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:
-
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 thedocument_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>
-
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
Name | Type | Default | Description |
---|---|---|---|
data-asset-id | string null | null | The ID of the registered asset. |
data-default-asset-id | string null | null | The ID of the registered asset to use as a fallback. |
Events
There are no custom events emitted by this plugin.