Updating page templates

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

Guide templating, also known as the Templating API, is responsible for rendering the Help Center theme packages. This contains the Curlybars templating language that is used in the template files, CSS and JS files, and the manifest file.

To learn more about Guide themes, see Customizing your Help Center theme and the Help Center Templates developer documentation.

About Guide templating versions

Version 2 of the Templating API was released on February 24, 2020 and applies to the Copenhagen theme and any new theme releases. You can find out which version of the framework from the Customize design icon () in Guide (see Finding out the templating version).

All Zenplates themes are built using the latest version of the Templating API which removes jQuery entirely to ensure themes remain fast and nimble. All custom functionality in our themes is written in vanilla JavaScript however if to use jQuery you can import the jQuery library.

For a full list of changes in version 2, refer to the online documentation.

Finding out the templating version

You can see the templating version from the Edit code view in your theme, or in the manifest file.

To check the templating version

1. In Guide, click the Customize design icon () in the sidebar.
2. Click the theme you want to see.
3. Click Edit code.

4. Under the preview option, you’ll see the templating version number, for example, Templating API v1.

   

   This version number corresponds with the api_version field in the manifest file.

The HTML for the Help Center is contained in editable templates that define the layout of each page type, as well as the global header and footer. You can also use a full-featured templating language called Curlybars to access Help Center data and manipulate content in page templates.

On Guide Enterprise, you can create additional page templates for articles, sections, and categories if you need multiple versions of those templates.

You can customize the template of any of the following page types or elements:

• Article page (article_page.hbs): the individual article pages in the knowledge base
• Category page (category_page.hbs): landing pages
• Community post list page (community_post_list_page.hbs)
• Community post page (community_post_page.hbs)
• Community topic list page (community_topic_list_page.hbs)
• Community topic page (community_topic_page.hbs)
• Contributions page (contributions_page.hbs): the lists of posts, community comments, and article comments by an end-user
• Document head (document_head.hbs): the document’s head tag
• Error page (error_page.hbs): the message displayed when a user lands on a non-existent page
• Footer (footer.hbs): the bars appearing at the bottom of all Help Center pages
• Header (header.hbs): the bars appearing at the top of all Help Center pages
• Home page (home_page.hbs): the top-level landing page for your Help Center
• New community post page (new_community_post_page.hbs)
• New request page (new_request_page.hbs): the request or ticket submission form
• Request page (request_page.hbs): the individual request or ticket pages
• Requests page (requests_page.hbs): the lists of requests or tickets assigned to a user or that a user is CC’d on
• Search results (search_results.hbs): the search results display format
• Section page (section_page.hbs): landing pages
• Following page (subscriptions_page.hbs): the list of categories, sections, and articles a user is following
• User profile page (user_profile_page.hbs)

When you use the Theme Editor to edit the page templates, CSS, or JavaScript for a standard theme, or when you develop your own theme, it is saved as a custom theme. Custom themes are not supported by Zendesk and are not automatically updated when new features are released. See About standard themes and custom themes in Help Center.

To edit the page templates

1. In Guide, click the Customize design icon () in the sidebar.

2. Click the theme you want to edit to open it.

3. Click Edit code.

   

4. In the Templates section, click the template you want to modify.

   The page opens in the code editor.

5. Use the code view to edit the template.

   You can add, remove, or reorder any the following:

   • Template expressions to display and manipulate content in your pages

   For example, the breadcrumbs template helper {{breadcrumbs}} displays a breadcrumb navigation element on a page. For a detailed guide on template expressions, see Help Center Templates.

   • Dynamic content placeholders (see Adding translated text)
   • Embeddable widgets created by third parties (such as the Twitter search widget)
   • HTML markup

6. Click Save in the top right corner to save your changes.

   The changes are applied to every page in your theme that is based on the template you modified.

7. To preview your changes, click Preview (see Previewing your theme in Help Center).

   

8. Make other code changes as needed, then click Save.

   When you’re finished editing the page template, you can close it.

The properties you choose in the Settings panel or set in your manifest file for colors, fonts, and theme images are stored in variables. You can use these variables in the theme’s style.css file. You can also reference the variables using Curlybars expressions in HTML page templates.

The variables are useful if you want to specify the same value in several places and update it quickly. Updating the property updates it everywhere the variable is used. You can change the names and labels, delete variables, or add your own (see the Settings manifest reference).

For a complete list of the default settings available in our themes, refer to our online documentation.

Examples using variables in CSS

The properties you set for colors, fonts, and theme images are stored in variables that you can use in your theme’s style.css file.

For example, you can use some of the default variables in CSS with the following syntax:

• $primary_color
• $primary_inverse_color
• $heading_font
• $text_font

In the CSS file, you assign a variable to a CSS property the same way you would assign a normal value. For example:

.button {
  label-color: $text_font;
}

You can also use single curly brackets to embed the helper in a CSS expression, as follows:

max-width: #{$search_width}px

Examples using variables in Curlybars in HTML

The properties you set for colors, fonts, and theme images are stored in variables that you can reference with Curlybars expressions in HTML page templates.

The variables become properties of the settings object in Curlybars. As with any Curlybars object, you can use double curly brackets and dot notation to insert an property in a page template.

For example:

• {{settings.color_1}} is the HEX value of a color. For example: #FF00FF
• {{{settings.font_1}} is the font stack. For example, system is defined as: ‘-apple-system, BlinkMacSystemFont, ‘Segoe UI’, Helvetica, Arial, sans-serif”
• {{settings.homepage_background_image}} is the path to the file stored in this field. For example: p8.zdassets.com/theme_assets/…
• {{settings.range_input}} is the value of the range input.

The settings object can be used as input to any helper. For example:

{{is settings.enabled}} ... {{/is}}

By default, there is one page template each for article, section, and category in a theme. You can create up to ten additional page templates each for articles, sections, and categories.

This means that you can create alternate versions of templates to use for your articles, sections, and categories. You can apply or change the page template when you create or edit an article, section, or category.

You must have Guide Enterprise and you must be a Guide Manager to create multiple templates.

Adding multiple templates using the theme editor

You can create additional page templates for articles, sections, and categories using the theme editor in Guide. If you prefer working on your themes locally, you can also add templates to your exported themes.

To add an article, section, or category template using the theme editor

1. In Guide, click the Customize design icon () in the sidebar.

   Your themes appear on the Themes page.

2. Hover your mouse over the theme you want to edit, then click View theme.

3. Click Edit Code.

   

4. Scroll to the bottom of your templates list, then click Add new template.

   

5. Under Template for, select the type of template you’d like to create.

   You can create article, section, and category templates only. You can create up ten additional templates for each type.

   

6. Enter a Template name.

7. Under Start from, select an existing template to copy and use as a starting point.

   You can select blank template if you don’t want to start from another template.

8. Click Create template.

   The new template opens for you.

9. Edit your template and click Save as you go.

10. To preview your template, click Preview, then click Templates at the top of the preview and select the template you want to preview.

    

    For more information, see Previewing your theme while editing theme code.

When you are ready, you can apply your template to a new article or new category or section. You can also change the template on an existing article, section, or category.

Adding multiple templates in exported themes

If you export and work on themes locally, you can add multiple templates to the themes. The workflow consists of creating a predefined folder in a theme’s templates folder, then adding .hbs template files to the folder.

To learn more about working on themes locally, see Working on a theme locally.

To add a template to an exported theme

1. Depending on the type of template you want to add (article, section, or category), create any of the following folders in the templates folder of the exported theme:

   • article_pages
   • section_pages
   • category_pages

   As in the Guide theme editor, you can only create article, section, and category templates.

2. Add an .hbs template file in the new folder.

   You can name the file anything you want. The name must be 25 characters or less, and snake_case.

   

   To save time, copy an existing .hbs file into the folder to use as a starting point for the new template.

3. Edit and save the template.
4. If you need to add more templates of the same type, add them to the same folder.
5. When you’re done, zip the theme and import it into Guide.

Use Guide to preview the new template.

When you are ready, you can apply your template to a new article or new category or section. You can also change the template on an existing article, section, or category.

In a Guide theme, there is one page template each for article, section, and category by default. On Guide Enterprise, Guide managers can create additional templates for article, sections, and categories. If your live theme has multiple templates for these template types, you can change the template for an article, section, or category at any time.

Agents can change the template on any article they have permission to edit. You must be a Guide Manager to change the template for a section or category.

Changing the template for an article

If you have multiple article templates in your live theme, you apply a template when you create a new article. You can change the template on an existing article at any time.

Agents can change the template on any article they have permission to edit.

To change the template for an article

1. In Help Center, navigate to the article you want to edit, then click Edit article in the top menu bar.

   

   Alternatively, in Guide, click the Manage articles () icon in the sidebar, then select an article from an article list to open it in edit mode.

2. In the sidebar, click Article settings.

3. Click the Template menu, then select a template.

   You might have to scroll down to see this option.

   

4. Click Save.

   The live article is updated with the new template. You cannot preview this change in the article editor.

Changing the template for a category or section

If you have multiple category or section templates in your live theme, you apply a template when you create a new category or section. You can change the template on an existing category or section at any time.

You must be a Guide Manager to change the template for a section or category.

To change the template for a category or section

1. In Help Center, navigate to the category or section you want to edit, then click Edit category or Edit section in the top menu bar.

   

   Alternatively, in Guide Admin, click the Arrange content () icon in the sidebar, then click the title of the category or section to open it in edit mode.

2. In the sidebar, click the Template menu, then select a template.

   

3. Click Update.

   The live category or section is updated with the new template.