Bolt CMS BetterThumbs Extension

Installation
Example Setup
Quick Use
Template Usage
Advanced Usage
Source

This is a Bolt Content Management System extension that enables you to use a twig tag to produce responsive images using srcset and also use Glide which is backed by the image manipulation library Intervention

This extension creates responsive images by default, secures thumbnail URL's to prevent unwanted modifications, allows images to be deleted individually from the cache or all at once, and to generate images and place those into the cache before hand. You also have an option to use a PHP-Imagick (imagemagick) as the driver to produce your image thumbnails.

Installation

In the backend of your Bolt install navigate to the "Extras" menu in your dashboard and click "view/install extensions". In the "Install New Extension" search box type either "Responsive Images" or paste the following snippet.

cdowdy/betterthumbs

Then click "Browse Versions and install the latest stable version.

Examples Setup

For the examples on this page I will be using a rule set I have created in the extensions config titled - betterthumb_demo.

Each image set will need a config defined in the extensions config file. One is already there called 'betterthumbs'. This has all the needed areas for a responsive image set and uses the extensions preset defaults.

For a custom set of rules start off by giving the rule set a name inside the config. This pages rule set as mentioned above is 'betterthumb_demo'. Here is this demo page rule set as defined in the extensions config.

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
    medium:
      w: 520
    large:
      w: 900

If your named config is short like the one above you can use hashes instead like as follows:

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small: { 'w': 320 }
    medium: { 'w': 520 }
    large: { 'w': 900 }

For this particular page I know that on screens wider than 50em (800px) the image will be approximately 30% of the viewport ( taking into consideration the column padding/gutters ). To help you get you head around this you can read Jake Archibald's Anatomy of Responsive Images.

Quick Usage

You can quickly use BetterThumbs in your templates by using the extensions defaults, which also happen to be the presets. You can change these presets to your own if you so wish.

{{ img( record.image, 'betterthumbs' ) }}

This will produce four (4) images with the settings found in 'presets'

redpanda-eric_kilby — Red Panda By Eric Kilby

Using Widths

By default this extension uses the width descriptor for the images. In the 'betterthumb_demo' config shown above that means the widths used are the numbers after each modifications section 'w:' section.

Usage examples for using the "w" descriptor.

To use the W descriptor either use the default settings "widthDensity" setting of "w" or create your own set of rules with the widthDensity setting set to w in that rule set.

We'll use the config defined above in the "Config" section.

Template Usage

Using with a record image

{{ img( record.image, 'betterthumb_demo' }}

Using with a File From Files

{{ img( 'demos/betterthumbs/redpanda-eric_kilby.jpg', 'betterthumb_demo' }}

Using Densities

To use screen densities with the extension use an 'x' in the 'widthDensity' config setting. The 'sizes' config option isn't needed if using the 'x' descriptor but the 'resolutions' option is. The 'x' descriptor is also good to use with fixed width images. More on why fixed width images can be found here at Cloudfour Blog: Responsive Images 101 Display Density.

Config:

betterthumb_density:
  widthDensity: 'x'
  resolutions: [ 1, 2, 3 ]
  modifications:
    small:
      w: 320
    medium:
      w: 640
    large:
      w: 900

Using with a record image

{{ img( record.image, 'betterthumb_density' }}

Using with a File From Files

{{ img( 'demos/betterthumbs/redpanda-eric_kilby.jpg', 'betterthumb_density' }}

Using Image Effects & Filters

Usage examples of the sepia and greyscale filters along with the pixelate and blue effects.

Sepia Filter

Sepia Config setup up and examples

moon-bear-portrait — Moon Bear Portrait By Eric Kilby

Config:

betterthumb_sepia:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      filt: 'sepia'
    medium:
      w: 520
      filt: 'sepia'
    large:
      w: 900
      filt: 'sepia'

Greyscale Filter

Greyscale Config setup up and examples

Config:

betterthumb_grey:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      filt: 'greyscale'
    medium:
      w: 520
      filt: 'greyscale'
    large:
      w: 900
      filt: 'greyscale'

Pixelate Filter

Pixelate Config setup up and examples

Config:

betterthumb_pixelate:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      pixel: 8
    medium:
      w: 520
      pixel: 8
    large:
      w: 900
      pixel: 8

Blur Filter

Blur Config setup up and examples

Config:

betterthumb_blur:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      blur: 5
    medium:
      w: 520
      blur: 5
    large:
      w: 900
      blur: 5

Adjusting Images

Usage examples of the image adjustments of, gamma correction, and adjusting the sharpness, contrast and brightness of images.

Brightness Adjustments

Brightness Config setup up and examples

milky-way — Milky Way Above Bend in Forested Shoreline By Eric Kilby

Config:

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      bri: 25
    medium:
      w: 520
      bri: 25
    large:
      w: 900
      bri: 25

Sharpness Adjustments

Sharpness Config setup up and examples

Config:

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      sharp: 15
    medium:
      w: 520
      sharp: 15
    large:
      w: 900
      sharp: 15

Contrast Adjustments

Contrast Config setup up and examples

Config:

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      con: 25
    medium:
      w: 520
      con: 25
    large:
      w: 900
      con: 25

Gamma Adjustments

Gamma Config setup up and examples

Config:

betterthumb_demo:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
      gam: 1.5
    medium:
      w: 520
      gam: 1.5
    large:
      w: 900
      gam: 1.5

Advanced Usage

You can over ride just about any default setting or user supplied setting in the extensions config inside a template. You must supply the image you wish to use, followed by a rule set (or use defaults) then followed by which custom settings you wish to use.

In the image effects and filters examples above the code blocks follow a pattern of <name>_<filter/effect name> . This isn't practical for configs using a lot of the same settings. So behind the scenes I cheated a bet. I created a config section that only contained the widths of the images. Then in the template I added in what I need for that filter or effect.

Here is that config block:

betterthumb_filters:
  sizes: [ '(min-width: 800px) 30vw', ' 90vw' ]
  modifications:
    small:
      w: 320
    medium:
      w: 520
    large:
      w: 900

Then we override / add in things we want for that particular image. The examples below show you how this is accomplished in a template. The markup is kinda verbose so you may want to use this sparingly.

Template Usage

Template Override Examples

Override Default Width Settings

{{ img( 'demos/betterthumbs/milky-way.jpg', 'betterthumb_filters', {
  'modifications': {
    'small': { 'w': 400 },
    'medium': { 'w': 640 },
    'large': { 'w': 1000 }
  }
}) }}

Override The Default widthDensity Descriptor. Add in Density

{{ img( 'demos/betterthumbs/emmi-pemmi.jpg', 'betterthumb_filters', {
          'widthDensity': 'x',
          'resolutions': [ 1, 2, 3 ],
        }) }}

Using a generic config and adding in a filter

{{ img( 'demos/betterthumbs/emmi-pemmi.jpg', 'betterthumb_filters', {
  'modifications': {
    'small': { 'filt': 'sepia' },
    'medium' : { 'filt': 'sepia' },
    'large' : { 'filt': 'sepia' }
  }
}) }}

Using presets

McKinleyMemorial — McKinely Memorial, Canton, Ohio by Eric Kilby

{{ img( 'demos/betterthumbs/McKinleyMemorial.jpg', 'presets') }}

Overriding Presets

Since presets are settings used for each and every image that gets modified they are a little harder to override. If you wish to override this you should create a named config block. That way if you want to add in a class, data-attribute, use an ID or use density descriptors it's easier to do so. There is already a named config block set up for this purpose titled "betterthumbs". This uses yaml's repeated nodes so you don't have to repeat the preset settings. Here is how you would override these presets in a named config.

The Preset Config block:

presets: &presets
  small:
    w: 175
    fit: stretch
  medium:
    w: 350
    fit: stretch
  large:
    w: 700
    fit: stretch
  xlarge:
    w: 1400
    fit: stretch

The named config inheriting the Preset config

betterthumbs:
  save_data: true
  altText: ~
  widthDensity: 'w'
  sizes: [ '100vw' ]
  modifications:
    <<: *presets

Usage

Here we can override or add to our presets anything available in the Glide API. So for example purposes we will add a new fit to the "large" modifications array along with a new width. We will also add a class for this specific image, a data-attribute and just to round things out an ID. Everything else will be exactly the same as the preset config block. Open up your dev tools and inspect the image too see the rendered options applied to the image tag.

white_rhino — White rhino by US Fish & Wildlife Services

The twig over rides

{{ img( 'demos/betterthumbs/white_rhino.jpg', 'betterthumbs', {
  'class': [ 'Template_Class' ],
  'id' : 'MyCoolId',
  'data_attrib': { 'rhino-type' : 'white' },
  'modifications': {
    'large' : { 'w': 800, 'fit': 'max' }
  }
}) }}

Can we take a moment and think about this animal? This thing actually exists! Well... struggling to exist but it does. It's pretty remarkable. According to the World Wildlife Foundation there are only 3 of these left in existence and all are in captivity. Which in itself is extremely sad. People are wiping this thing out for its horn which would be the same thing as eating your own fingernails and or hair for keratin.

Source

The source for Bolt BetterThumbs can be found at my github page

Github Source: Bolt BetterThumbs

Bolt BetterThumbs Store Page

Bolt Store: Bolt BetterThumbs