Sections

Micro-templating

Some layouts cannot be created using Zendesk’s Curlybars templating language because one or more required objects are not available on the page. That’s where our JavaScript-based micro-templating system can save the day.

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 plugins, however, offer 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 theme is your own imagination.

Usage

The micro-templating system requires a template string to generate HTML. A convenient and easy way to provide the template string is within a <script> element. The element should have an ID in the format tmpl-{name}, where {name} is the unique identifier provided to the renderTemplate method.

For example, the custom-articles-list template below renders a simple unstyled list of articles:

<script type="text/html" 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.name %>
          </a>
        </li>
      <% }); %>
    </ul>
  <% } %>
</script>

Micro-templates are similar to the Curlybars 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.
  2. Use <%= … %> to print values to the screen. If the value should be HTML-escaped, use <%- … %>.

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

Via data attributes and plugins

Plugins that are responsible for rendering markup have a template option that allows a custom template to be used instead of the default. For example, when using the Articles List plugin to render a list of articles you can specify a custom template (my-custom-template) using data attributes on the element that will become your list:

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

Alternatively, the plugin can be initialized using JavaScript and the template identified in the plugin options:

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

<script type="text/javascript">
  ready(function() {
    var articlesList = document.getElementById('articles-list');
    if (articlesList) {
      new Articles(articlesList, {
        template: 'custom-articles-list',
        templateData: { ... }
      });
    }
  });
</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 a plugin:

var articlesList = document.getElementById('articles-list');
var data = {
  "articles": [ ... ] 
};

Util.renderTemplate(articlesList, 'custom-articles-list', data);

In this example, the template will be rendered using the data provided and the resulting HTML used to replace the content of the specified element (#articles-list). If required, you can fetch data (like all of your categories and sections) from the Zendesk REST API using our framework’s handy get() method.