Support and Documentation

Context

Brightspot selects the appropriate image size to use when rendering images based on the template context. Multiple contexts may be valid for a given image field, and the most specific context will be chosen. The rules of specificity are similar to those you would find in CSS.

A context specifies the template and the field for which the image size context should be used:

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

If you need a different image size in a different context, simply create an image size with more specificity. In the example below MyComponent will render image with the small image size when it is rendered within Container:

{
   "imageSizeContexts": {
      "/styleguide/Container.hbs": {
        "/styleguide/MyComponent.hbs": {
          "image": "small"
        }
      }
   }
}

If my configuration contains both of the image size contexts above, they may both be used depending on the rendering context.

Note

Image Size Contexts also support globbing, which allows you to specify an Image Size Context that applies to more than one template. Below is a simple example.

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

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

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.

    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.

{
  "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: