Rendering HTML using JavaScript

When Zendesk’s Curlybars templating language can’t generate the desired HTML, our JavaScript-based micro-templating system steps in.

A common use case for micro-templating is the creation of a category list that’s present on all pages in the Help Center. This is not possible out-of-the-box because the required template property, in this case an array of category objects, is only available on the Home page.

We offer a convenient way of fetching properties for use in JavaScript, so your imagination becomes the only constraint when creating new layouts and features within Zendesk Guide.

Usage

The micro-templating system requires a template string to generate HTML, which can be provided as a literal string of text or retrieved from a <script> element.

If a <script> element is used, it should have an ID in the format tmpl-{template_name}. For example, the custom-articles-list template below renders a collection 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.

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.

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:

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

Alternatively, the plugin can be initialized (and options set) using JavaScript:

<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>

All examples above require that a micro-templates exists on the page with an ID of tmpl-{template_name}:

<script type="text/html" id="tmpl-custom-articles-list'">
  ...
</script>

Via JavaScript

Micro-templates can be rendered using the renderTemplate() utility method.

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

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