Defining Image Size and Crop Presets

Note: Where you see ~ in a file path, it refers to the current folder for a given website and assumes you are using global_design_mode_theme as the main theme with the theme_merge system for customisation. For example /sites/YOURSITE/theme_merge/settings/image_sizes.json is the same as ~/settings/image_sizes.json

You can define any number of image size presets which your clients can assign to their images when they add them in the CMS. This avoids the need to get people working with the CMS to resize their images before uploading, or even remember any dimensions and ratios at all.

Image size presets are applied to images when editing a page in the CMS. Once an image has been added to a page it can be selected, the click on Styles, then choose one of the size presets from the menu to apply it.

The image resize system allows the following type of sizes:

  • Scale by width and height and crop to fit
  • Scale by width and height and constrain to fit
  • Scale by width only
  • Scale by height only

The sizes are defined in the ~/settings/image_sizes.json file. There is also a version of this file that is used for emails called image_sizes_email.json. This is a JSON formatted file and an example with 4 different image sizes would look like this:

If the file doesn't exist in your theme you can create it. The CMS will use a default collection of three sizes in the absence of this file.

[
    {
        "name":"Small"
        ,"width": "120"
        ,"height": "auto"
    }
    ,{
        "name":"Medium"
        ,"width": "200"
        ,"height": "200"
        ,"shrink":"false"
        ,"default": "true"
    }
    ,{
        "name":"Large"
        ,"width": "300"
        ,"height": "auto"
    }
    ,{
        "name":"Extra Large"
        ,"width": "800"
        ,"height": "auto"
    }
]

Let's look at the options one by one:</code>

"name"
This is the display name that represents the size present. This is what your clients will see in the Styles menu within the CMS.

"width"
This is the width value for the image. It can be "auto" or a pixel value. If the value is set to "auto" the "height" value must be a pixel value.

"height"
This is the height value for the image. It can be "auto" or a pixel value. If the value is set to "auto" the "width" value must be a pixel value.

"shrink"
This is a boolean option which stipulates if the image should be cropped or constrained within the dimensions. It's default value is "true" which means images will be constrained within the dimensions. Setting the value to "false" will only work if both the "width" and "height" values are set to a pixel value. If "shrink" is set to "false", images will be cropped to fit the dimensions exactly. Cropping will occur with the image centred. Images will be scaled to fit as closely as possible so cropping is minimised.

"default"
One of the size definitions must have "default" set to "true". This makes this size the default size for all images when they are added to a page in the CMS.

Search