Using micro-templates

For example, it’s not possible out-of-the-box to display a vertical navigation menu containing your categories and sections outside of the Home page because that’s the only template with access to the required an array of category objects.

Our theming framework offers a convenient way of fetching the required objects and rendering the result in a micro-template. This means that now the only constraint you’ll face when creating new layouts and features within your Zendesk Guide help center is your own imagination.

Overview

The micro-templating system requires a template string to generate HTML. A convenient and easy way to provide the template string is within a <template> element:

<template id="tmpl-custom-articles-list">
  <% if (articles.length) { %>
    <ul class="list-unstyled">
      <% articles.forEach(function(article) { %>
        <li class="list-item" id="<%= article.id %>">
          <a href="<%= article.html_url %>">
            <%- article.title %>
          </a>
        </li>
      <% }); %>
    </ul>
  <% } %>
</template>

The element should have an ID in the format tmpl-{name}, where {name} is the unique identifier provided to the renderTemplate method or used by our collection of extensions.

Micro-templates are similar to the Curlybars page templates used by Zendesk, but have some important differences:

1. Use <% … %> to execute custom JavaScript code. This is often used to apply conditional logic or manipulate data.

    <% articles.forEach(function(article, index) { %>
      <% if (article.title && index % 2 === 0) { %>
        <%- article.title %>
      <% } %>
    <% }); %>
   

2. Use <%= … %> to print values to the screen, or <%- … %> if the value should be HTML-escaped.

Micro-templates can be placed in any of the Zendesk Curlybars page templates and you can therefore reference all objects available on the page in the way that you normally would. If a micro-template is used on multiple pages, you should include it within the footer.hbs page.

Via data attributes

You can render arbitrary micro-templates quickly and easily using the data-element="template" attribute. For example, the following HTML element will render a custom micro-template with the ID my-custom-template:

<div data-element="template" data-template="my-custom-template"></div>

For more complex use-cases where you need to retrieve or pass a large amount of data to the template, using JavaScript to render the template is recommended.

Via extensions

All of our extensions that render HTML on the page have a template option that allows a custom micro-template to be used instead of the default one provided by the extension.

For example, when using the Navigation extension to render a list of articles you can use a custom micro-template by supplying its ID (custom-articles-list) as a data attribute on the element that will become your list:

<div data-element="navigation" data-template="custom-articles-list"></div>

The available options for each extension are described on each extension’s page under the Usage tab.

Alternatively, the extension can be initialized using JavaScript and the micro-template identified using extension options:

<div id="articles-list"></div>

<script type="text/javascript">
  document.addEventListener('DOMContentLoaded', function() {
    new Navigation(document.getElementById('articles-list'), {
      template: 'custom-articles-list'
    });
  });
</script>

Both examples require that the custom-articles-list template micro-template exists on the page, either in template of the page being viewed or one that’s globally available like the page footer.

Via JavaScript

Micro-templates can be rendered using the renderTemplate framework method independently of an extension.

For example, the custom-articles-list template above renders a simple unstyled list of articles and could be used with the renderTemplate method as follows:

<div id="article-list"></div>

<script type="text/javascript">
  document.addEventListener('DOMContentLoaded', function() {

    // Fetch the data
    Util.get(['articles']).then(function(collection) {
    
      // Render the template
      Util.renderTemplate(
        document.getElementById('article-list'),  // DOM element
        'custom-articles-list',                   // Template ID
        collection                                // Template data
      );
    });
  });
</script>

The collection object containing the template data could also be generated manually, or by Zendesk template object data to the page:

<script type="text/javascript">
  var collection = {};
  collection.catgories = [];
  {{#each categories}}
    collection.catgories.push({
      id: {{id}},
      name: {{json_stringify name}},
      {{#if description}}description: {{json_stringify description}},{{/if}}
      html_url: {{json_stringify url}}
    });
  {{/each}}
</script>