Defining Image Size and Crop Presets

Develop

Share this page: Facebook LinkedIn Pinterest Twitter

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

In the CMS, you have the flexibility to define a range of image size presets that clients can assign to their images when adding them. This eliminates the need for users to resize their images before uploading or remember specific dimensions and ratios.

To apply image size presets, simply edit a page in the CMS, select the desired image, click on 'Styles,' and choose a size preset 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.