Brightspot CMS Developer Guide

Defining image sizes


This section provides information on how to define image sizes at the theme level, module level, and more.


Image sizes are defined in the configuration file (see Configuring a theme) of your theme. To define an image, you will at a minimum need to define the width (or maximumWidth) and height (or maximumHeight).

An example configuration file with a single image size definition would look like the following:

{
  "imageSizes": {
    "MyImageSize": {
      "width": 100,
      "height": 100
    }
  }
}

See also:


You can define image sizes at the module level, overriding image sizes at the theme level. You can use all of the keys listed in the table Keys for image size in module-level data files except the following:

previewWidth and previewHeight at the module level

Key
Description
Type
previewWidth

This key is available at the module level only if the following are true:

  • previewWidth is present in the theme’s _config.json for the same template.
  • width is not present in the theme’s _config.json for the same template.
Number
previewHeight

This key is available at the module level only if the following are true:

  • previewHeight is present in the theme’s _config.json for the same template.
  • height is not present in the theme’s _config.json for the same template.
Number

The following snippet describes the height, width, and source set descriptors for a templateImage.hbs. These attributes override any of the contextual rendering settings in the theme’s _config.json.

{
  "_template": "Image.hbs",
  "height": "900",
  "width": "1600",
  "srcsetDescriptors": [
    "2x",
    "3x"
  ]
}

See also:


The following table lists the available properties when defining an image size.

Keys for image size

Key
Description
Type
width
Width of rendered image in web page and generated image representation in Styleguide.
Number
height
Height of rendered image in web page and generated image representation in Styleguide.
Number
previewWidth
If width not set, width of image representation in Styleguide. Do not set previewWidth if width is set.
Number
previewHeight
If height not set, height of image representation in Styleguide. Do not set previewHeight if height is set.
Number
maximumWidth
Maximum width of image size. Aspect ratio will be preserved by the resize. If you define maximumWidth, you must also define previewWidth; otherwise, you will get an error.
Number
maximumHeight
Maximum height of image size. Aspect ratio will be preserved by the resize. If you define maximumHeight, you must also define previewHeight; otherwise, you will get an error.
Number
srcsetDescriptors
A list of image density or width descriptors to support different device screen resolutions. For more information, see srcSetDescriptors.
Array of String
format
Specifies the format in which an image is delivered to the client. For more information, see Image format.
String
group
Heading under which an image size appears in the image editor. For more information, see Grouping images in the image editor.
String
displayName
Customized label for an image size in the image editor. For more information, see Image size display names.
String
quality
Specifies an image’s visual quality and compression level at run time.
Number

See also:


Brightspot’s image editor lists the image sizes as they appear in the theme’s configuration file _config.json.

{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765
    }
  }
}

In the previous snippet, Brightspot displays the names square-small-62x6, square-medium-84x84, and square-large-765x765.

You can provide a more intuitive name for each image size using the displayName key.

{
  "imageSizes": {
    "square-large-765x765": {
      "width": 765,
      "height": 765,
      "displayName": "Huge Square" 
    },
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "displayName": "Small Square" 
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "displayName": "Medium Square" 
    }
  }
}
  • Custom name for the image size square-large-765x765.
  • Custom name for the image size square-small-62x62.
  • Custom name for the image size square-medium-84x84.

The following illustrations provide examples default and customized image-size names.

Default image-size names.svg Default image-size names.svg
Default image-size names
Customized image-size names.svg Customized image-size names.svg
Customized image-size names


Editors can set a focus pointon images. If your theme has many image sizes and orientations, the editors may want to place the focus point in different locations.

Focus point on portrait orientation.svg Focus point on portrait orientation.svg
Focus point on portrait orientation
Focus point on square orientation.svg Focus point on square orientation.svg
Focus point on square orientation


Referring to the previous illustrations, the focus point is in the bottom-right quadrant of the portrait image; in comparison, the focus point is in the top-left quadrant of the square image.

If you have multiple images with the same aspect ratio, the focus point is always in the same place, scaled for the image size. For example, if an image is 1000 × 500 with a focus point at (100, 250), and another image is 2000 × 1000, the focus point for the second image is scaled to (200, 500). This implies that an editor can set a focus point once for all images with the same aspect ratio, and Brightspot scales the focus point when performing crops.

You can group images into the same or similar aspect ratio using the group key under imageSizes.

{
  "imageSizes": {
    "80x80": {
      "width": 80,
      "height": 80,
      "group": "square" 
    },
    "100x100": {
      "width": 100,
      "height": 100,
      "group": "square"
    },
    "150x100": {
      "width": 150,
      "height": 100,
      "group": "landscape" 
    }
}
  • Groups images under a label Square in the image editor.
  • Groups images under a label Landscape in the image editor.

When detecting at least one group key in the theme, Brightspot displays a selection field containing all of the groups.

Group selector.svg Group selector.svg
Group selector

When an editor selects one of the groups and sets a focus point, Brightspot applies and scales the focus point to all associated image sizes.


By default, Brightspot delivers images to a client in the format in which they are stored. For example, if you upload an image as a PNG, Brightspot delivers the image in the same format.

You can force Brightspot to deliver images of a given size in a given format—regardless of the format in which the image is stored. This feature is useful if you ingest or upload multiple images in one format, and want to deliver them to the browser in a different format. (If your travel editor took one thousand jaw-dropping photographs during a safari and uploaded them to Brightspot as PNGs, you can force Brightspot to convert the images to JPGs.)

The following table lists the available formats.

Available image formats

Extension Name
png, x-png Portable Network Graphic
gif Graphics Interchange Format
jpg, jpeg Joint Photographic Experts Group
webp Web Picture Format
bmp Bitmap
svg Scalable Vector Graphics
tiff, x-tiff Tag Image File Format


This feature is available if you configured DIMS as the image editor; for details, see Image editor configuration.

You can use any of the extensions in the table above with the format key inside the elements of an imageSizes array.

{
  "imageSizes": {
    "small": {
      "format": "jpg" 
    }
  }
}
  • Delivers as jpg all usages of the small image size.

Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.

File converter in URL.svg File converter in URL.svg
File converter in URL

Referring to the previous illustration, Brightspot constructs an image’s src attribute from the original file’s name bowtie.png and an instruction to an online service for conversion to the jpg format. When the browser submits this request to the server, the image editor performs the conversion.

See also:


Fixed image size

Setting both width and height dimensions results in a fixed image size. A fixed image size may result in cropping if the image size does not reflect the aspect ratio of the original image.

The following image-size snippet defines a square shape, with equal width and height dimensions.

{
  "imageSizes": {
    "square-medium-200x200": {
      "width": 200,
      "height": 200
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, with a 2:1 aspect ratio, the result is a 200×200 square image that is cropped because the image size does not reflect the aspect ratio of the original image. Brightspot first creates an image rendition that maintains the aspect ratio of the landscape image. In this example, the ratio is 2:1, so Brightspot resizes the image to 400×200. Brightspot then crops the width of the rendition to fit it into a 200×200 image size.

200x200 square.png 200x200 square.png
200x200 square

The next image-size snippet defines a landscape shape, with the width greater than the height.

{
  "imageSizes": {
    "landscape-large-500x250": {
      "width": 500,
      "height": 250
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a scaled-down landscape image. The image is also uncropped because the image size reflects the aspect ratio of the original image, 2:1.

The next image-size snippet defines a portrait image, with the height greater than the width.

{
  "imageSizes": {
    "portrait-medium-200x400": {
      "width": 200,
      "height": 400
    }
  }
}

If the snippet is applied to a 1000×500 landscape image, the result is a 200×400 portrait image. Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 800×400, which is the image rendition. To fit the image into a portrait-oriented size, Brightspot crops the width.

Applying portrait image style to landscape image.png Applying portrait image style to landscape image.png
Applying portrait image style to landscape image


As an alternative to a fixed image size, you can have Brightspot calculate the size by specifying only one image dimension, width or height, or by using width or height in conjunction with a maximumHeight or a maximumWidth key. As in a fixed image size, Brightspot creates an image rendition based on the aspect ratio of the image, but Brightspot does not crop the rendition to fit a fixed size. In essence, the image rendition dimensions determine the image size.

The maximumWidth and maximumHeight keys can restrict the width or height of an image while preserving the aspect ratio. For example, say that you have a 1000×500 landscape image, with a 2:1 aspect ratio. The following snippet specifies that the resulting image size not exceed a height of 200.

{
  "imageSizes": {
    "auto-small-400xauto": {
      "width": 400,
      "maximumHeight": 200,
      "previewHeight": 200
    }
  }
}

Maintaining the 2:1 aspect ratio, Brightspot resizes the image to 400×200, which is the image rendition. Because the computed height does not exceed maximum height, the resulting image size is 400×200.

Image with aspect ratio maintained.png Image with aspect ratio maintained.png
Image with aspect ratio maintained

Using the width and previewHeight values, Styleguide generates a 400×200 image representation.

Styleguide image preview.png Styleguide image preview.png
Styleguide image preview

If the image size defined in the above snippet is applied to a 500×500 square image, with a 1:1 aspect ratio, the resulting image size is different. Maintaining the 1:1 aspect ratio of the image, Brightspot initially computes a height of 400, which exceeds the maximum height. Brightspot then resizes the image to 200×200 to maintain aspect ratio. (In Styleguide, the image is represented with a 400×200 size.)

200x200 image.png 200x200 image.png
200x200 image



To accommodate image display on devices with different resolutions, the srcsetDescriptors key specifies density descriptors or width descriptors. This key provides support for the HTML srcset attribute. Brightspot generates images of different densities or widths, and the browser determines the applicable image based on the device screen resolution or viewport size.

Note
You cannot combine width descriptors and density descriptors.

Use density descriptors for images that should maintain the same width across devices, but should vary by resolution to support displays with different pixel densities. For example, the following image snippet specifies a density array of 2x and 3x.

{
  "imageSizes": {
    "landscape-small-300x200": {
      "width": 300,
      "height": 200,
      "srcsetDescriptors": [
             "2x",
             "3x"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag:

<img src="src.png" srcset="src-2.png 2x, src-3.png 3x" />

Use width descriptors for images that are likely to change in width, especially in responsive designs. With width descriptors, images vary in width based on the size of the viewport.

For example, the following image snippet specifies a width array of “1000w” and “2000w”.

{
  "imageSizes": {
    "auto-large-autox1000": {
      "maximumWidth": 2000,
      "previewWidth": 2000,
      "height": 1000,
      "srcsetDescriptors": [
             "1000w",
             "2000w"
       ]
    }
  }
}

This results in the following srcset attribute in the HTML image tag. If the viewport is 1000 pixels wide or smaller, the image will be 100% of the viewport width, and the browser will use the src-1000.png image. If the viewport is wider than 1000 pixels, the browser will use the src-2000.png image.
<img src="src.png" srcset="src-1000.png 1000w, src-2000.png 2000w" sizes="(max-width: 1000px) 100vw, 2000px" />


Images you upload to Brightspot can appear differently in different places on the front end. The image may have the native size in some pages, and appear larger or smaller in other pages. Brightspot selects the image size to send to the front end based on the image’s context—a combination of template and placeholder.

{
  "imageSizeContexts": { 
    "/styleguide/Image.hbs": { 
      "image": "large" 
    }
  }
}
  • Stanza within _config.json that contains image context definitions.
  • Template.
  • Placeholder.

Referring to the previous example, the context is the placeholder {{image}} within the template Image.hbs. In this context, Brightspot uses the image size large.

You can define levels of nested context, a technique that promotes template reuse.

{
  "imageSizeContexts": {
    "/styleguide/ByLine.hbs": {
      "/styleguide/Image.hbs": {
        "image": "small"
      },
      "/styleguide/BioPage.hbs": {
        "/styleguide/Image.hbs": {
          "image": "large"
        }
      }
    }
  }
}


In the previous example, there are two contexts for the template Image.hbs:

  • One context for a byline under the template ByLine.hbs. In this context, Brightspot provides the image size small to the front end.
  • One text for a bio page under the template BioPage.hbs. In this context, Brightspot provides the image size large to the front end.


You can assign an image size to multiple contexts using file globbing.

{
  "imageSizeContexts": {
    "/styleguide/*.hbs": {
      "image": "large"
    }
  }
}

In the previous example, Brightspot uses the image size large in any template whose file name matches the pattern /styleguide/*.hbs. For details about the supported patterns, see Glob Primer.

See also:


After you define image sizes (see Defining image sizes), you can use the {{resize}} helper to apply a resize to an image object. In a Brightspot theme, rendering an <img>tag should almost always include a usage of the {{resize}} helper.

Basic usage
As a simple example, suppose a component MyComponent.hbs that renders an <img> with an image size named small.

MyComponent.hbs

{{#resize image "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}


Container usage
A container will often need to define an image size used by its children.

Container.hbs

{{include "Item.hbs" child imageSize="large"}}

Item.hbs

{{#resize image imageSize}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}


Providing a fallback
To decouple Item.hbs from Container.hbs, you may want to provide a fallback for when an imageSize property is not specified by a container, or there is no container at all.

Item.hbs

{{#resize image (fallback imageSize "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

In the above example, Item.hbs will render using the small image size, unless a container specifies an imageSize value.

Images with variable helpers
There may be times when the immediate container does not specify the image size necessary. Consider an example in which Page.hbs renders a Container.hbs of Item.hbs, and Page.hbs determines which image size to use.

This could be implemented by passing down the image size through multiple templates:

Page.hbs

{{include "Container.hbs" container itemImageSize="large"}}

Container.hbs

{{include "Item.hbs" child imageSize=itemImageSize}}

Item.hbs

{{#resize image imageSize}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}

However, this quickly becomes unwieldy when you need to pass the image size through multiple contexts. To facilitate these scenarios, you can use the {{get}} and {{set}} helpers.

Page.hbs

{{#set imageSize="large"}}
    {{include "Container.hbs" container}}
{{/set}}
Item.hbs

{{#resize image (get "imageSize")}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}
Container.hbs

{{include "Item.hbs" child}}


Variables with fallback images
You may also wish to define a fallback for when the image size is not specified, using the {{fallback}} helper:

Item.hbs

{{#resize image (fallback (get "imageSize") "small")}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}" />
{{/resize}}



This section describes the steps for diagnosing and resolving the most common causes of blurry or missing images in published content.

The techniques described in this section assume you are using the Frost theme, which adds a srcset attribute to <img>tags. In other scenarios, you can use similar techniques to identify the cause of a blurry image.

Troubleshooting blurry images

The following steps help to identify the cause of a blurry image on a published page.

Step 1: Check native image’s size
Brightspot displays images in different sizes depending on the context. If the editor uploaded a very small image, Brightspot likely enlarges it, resulting in a blurry presentation.

Native image.jpeg Native image.jpeg
Native image
Image in author's byline.jpeg Image in author's byline.jpeg
Image in author's byline
Image on author's bio page.jpeg Image on author's bio page.jpeg
Image on author's bio page


Referring to the previous examples, the native image is small, 65 × 65 pixels. The image in the byline is 100 ×100, and in the bio page 240 × 240. At each level of zoom, Brightspot needs to fill in pixels, resulting in a blurry effect.

The best way to check a native image’s size is to view it in a browser or graphic editor. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To view a native image:

  1. In a published page, right-click the blurry image, and select Inspect from the popup menu.
  2. In the Elements tab, right-click the img element and select Copy > Copy element.
  3. Paste the element into a text editor.

    • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
    • Each entry in the srcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
      Native image URL encoded.svg Native image URL encoded.svg
      Native image URL encoded
  4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
  5. Paste the decoded URL into your browser. The image you see is the native image uploaded by the editor.

Result:

  • If the image is small, the blurries are due to enlarging the image. Inform the editor to upload a larger image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
  • If the native image size is large, the blurries are due to another reason. Save the native image to your local drive, and continue to the next step.

Step 2: Check quality of native image
View the native image you saved in Step 1: Check native image’s size in your browser.

Result:

  • If the native image is blurry, then no amount of editing (either by Brightspot or by a graphic artist) can make it crisp. Inform the editor to upload a different image.
  • If the image is crisp, the blurries are due to another reason. Continue to the next step.

Step 3: Check native image’s pixel density
Images taken with a low-ppi camera or created on a low-ppi monitor appear blurry on high-ppi screens.

Open the native image in a graphic editor and view the ppi, or use the ImageMagick command identify -format “PPI (x,y): %x x %y\n” filename.ext.

Result:

  • If the native image’s ppi is much smaller than that of the monitor, the client device is adding pixels to compensate, resulting in a blurry image. Inform the editor to upload a higher ppi image, ideally three times the size of the largest size listed in srcset. (Uploading an image this size allows devices with pixel-density ratios up to 3 to display images without introducing the blurries.)
  • If the native image’s ppi is close to that of the native image, search for blurry images on the Internet for other possible resolutions.

Troubleshooting missing images

Images uploaded to Brightspot can be missing in the preview pane or in a published page. The following steps help to identify the cause of a missing image.

Step 1: Check native image’s URL


Ensure the native image’s URL is valid. The following instructions apply to the Chrome browser; the procedure for other browsers is similar.

To verify a native image’s URL:

  1. In a published page, right-click the missing image, and select Inspect from the popup menu.
  2. In the Elements tab, right-click the img element and select Copy > Copy element.
  3. Paste the element into a text editor.

    • The element contains a srcset attribute for displaying different image sizes on different pixel densities.
    • Each entry in the srcset attribute has the form DIMSurl?NativeImageURLEncoded, as in the following illustration.
      Native image URL encoded.svg Native image URL encoded.svg
      Native image URL encoded
  4. Copy and paste the encoded URL into a decoder, such as URL Decoder.
  5. Paste the decoded URL into your browser.

Result:

  • If the image is missing (error 404), or if the URL points to something other than an image, then inform the editor to upload a new image.
  • If the URL appears in your browser, continue to the next step.

Step 2: Check native image’s format
Before delivering an image to a client, Brightspot performs some edits, such as cropping and resizing. On some versions of Brightspot, these operations fail on TIFFs. Use the following procedure to determine if this failure is occurring on your version of Brightspot.

  1. Examine the URL you pasted into the text editor in Step 1: Check native image’s URL. Does the native URL have a .tifor .tiff extension?
    Examine the URL.svg Examine the URL.svg
    Examine the URL
  2. Is there a path parameter format/jpg?

Result:

  • If the answer to 1 is Yes and the answer to 2 is No, then the conversion from TIFF to JPG is failing, and the image appears as if missing. Do one of the following:

    • Inform the editor to convert the image to JPG, PNG, or GIF and upload the image again.
    • Update your theme to include the conversion from TIFF to JPG, PNG, or GIF.
  • In all other cases, continue to the next step.

Step 3: Check for zero-width crops
Some previous versions of Brightspot intermittently injected zero-width crops.

  • Examine the URL you pasted into the text editor in Step 1: Check native image’s URL.

Result:

  • If there is a path parameter crop/0x0+0+0, contact your Brightspot representative to receive a patch.
  • If there is no crop parameter or if the crop parameter has reasonable dimensions, continue to the next step.

Step 4: Check for access to native image from the DIMS server
At run time, the DIMS server retrieves the native image, performs graphic editing, and delivers the modified image to the client. In this step, you verify the DIMS server has access to the native image.

To check for DIMS access:

  1. SSH in to the DIMS server.
  2. Use curl or wget to retrieve the missing image, pasting the decoded URL from Step 1: Check native image’s URL into the command line.

Result:

  • If the request from the DIMS server fails, perform network debugging to resolve the error. Typical causes are firewalls, timeouts, and allowed/blocked access control.
Previous Topic
Image sizes
Next Topic
Resource bundles - Theme Guide
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Modules
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Dashboards
Publishing
Workflows
Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
Images
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Shopify
Apple News