Configuration / Thumbnails

Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?

Bolt comes with a thumbnail system which allows you to scale and crop your images. This is particularly useful if images need to fit into a specific layout. The reduced file size can also increase the performance of your site.

The thumbnail settings are defined in config.yml under the thumbnails key. Here is an example with the default settings:

thumbnails:
    default_thumbnail: [ 160, 120 ]
    default_image: [ 1000, 750 ]
    quality: 80
    cropping: crop
    notfound_image: bolt_assets://img/default_notfound.png
    error_image: bolt_assets://img/default_error.png
    save_files: false
    allow_upscale: false
    exif_orientation: true
    only_aliases: false
#    browser_cache_time: 2592000

Settings¶

Thumbnail Aliases¶

With thumbnail aliases, you can define thumbnail sizes which are specific for your theme, like a teaser or cover thumbnail. This not only makes them easy to change at any time, but also prevents people from flooding your cache or server space with automatically generated thumbnails.

Defining Thumbnail Aliases¶

Because thumbnail aliases are very theme specific, they will be defined in the theme.yml of your theme.

Here is a little example with a teaser and a cover alias:

thumbnails:
    aliases:
        teaser:
            size: [400, 300]
            cropping: crop
        cover:
            size: [600, 400]
            cropping: crop

As you can see, each alias has a new setting called size where you define the width and the height of the thumbnails. You can also define how they will be cropped.

Basic usage is straightforward:

{{ record.image|thumbnail(400, 300, 'c') }}

becomes:

{{ record.image|thumbnail('teaser') }}

For further examples on how to use the thumbnail alias with your code, please see the template tag documentation.

Preventing non-alias Thumbnails¶

With the only_aliases setting in the general thumbnail configuration, you can prevent the generation of thumbnails that don't belong to an alias. This is useful to secure your server from automatically generated thumbnails that could flood your cache.

When developing a site with this feature turned on, there are two things to note:

• If you're logged on, thumbnails not using an alias will still work. Test them 'incognito', or when logged off.
• Images that are already generated might still be served from cache. Flush the cache, if you're seeing stale images.