Available Properties

Below is a table of the supported properties when defining an 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 Aspect Ratios in the Image Editor. String
displayName Customized label for an image size in the image editor. For more information, see Preparing an Image for Publication. String
quality Specifies an image’s visual quality and compression level at run time. Number

Image Format

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 and their suggested uses.

Available Image Formats
Extension Name Suggested Use
png Portable Network Graphic Transparency.
gif Graphics Interchange Format Animation, small images with fewer than 256 colors.
jpg Joint Photographic Experts Group All other uses.

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 Available Image Formats with the format key inside the elements of an imageSizes array.

1
2
3
4
5
6
7
{
  "imageSizes": {
    "small": {
      "format": "jpg"
    }
  }
}

In the previous snippet, line 4 configures Brightspot to deliver as jpg all images whose context is small. (For an explanation of determining an image’s context, see Context.) Brightspot delivers the file by retrieving the original file and running it through a file converter as indicated in the following URL.

../../_images/target-online-image-format.svg

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:

Image URLs

Grouping Aspect Ratios in the Image Editor

Brightspot’s image editor lists all of the image sizes available for the current theme, automatically grouping them by aspect ratio. The labels appearing in the list are elements of the imageSizes key in the theme’s configuration file _config.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765
    },
     "landscape-small-54x50": {
      "width": 54,
      "height": 50
    }
  }
}

In the previous snippet, Brightspot identifies all of the image sizes with an aspect ratio of 1:1, and groups the corresponding labels in lines 3, 7, and 11 in the image editor. See the left image in the table Grouping Images by Aspect Ratio.

You can provide a more intuitive label for aspect-ratio groupings using the group key. With this key, Brightspot provides only one entry for each aspect ratio. You can also provide group labels that give editors a cue when the image size appears, such as Promo Size.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "imageSizes": {
    "square-small-62x62": {
      "width": 62,
      "height": 62,
      "group": "1:1"
    },
    "square-medium-84x84": {
      "width": 84,
      "height": 84,
      "group": "1:1"
    },
    "square-large-765x765": {
      "width": 765,
      "height": 765,
      "group": "1:1"
    },
     "landscape-small-54x50": {
      "width": 54,
      "height": 50,
      "group": "1.08:1"
    }
  }
}

In the previous snippet, Brightspot detects a heading 1:1 in lines 6, 11, and 16, and displays it only once, suppressing the individual names of the associated image sizes.

The following illustrations provide examples of the default grouping and a cleaner listing by group heading.

Grouping Images by Aspect Ratio
Default Group Headings Customized Group Headings
../../_images/image-grouping-default.png ../../_images/image-grouping-custom.png

See also:

Preparing an Image for Publication

Image Size Display Names

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. See the left image in the table Image-Size Labels.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "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"
    }
  }
}

In the previous snippet, lines 6, 11, and 16 provide custom names for the associated image sizes.

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

Image-Size Labels
Default Image-Size Names Customized Image-Size Names
../../_images/image-size-label-default.png ../../_images/image-size-label-custom.png