Templating API

Introduction

This is the Templating API v4 documentation. See Upgrading from Templating API v1, Upgrading from Templating API v2 and Upgrading from Templating API v3.

Each Help Center theme consists of a collection of editable page templates that define the layout of different types of pages in Help Center. For example, there's a template for knowledge base articles, a template for the list of requests, and so on.

A Help Center template is simply a text file to be rendered on the server into an HTML page when a request for the page is received from a browser. Each template consists of a mix of HTML markup and expressions identifiable by double curly brackets. The expressions modify the page content at render-time.

The Help Center templating language is named Curlybars and implements a large subset of the Handlebars language. This page describes the language.

For a more detailed guide, see Using the Help Center templating language in the Zendesk Support Help Center.

The rest of the docs provide details about the properties, helpers, and forms you can use in your templates.

First look

The following example uses the templating language to generate a list of users who left comments on the page. The each helper iterates through each comment object in the page's comments array. For each comment, the values of the author.avatar_url, and author.name properties are rendered in the HTML.

{{#each comments}}
  <li>
    <div class="comment-avatar">
      <img src="{{author.avatar_url}}" alt="Avatar" />
    </div>
    <div class="comment-author">
      {{author.name}}
    </div>
  </li>
{{/each}}

Expressions

A template usually contains expressions that modify the page content at render-time. An expression is identifiable by double curly brackets. Example: {{author.name}}. An expression can contain literals, Help Center properties, helpers, or code comments:

• A literal is a string, a number, or a boolean. A string must be enclosed in single or double quotes. A number can be any positive or negative integer. A boolean is either true or false.

• A Help Center property specifies some data in your Help Center. For example, the author.name property specifies the author of the article requested by the user. The value is supplied only when the article is rendered. For details, see Help center properties.

• A helper performs a specific action. For details, see Conditional helpers, Array iterator helper, and Custom helpers.

• A code comment lets you add a note to yourself and to other developers who might work on the template later. For details, see Code comments.

Nesting double curly brackets isn't allowed. For example, {{ {{ ... }} }} results in an error. However, you can use subexpressions to evaluate expressions within expressions.

Subexpressions

Subexpressions allow you to invoke multiple helpers within a single expression, and pass the results of inner helper invocations as arguments to outer helpers. Subexpressions are delimited by parentheses.

The following example shows a subexpression in an expression:

{{search placeholder=(dc "search_text")}}

Subexpressions can be nested:

{{search placeholder=(excerpt (dc "search_text"))}}

Subexpressions can be used in conditional helpers:

{{#if (compare collection.length "==" 0)}}
  <div>Empty collection.</div>
{{else}}
  <div>Your collection has {{collection.length}} items</div>
{{/if}}

Subexpressions can be used in array iterator helpers:

{{#each (slice (filter user.badges on="category_slug" equals="achievements") 0 4)}}
  <section>
    <h3>{{name}}</h3>
    <div>{{description}}</div>
  </section>
{{/each}}

Help center properties

Templates have access to various properties of your help center. For example, the Article Page template has access to an object named article that has properties describing the article requested by the user. You can use dot notation to pluck information from the object. Example:

<h1>{{article.title}}</h1>

<p>Author: {{article.author.name}}</p>

{{article.body}}

The fully qualified name of a property is sometimes called a path. For example, name is a property in the author object, but article.author.name is its path.

Depending on the property, the value can be a string, an integer, a boolean (true or false), an object with its own set of properties, or an array of objects. For example, the comments property in the Article Page template returns an array of all the comments on the requested page.

Click the page links in the sidebar on the left side for all the available properties.

Array length

Each array has an implicit length property that provides the number of elements in the array. Example:

<p>This article has {{comments.length}} comments.</p>

Context

You can reduce the clutter in your code by setting a context for a property. For example, the following snippet uses full property paths:

<p>Author: {{article.author.name}}</p>
<img src="{{article.author.avatar_url}}">

You can set a context of article.author for this snippet using the with helper, and then use only name and avatar_url to render the properties. Example:

{{#with article.author}}
  <p>Author: {{name}}</p>
  <img src="{{avatar_url}}">
{{/with}}

Suppose you also want to render article.title, which isn't in the article.author context. It would be evaluated in the block as article.author.article.title, a property that doesn't exist.

To escape the context, add ../ to the property, as follows:

{{#with article.author}}
  {{../article.title}}
  <p>Author: {{name}}</p>
  <img src="{{avatar_url}}">
{{/with}}

Use an additional ../ to escape an additional context. Example:

{{#with article}}
  {{#with author}}
    {{../../article.title}}
  {{/with}}
{{/with}}

You can use an else block in a with construct in case the context is falsy. A falsy value is a value that translates to false when evaluated in a Boolean context. See How conditions are evaluated.

Example:

{{#with article.author}}
  ...
{{else}}
  No author is present for this article!
{{/with}}

Note: In Help Center, article.author is never actually false. It's only used here for demonstration purposes.

Helpers

Helpers perform actions in templates. For example, the asset helper inserts the relative path of an asset. Example:

<img src="{{asset 'background_image.png'}}" />

Help Center templates support Handlebars conditional and iterator helpers, as well as custom helpers designed specifically for Help Center pages. Topics covered in this section:

• Conditional helpers
• Array iterator helper
• Custom helpers

Conditional helpers

A conditional is a block that's rendered based on whether a specified condition is true or false. You can use built-in Handlebars helpers to set up if and unless constructs. You can also use the custom conditional helper is to create equality conditions.

if, if-else

To render a block if the condition is true:

{{#if condition}}
  block to render if the condition is true
{{/if}}

Example:

{{#if article.internal}}
  <p>This article is internal.</p>
{{/if}}

To render an alternate block if the condition is false:

{{#if condition}}
  block to render if the condition is true
{{else}}
  block to render if the condition is false
{{/if}}

unless

To render a block if the condition is false:

{{#unless condition}}
  block to render if the condition is false
{{/unless}}

is, is-else

To render a block when one value is equal to another value:

{{#is value1 value2}}
	block to render if the values are equal
{{/is}}

Example:

{{#is article.author.name 'John Venturini'}}
  <p>Cool! John Venturini is the author of this article!</p>
{{/is}}

To render an alternate block if the values are not equal:

{{#is value1 value2}}
	block to render if the values are equal
{{else}}
	block to render if the values are not equal
{{/is}}

How conditions are evaluated

A condition is usually a Help Center property such as article.internal, which has a boolean value of true or false. Some properties don't have boolean values. These properties are evaluated as follows:

• If the value is a number, then 0 is false and any other number is true

• If the value is a string, an empty string is false and any other string is true

• If the value is a collection of objects, an empty collection is false and any other collection is true

• If the value is null, the expression is false

Array iterator helper

Some Help Center properties return an array of objects, each with its own set of property values. For example, the comments property returns all the comments left on the requested article.

You can use the each helper to iterate over an array and render the values of each item. Example:

{{#each comments}}
  <li>{{author.name}} commented on {{created_at}}.</li>
{{/each}}

The snippet creates a list containing as many items as the number of comments in the article. Each item has data specific to that comment, such as its author.name and created_at values.

The each helper sets the context of the block to the objects in the array, which in the snippet above is the comment object. In other words, don't use {{comment.author.name}} in the each block above. To access the outer context, use the ../ notation. See Context.

Custom helpers

Custom helpers perform actions that are unique to Help Center. For a complete list of custom helpers, see Global helpers, Shared helpers, and Advanced helpers.

For example, the following snippet uses a custom helper named excerpt to truncate a string:

<h1>{{excerpt article.title characters=50}}</h1>

The characters attribute specifies the number of characters to keep and is optional. If you don't specify it, a default value is used. For more information on this helper, see excerpt helper.

The syntax to invoke a helper is as follows:

{{helper [parameter ...] [key=value ...]}}

The only mandatory element is the helper name. Parameters and key-value attributes vary depending on the helper.

You can use the this keyword to pass the current root context to a helper in a with block. Suppose the helper accepts an article object as a parameter. In a {{#with article}} block, you can pass the object to the helper as follows:

{{#with article}}
  {{my_helper this}}
{{/with}}

Code comments

To comment your template code, use {{! ... }}. Example:

{{! Test this out }}

To comment out another expression while testing and debugging, use {{!-- ... --}}. Example:

{{!--
  don't render the name for now
  {{author.name}}
--}}