EarthBrain images

How to configure media sources, extend the base class and avoid problems.

Media sources

In order to avoid having to configure and maintain a media source for each kind of object, there is a default source that can be configured to generate separate source paths for different objects.

The media source name is Earth - Images, which has an arbitrary ID.

Note that some folders are symlinked inside a different container. Yes, that is a totally stupid idea, but it allows you to select images specific to that container (such as a forest) from its media source root, while also keeping the categories (such as plants) bundled together in 1 location.

Settings

The basePath and baseURL settings of the Earth - Images media source should be as follows:

[[earthObjectMediaPath? &pathTpl=`uploads/img/{category}/{parentId}/`]]

And you need to add the media source ID to the system setting earthbrain.img_source.

Resize on upload

You can specify a resizeConfigs property inside the media source (needs to be added manually!) with a value such as:

[{"alias":"origin","w":"3000","h":"2000","q":"85","zc":0}]

This will resize the image to fit within given limits, in order to save disk space.

Beware though: EXIF data is stripped in this process.

Adding an image class

Images are designed to extend a base earthImage class. So all images are stored in a single table, but refer to different parents with a combination of class_key and parent_id.

You can add an extended image as follows:

Add extended class to schema

<object class="earthImagePlant" extends="earthImage">
    <aggregate alias="Plant" class="earthPlant" local="parent_id" foreign="id" cardinality="one" owner="foreign" />
</object>

Include earthbrain_images TV in MIGX grid

The cover image is optional. You can include the image_id field in your object.

{
    "MIGX_id": 8,
    "caption": "Presentation",
    "print_before_tabs": "0",
    "pos": "",
    "fields": [
        "@@earthbrain/fields/images",
        {
            "MIGX_id": "",
            "field": "image_id",
            "caption": "Cover image",
            "description": "",
            "description_is_code": "0",
            "inputTV": "",
            "inputTVtype": "listbox",
            "validation": "",
            "configs": "",
            "restrictive_condition": "[[If? &subject=`[[+createdon]]` &operator=`empty` &then=`break`]]",
            "display": "",
            "sourceFrom": "config",
            "sources": "",
            "inputOptionValues": "@CHUNK tvSelectEarthOption@ComponentImage",
            "default": "",
            "useDefaultIfEmpty": "0",
            "pos": ""
        }
    ]
}

Configure source path

By default, you can reuse the Earth - Image media source, which will automatically generate a base path to the correct folder. For this to work, it needs to know which category belongs to which MIGX config.

To hook up the media source, go to the earthObjectMediaPath snippet and add a switch case to the existing list, with the appropriate category values. If you want to create a symlink also, make sure to define a symCategory value as well. See code for further documentation and examples.

Define class key

Because the earthbrain_images TV is also reused in MIGX grids, it needs to know which parent grid it is nested in. The necessary configuration is defined in the migxGetClassKeys snippet.

Add the appropriate class key in a switch case there. And as you will see, it works the same if you want to attach EarthBrain notes or links to your object.

If set correctly, the image grid will only show images connected to the object. If you're seeing a lot more images than expected, then something went wrong.

Troubleshooting

Media sources are notorious for becoming a big pain in the bumsers. When not configured correctly from the start, you could end up with thousands of images scattered around your project some day. Everything can be fixed of course, but probably not without waging some terrible find & replace war.

I see them as a necessary evil though, if you wish to organize your images in a predictable manner. The problems that arise from using media sources outweigh the random mess that will surely accumulate by not having them.

Incorrect image paths in MIGX grids

When you get the error "The image was not found and can’t be cropped. Please select a different image.", it means that the media source path was not correctly generated.

This can have several reasons:

• The baseUrl in the media source settings itself is incorrect. It should be the same as the basePath.
• You are editing multiple objects, and every new object you edit inherits the path of the first object. You can see this happening in the inspector. Clearing cache and a page refresh solves this. If you refresh the page, you're able to update the last edited object.

https://github.com/Jako/ImagePlus/issues/112

It turns out this bug was introduced somewhere in Image+ version > 2.9. Reverting to 2.8.9 solves these issues for now.