Define Image Size Context

Brightspot looks up image sizes using templates context. For example, if you have a template Author.hbs, and that template 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 simple context, the value directly provides the image size. In the following example of simple context, when the placeholder {{authorImage}} appears in the template file ArticlePage.hbs, the size applied to the image is square-small-50x50.

{
  "imageSizeContexts": {
    "/styleguide/core/article/ArticlePage.hbs": {
      "authorImage": "square-small-50x50"
     }
  }
}

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

{
  "imageSizeContexts": {
    "/core/promo/Promo.hbs": {
      "/core/image/Image.hbs": {
        "image": "landscape-large-450x370"
      }
    }
  }
}

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.

  1. In Brightspot, change to the theme for which you want to determine an image’s context. For details, see Previewing Content in Different Themes.

  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 Quote Promo Carousel.

    ../../_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": "Quote Promo Carousel".

  4. Find the field’s data file from the key example. Referring to the following snippet, the data file is themes/brightspot-theme-falcon/styleguide/core/list/QuotePromoCarousel.json.

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

    {
      "_template": "QuotePromoCarousel.hbs",
      "items": [
        {
          "_include": "/core/promo/QuotePromo.json"
        }
      ]
    }
    
  6. If there is a stanza or key in the data file referring to the required image, then nest any templates associated with the image into the template chain found so far, and terminate the recursion. 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-falcon/styleguide/core/promo/QuotePromo.json.

  8. Return to step 5.

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 quote carousel example, the nested chain is as follows:

/core/list/QuotePromoCarousel.hbs
  /core/promo/QuotePromo.hbs
    media
      /core/image/Image.hbs
        image

Finally, examine the theme’s configuration file _context.json to find the most specific context matching your nested chain of templates. In the case of our quote carousel example, the context is in the following snippet:

{
  "imageSizeContexts": {
    "/core/promo/QuotePromo.hbs": {
      "media": {
        "/core/image/Image.hbs": {
          "image": "authorPromo"
        }
      }
    }
  }
}

Referring to the previous snippet, when a helper {{image}} appears in the nested context QuotePromo.hbs/Image.hbs, Brightspot applies the image size labeled authorPromo.

Lookup Logic for Image Size

Given a data file that defines an image with an associated _image key, Brightspot uses the following lookup logic to determine the image’s size:

  1. In the data file, retrieve the associated template file from the key _template.
  2. In the theme’s configuration file _config.json, under the key imageSizeContexts, search for the stanza matching the template file from step 1.
  3. In the stanza from step 2, find the key matching the image (usually image), and observe the value.
  4. Under the key imageSizes, look up the key corresponding to the value from step 3. This is the image’s size.
  5. Apply the dimensions from step 4 to the image.

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

{
  "_template": "/styleguide/Author.hbs",
  "image": {
    "_image": true,
     "src": "/path/beachrocks.png"
  }
}

Because the key image has an element _image = true, at runtime Brightspot retrieves the image’s dimensions from _config.json. In the first step, Brightspot searches for an element under imageSizeContexts whose key matches the template’s filename /styleguide/Author.hbs.

1
2
3
4
5
6
7
{
  "imageSizeContexts": {
    "/styleguide/Author.hbs": {
      "image": "square-small-50x50"
    }
  }
}

Referring to lines 3–5 in the previous snippet, Brightspot looks up the image’s size under the key /imageSizes/square-small-50x50 in _config.json.

{
  "imageSizes": {
    "square-small-50x50": {
      "width": 150,
      "height": 150,
    }
  }
}

In the previous snippet, Brightspot determines that the image’s size is 150×150, and applies those dimensions to the image.

The previous example describes a simple scenario of simple context—an image is inside a top-level template. In most cases, templates are nested within each other, and an image’s size can change depending on where it is in the nesting. For a more detailed explanation of simple and nested contexts, see Determining an Image’s Context.

See also:

Setting Different Sizes in a List of Images

When a View contains multiple images, you can assign a size to one 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

In a different example, 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. To achieve a balanced layout, the images in each column should have the same width: Images 1 and 4 share the same width, Images 2 and 5 share a different width, and Images 3 and 6 also share a different width.

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

Given these layout scenarios, you can assign a size to each image depending on its index in the list. The image sizes have a zero-based index, so the first image in a list has an index of zero. Furthermore, the list is circular: if there are five images in a three-column list, then the fifth image’s index is (5 − 1) mod 3 = 1. Looking up index 1 in the following table indicates that the fifth image’s width is 300 (<img src="path/file.png" width="300" />).

Index Image Size Label Width
0 medium 200
1 large 300
2 small 100

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 the theme’s configuration file _config.json.
  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 index 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 index.
  4. Rebuild the theme’s styleguide, and view the template that contains the list.

The following detailed example illustrates how to implement varying sizes for images appearing in a table.

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

In the theme’s configuration file _config.json, under the key imageSizeContexts, add keys of the form <label>:x. Each key’s value is an element indicating context and a pointer to the image size in the stanza imageSizes.

Variable Image Size Contexts
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "imageSizeContexts": {
    "/path/Image.hbs": {
      "image": "small"
    },
    "images:1": {
      "/path/Image.hbs": {
        "image": "medium"
      }
    },
    "images:2": {
      "/path/Image.hbs": {
        "image": "large"
      }
    }
  }
}

In the previous snippet—

  • Lines 3–5 specify using the image size small in the following situations:
    • An element named image is inside the template Image.hbs.
    • The first element in an array of images whose individual entries are named image.
  • Lines 6–10 specify using the image size medium for the second element in an array of images called images when that second element appears inside the context Image.hbs.
  • Lines 11–15 specify using the image size large for the third element in an array of images called images when that third element appears inside the context Image.hbs.

Step 4: Create Child Templates and Data File

Create a template and data file for the image with the variable sizes. Referring to the snippet Variable Image Size Contexts, create a template Image.hbs and a corresponding data file Image.json.

Step 5: Create Parent Template

Create a template with the helper {{each}} that refers to a data file’s array of images.

Template Iterating Over Array of Images
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{{!-- Filename Table.hbs --}}
<table>
    <tbody>
        <tr>
            {{#element "images"}}
                {{#each this}}
                    <td>{{this}}</td>
                {{/each}}
            {{/element}}
        </tr>
    </tbody>
</table>

In the previous snippet, lines 5–9 iterate over the elements in the data file’s key images, placing the value of each element in a table cell.

Step 6: Create Parent Data File

Create a data file that includes an array of images.

1
2
3
4
5
6
7
8
9
{
  "_template": "Table.hbs",
  "images": [
    {
      "_include": "Image.json",
      "_repeat": 3
    }
  ]
}

In the previous snippet, lines 3–8 declare a three-element array of images. The helper {{each}} in the snippet Template Iterating Over Array of Images iterates over this array.

At run time, Styleguide displays the template using the variable sizes in the snippet Variable Image Size Contexts.

../../_images/image-sizes-variable.png

Applying Image Size at Runtime

At runtime, Brightspot uses the lookup logic described in Lookup Logic for Image Size and Setting Different Sizes in a List of Images to create an <img> tag with width and height attributes. For example, the following template provides the layout for an author’s byline.

<!-- 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: