Image Style Generate

Introduction

Image Style Generate allows a site administrator to quickly create image styles in bulk, based on a defined set of rules and patterns. It provides examples of how migrations can employ the module's capabilities.

Requirements

• Migrate: Image Style Generate leverages the Migrate module in Drupal core to create image styles.
• Image: The Image Style entity and Image Effect plugin type are defined by the Image module in Drupal core.

Recommended modules

• Migrate Plus: Enhances migrate functionality provided by Drupal core.
• Migrate Tools: Adds a UI and Drush commands for executing migrations.

Installation

Install as you would normally install a contributed Drupal module. See: https://www.drupal.org/node/895232 for further information.

Configuration of the module

The module itself has no settings.

Defining image styles to generate

Image Style Generate defines a source plugin for Migrate that allows configuration values in a migration definition to be used to generate image styles in bulk.

The first step to leveraging the module’s capabilities is to set image_style_generate as the source plugin within a migration definition:

source:
  plugin: image_style_generate

Then, within the source section, the following items may be defined:

Style groups

Style groups are top-level categories of image styles, often defined by an aspect ratio that is shared by all image styles in a style group. Here’s an example of a style group definition:

style_groups:
  landscape_3x2:
    label: 'Landscape 3:2'
    aspect_ratio: '3:2'

Style groups can be defined by an optional ID (landscape_3x2 in the example above). This is primarily useful within an ID pattern, but it can also be used just to provide clarity about the style group in the configuration definition.

Style groups can contain a label, an aspect ratio, and information about what dimension the base size value defines. If base_size_dimension is not defined (as in the example above), it's assumed to be the width of the image. A style group definition for image styles in a portrait orientation might look something like this:

style_groups:
  portrait:
    label: Portrait
    aspect_ratio: '3:4'
    base_size_dimension: height

All values in a style group, including the machine name, are optional. For instance, aspect_ratio would not be relevant to image styles that use an image effect just to constrain the width of the image, but not preserve its aspect ratio, so that can be left undefined. The same is true for label, if you don’t need it for a label pattern. An example of a minimal style group definition is this:

style_groups:
  -

Base sizes

Base sizes define which values should be used as a base for generating image styles that contain image effects that resize or scale an image. They may be defined in a specific style group or in defaults.

The following example defines two base sizes as defaults that will apply to all style groups (unless a base size is specifically overridden or removed within the definition for a style group).

defaults:
  base_sizes:
    - 160
    - 320

If you’d rather define your base sizes as multiples of a specific multiplier, set size_multiplier to the value you want to use, then base the base sizes off of that value. For example:

defaults:
  size_multiplier: 40
  base_sizes:
    - 4
    - 8

The definition above would result in the same styles being generated as in the previous example.

The base size values are multiplied by the defined size scales to produce the actual size values used within image effects.

Size scales

Size scales represent percentages of a base size to use when calculating an image size. These are generally used to map sizes to pixel densities supported by various devices. They may be defined in a specific style group, a specific base size, or in defaults. The example below defines three size scales that will apply to all style groups and base sizes (unless a size scale is specifically overridden or removed within the definition for a style group or base size).

size_scales:
  - 100
  - 150
  - 200

The scales map directly to pixel densities of 1, 1.5, and 2. Image styles generated for those sizes can then be used within a responsive image style definition to serve images appropriate for devices that support those specific pixel densities.

Image effects

Image effects that should be applied to style groups, base sizes, or size scales can be defined within each of those sections. Image effects that should be applied to all (or most) image styles should be defined in defaults. An image effect can be overridden or removed altogether in a style group, base size, or size scale. Here’s an example:

defaults:
  effects:
    image_scale:
      width: '{{width}}'
      height: '{{height}}'
      upscale: false

The definition above will cause the image_scale image effect to be applied to all image styles by default. Note that placeholders for width and height are used, since those values will vary for each image style being generated. Placeholders should be wrapped in double curly braces.

The definition for an image effect for Image Style Generate matches the contents of effects/data in an image effect in the configuration for an image style. For example, the definition for an image_scale image effect in an image style called image.style.large might look like this:

effects:
  ddd73aa7-4bd6-4c85-b600-bdf2b1628d1d:
    uuid: ddd73aa7-4bd6-4c85-b600-bdf2b1628d1d
    id: image_scale
    weight: 0
    data:
      width: 480
      height: 480
      upscale: false

Note how the effect definitions match. The easiest way to determine the structure for an image effect is to create an image style with that effect through the Drupal UI, then view the configuration at /admin/config/development/configuration/single/export, or export configuration and examine the appropriate file.

ID and label patterns

ID and label patterns provide templates for how the ID and label should be named. When defining them, consider the types of values that you might include if you were creating image styles manually through Drupal’s UI. Placeholders may be used for values that will vary for each image style. Here's a simple example:

defaults:
  id_pattern: 'max_width_{{width}}'
  label_pattern: 'Max width {{width}}'

For an image style that constrains images to a maximum width of 480, the resulting ID and label would be max_width_480 and “Max width 480”.

Here's a more complex example:

defaults:
  id_pattern: '{{group_id}}_{{size_padded}}_{{width}}x{{height}}_{{size_scale}}'
  label_pattern: '{{group_label}} - {{size}} ({{width}}x{{height}}) - {{size_scale_decimal}}x'

The following placeholder variables are available for use in ID and label patterns:

• size_multiplier
• group_id
• group_label
• base_size_dimension
• aspect_ratio
• aspect_ratio_width
• aspect_ratio_height
• base_size
• base_size_padded
• size
• size_padded
• width
• height
• size_scale
• size_scale_decimal

Image style IDs may only contain characters that are allowed in a machine name within Drupal (lowercase letters, numbers, and underscores) and must be unique. If an ID for an image style has already been created, the new image style definition will overwrite the old one. This can be used to your advantage to prevent creation of image styles with identical configuration.

Overriding definitions

Definitions may be overridden for specific style groups, base sizes, size scales, and image effects, with the following order of precendence:

• Default
• Style group
• Base size
• Size scale

For example, to add an additional base size of 960 for just the landscape_16x9 style group:

style_groups:
  landscape_16x9:
    label: 'Landscape 16:9'
    aspect_ratio: '16:9'
    base_sizes:
      - 960

Here's an example that allows upscaling for images, but only for the 2x size scale:

size_scales:
  100: {}
  200:
    effects:
      image_scale:
        upscale: true	

Another instance where you may want to override an image effect setting is to define different JPEG quality settings using the image_style_quality image effect provided by the Image Style Quality module.

defaults:
  effects:
    image_style_quality:
      quality: 60
  size_scales:
    100: {}
    150:
      effects:
        image_style_quality:
          quality: 45
    200:
      effects:
        image_style_quality:
          quality: 30
    300:
      effects:
        image_style_quality:
          quality: 20

You could really go crazy overriding values, but at a certain point, you’d probably be better off just creating additional migrations.

Preventing an image style from being generated

To prevent one or more image styles from being generated, set the appropriate value to false. For example, to prevent generation of all image styles in the “Square” style group with a base size of 480:

style_groups:
  square:
    label: Square
    aspect_ratio: '1:1'
    base_sizes:
      480: false

Examples

This module includes example migration files (in the Image Style Generate Example and Image Style Generate Example (Advanced) submodules) for examination and/or execution.