Define Image Size Context

Brightspot looks up image sizes using a View as a context. For example, if you have a View defined in the template Author.hbs, and that View includes an image, Brightspot looks up the image size in the file _config.json under the key imageSizeContexts for Author.hbs. If there is no context entry in _config.json for Author.hbs, Brightspot does not apply any size to the image and the browser scales the image accordingly.

Tip

Before developing your own image-size contexts, check if they are already present in the styleguide hierarchy. Projects inherit image-size contexts starting from <project_root>/styleguide/_config.json, then from <project_root>/themes/<theme-dir>/_config.json.

Types of Image Size Context

imageSizeContexts is a map of key-value pairs in which the key is the template context (the template to which the context applies) and the value is an object with two types of values: simple context and nested context. In a simple context, the value directly provides the image size. In the following example of simple context, when the Handlebars placeholder {{authorImage}} appears in the template file ArticlePage.hbs, the size applied to the image is tiny.

{
  "imageSizeContexts": {
    "/styleguide/core/article/ArticlePage.hbs": {
      "authorImage": "tiny"
     }
  }
}

In nested context, one Handlebars template is nested within another, providing more specific context for determining an image’s size. In the following example of nested context, when the Handlebars placeholder {{image}} appears inside the template file Image.hbs, which itself appears within a template file Carousel.hbs, the size applied to the image is large.

{
  "/styleguide/core/carousel/Carousel.hbs": {
    "/styleguide/core/image/Image.hbs": {
      "image": "large"
    }
  }
}

If a parent template has more than one nested template, consider simplifying your configuration with globbing on the nested filenames. For details, see Globbing Templates.

Determining an Image’s Context

An image’s context is the template file, or nested template files, in which the image appears. You can determine an image’s context by starting with the label in the Brightspot UI and then recursing through the theme’s configuration file _context.json and subsidiary data files. The following example demonstrates how to find the context for images appearing in a list using the Masonry template.

  1. In Brightspot, change to the theme for which you want to determine an image’s context. For details, see Changing to a Different Theme.

  2. Find the template for which you want to determine an image’s context. The following illustration indicates that the Lead field, when populated with a list of items, uses a template labeled Masonry.

    ../../_images/context-ui-label.png
  3. Search the theme’s configuration file _config.json for the label’s display name. In our example, search for "displayName": "Masonry".

  4. Find the field’s data file. Referring to the following snippet, the data file is /themes/brightspot-theme-canvas/styleguide/list/Masonry.json.

    {
      "displayName": "Masonry",
      "example": "/list/Masonry.json"
    }
    
  5. Open the data file from step 4 and examine the key _template. The value for this key is the next level in nesting. In the following example, the template is Masonry.hbs, so this is the first level of nesting.

    {
      "_template": "Masonry.hbs",
      "items": [
        {
          "_include": "/styleguide/promo/PortfolioItemCompact.json"
        }
      ]
    }
    
  6. If there is a key referring to an image, then nest any associated templates to the template chain found so far and terminate with the key. You have found the image size context. (If there is no key referring to an image, continue with step 7.)

  7. Examine the key _include, and open the associated data file. Referring to the snippet in step 5, the associated data file is /themes/brightspot-theme-canvas/styleguide/promo/PortfolioItemCompact.json.

  8. Return to step 4.

At the end of the recursive examination you have a chain of nested template files and the key representing the image. In the case of our Masonry example, the context is in the following snippet:

{
  "imageSizeContexts": {
    "/list/Masonry.hbs": {
      "/promo/PortfolioItemCompact.hbs": {
        "/core/image/Image.hbs": {
          "image": "380x200"
        }
      }
    }
  }
}

Lookup Logic for Image Size - Single Image

Given a View that includes a single _image, Brightspot uses the following lookup logic to determine the image’s size:

  1. Look up imageSizeContext given the current _template and field with an _image value.
  2. For the given image field key, get the specified image size name.
  3. Look up the image size by name.
  4. Apply the image size dimensions to the image.

For example, the file /styleguide/Author.json provides the following data:

{
  "_template": "/styleguide/Author.hbs",
  "image": {
    "_image": true
  },
  "byline": "{{words}}"
}

Because the key image has a value _image = true, at runtime Brightspot retrieves the image’s dimensions from _config.json. In the first step, search for a member under imageSizeContexts with key matching the template’s filename /styleguide/Author.hbs.

1
2
3
4
5
6
7
{
  "imageSizeContexts": {
    "/styleguide/Author.hbs": {
      "image": "tiny"
    }
  }
}

Referring to lines 3–5 in the previous snippet, Brightspot looks up the image size under the key /imageSizes/tiny in _config.json.

{
  "imageSizes": {
    "tiny": {
      "width": 150,
      "height": 150,
    }
  }
}

In the previous snippet, Brightspot applies the retrieved width and height attributes to every image whose context specifies the image size tiny.

Setting Different Image Sizes in a List of Items

When a View contains multiple images, you can assign a different size to each image based on its position relative to the other images.

Overview of Image Layout

Often when images appear in a list, you want to assign them different sizes depending on their position in the list. This is particularly true of images laid out in columns. Referring to the following illustration, there are three images: two in the left column and one in the right column. To achieve a balanced layout, the single image in the right column should be roughly equal to the total height of the images in the left column.

../../_images/image-index-wireframe.svg

When laying out images in columns, Brightspot places each image in the next available column. For example, in a list of six images, Brightspot places each image in column sequence as in the following illustration. The first three images are at the top of each column. Starting with the fourth image Brightspot returns to the first column, and adds each additional image to the next available column.

../../_images/image-layout-sequence.svg

Given this layout logic, you can assign a size to each image depending on its position in the list. The following table illustrates sizes for images in a list. The image sizes have a zero-based index, so the first image in a list has a size index of zero. Furthermore, the list is circular: if there are five images in the list, then the fifth image’s index (for the purposes of looking up the size) is (5 − 4) mod 3 = 1. Looking up index 1 in the following table indicates that the fifth image is sized at 200 × 450 (<img src="path/file.png" width="200" height="450" />).

Index Image Size Label Width × Height
0 medium 200 × 300
1 large 200 × 450
2 small 200 × 150

Implementing Image Sizes in Lists

The following steps provide an overview of implementing image sizes for a theme-specific list:

  1. Define the image sizes in _config.json as described in Define Image Sizes.
  2. Identify the name of the list for which you are assigning image sizes, and look up the corresponding template context.
  3. In the theme’s configuration file _config.json, do the following:
    1. Under the key imageSizeContexts, find or add the template context from step 2.
    2. Add the default image size, which corresponds to position 0 in the previous table.
    3. Add keys <label>:1, <label>:2, … <label>:x, where <label> is the key for the list of images and x indicates the position in the list.
  4. Rebuild the theme’s styleguide: in the directory themes/<theme_name>/styleguide/ run gulp styleguide. Brightspot packages the theme in a ZIP file under themes/<theme_name>/target/.
  5. Upload the updated theme package. For details, see Upgrading a Theme to New Release
  6. View the item that contains the list.

The following detailed example illustrates how to implement sizes for images appearing in Brightspot’s Masonry list in the theme Canvas.

Step 1: Prerequisites

  1. Working with a web designer, determine the sizes for images appearing in the theme’s list.
  2. In the theme’s configuration file _config.json, find or add image sizes used in the list. For details, see Define Image Sizes.

Step 2: Determine Image Size Context

Determine the template file, or series of nested template files, in which the images appear. For details, see Determining an Image’s Context.

Step 3: Add Position Context

Under the template key, add <label>:x keys with associated context, and an image label for each position in the list. For the Masonry example, <label> is items, and there are four image sizes.

{
  "imageSizeContexts": {
    "/list/Masonry.hbs": {
      "/promo/PortfolioItemCompact.hbs": {
        "/core/image/Image.hbs": {
          "image": "380x200"
        }
      },
      "items:1": {
        "/promo/PortfolioItemCompact.hbs": {
          "/core/image/Image.hbs": {
            "image": "340x590"
          }
        }
      },
      "items:2": {
        "/promo/PortfolioItemCompact.hbs": {
          "/core/image/Image.hbs": {
            "image": "380x280"
          }
        }
      },
      "items:3": {
        "/promo/PortfolioItemCompact.hbs": {
          "/core/image/Image.hbs": {
            "image": "380x280"
          }
        }
      }
    }
  }
}

Applying Image Size at Runtime

At runtime, Brightspot uses the lookup logic described in Lookup Logic for Image Size - Single Image and Setting Different Image Sizes in a List of Items to create an <img> tag with width and height attributes. For example, the following template provides the View for an author’s byline. The {{placeholder}}s match those in a companion data file Author.json.

<!-- File name /styleguide/Author.hbs -->
<div>
    <img src={{image.src}} width="{{image.width}}" height="{{image.height}}" />
</div>

At runtime, Brightspot looks up the appropriate contextual image size renders the template with the data to produce the following HTML:

<div>
    <img src="author.jpg" width="150" height="150" />
</div>

See also: