Sections

Images

Use images throughout your Help Center and in ways that theme settings cannot accomodate.

In this article

Images used in Zendesk themes are controlled using theme settings or stored as theme assets.

Theme settings are a convenient but somewhat restrictive way to manage images in a theme. This is because the theme developer must define the number of images ahead of time and there are limits (practical and otherwise) in terms of how many image settings a theme can have.

Theme assets can be added to a theme through the Zendesk Guide interface or when working on a theme locally by adding files directly into the theme’s Assets folder. You can then reference your assets on a page using the built-in Zendesk {{asset}} helper. Although this approach can be used in a majority of cases, the Images plugin offers several advantages over the standard helper:

  • Image references can be composed of two or more variables, whereas the image helper only allows for one.
  • Image references can contain a wildcard value (*).
  • You can specify a default image to use in the case where an image is not available.

For example, our Rebel theme displays sections on the Home page and each section block has its own image. The image plugin allows these images to be stored as theme assets and managed effectively without the need for potentially dozens of redundant theme settings.

We’ve created a guide that explains how to add category, section and article images to a page template in Zendesk Guide.

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>
    

    Using the ID of the category instead of a position is a popular alternative.

  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.

When adding SVG images into a page you can use the data-inline-svg attribute to replace the resulting <img> element with an inline SVG. This allows you to alter the appearance of the image directly using utilities or custom CSS. Read about replacing images with inline SVGs in our documentation 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.