Images

Image assets can be inserted into pages without the need for JavaScript using the {{asset}} helper, however this approach is not appropriate for all situations. The Assets page describes how to the built-in {{asset}} helper in your theme.

The Images plugin offers the following advantages over the built-in {{asset}} helper:

• Asset IDs can contain one or more variables.
• Asset IDs can contain a wildcard value (*).
• A default asset ID can be specified for use if the given asset ID has not been registered.

Adding icons to category and section lists is a common use-case.

Usage

The following steps describe how to set up and use the Images plugin:

1. Register assets

   The Images plugin requires that assets that need to be inserted into the page are registered within a window.assets JavaScript variable. This can be done in the document_head.hbs template using a <script> tag and the {{asset}} helper:

    <script type="text/javascript">
      window.assets = {
        "category-1": "{{asset 'getting-started.svg'}}",
        "category-2": "{{asset 'usage-guides.svg'}}",
        ...
      }
    </script>
   

2. Update templates

   Elements to be replaced with an image should be updated with the following data attributes:

   • data-asset="image"
   • data-asset-id="{id}" identifying the asset to use.
   • data-default-asset-id="{id}" identifying the asset to use if the asset above has not been registered (optional).

   The ID specified for both the asset and the default (fallback) asset is the object key specified in the window.assets global variable. The ID can identify an asset by name (e.g., “category-1”) or include a wildcard character (e.g., “category-*”):

    <div class="container">
      {{#each categories}}
        <h2>
          <a class="link-plain text-inherit" href="">
            {{name}}
          </a>
        </h2>
        <div class="h-6 w-6" data-asset="image" data-asset-id="category-*"></div>
      {{/each}}
    </div>
   

   Because data attributes are used, you will need to ensure that the allow unsafe HTML setting is enabled within Guide.

   If a wildcard character is used, the plugin replaces the character with an integer representing the current number of assets with the same prefix, starting at 1.

If the target is an SVG, the data-inline-svg attribute can be added to the element which will replace the <img> element with an inline SVG. Refer to the replaceWithSVG() JavaScript method for more information.

Options

Events

There are no custom events emitted by this plugin.