Templating API

Introduction

This is the Templating API v3 documentation. SeeUpgrading from Templating API v1andUpgrading from Templating API v2.

Each Help Center theme consists of a collection ofeditable page templatesthat 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 theHandlebarslanguage. This page describes the language.

For a more detailed guide, seeUsing the Help Center templating languagein 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. Theeachhelper iterates through eachcommentobject in the page'scommentsarray. For each comment, the values of theauthor.avatar_url, andauthor.nameproperties are rendered in the HTML.

             

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

Expressions

通常一个模板有限公司ntainsexpressionsthat 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:

• Aliteralis 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 eithertrueorfalse.

• AHelp Center propertyspecifies some data in your Help Center. For example, theauthor.nameproperty specifies the author of the article requested by the user. The value is supplied only when the article is rendered. For details, seeHelp center properties.

• Ahelperperforms a specific action. For details, seeConditional helpers,Array iterator helper, andCustom helpers.

• Acode commentlets you add a note to yourself and to other developers who might work on the template later. For details, seeCode comments.

Nesting double curly brackets isn't allowed. For example,{{ {{ ... }} }}results in an error. However, you can usesubexpressionsto 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 inconditional helpers:

             

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

Subexpressions can be used inarray 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 namedarticlethat 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 apath. For example,nameis a property in theauthorobject, butarticle.author.nameis 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, thecommentsproperty 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 implicitlengthproperty 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><imgsrc="{{article.author.avatar_url}}">
             

You can set a context ofarticle.authorfor this snippet using thewithhelper, and then use onlynameandavatar_urlto render the properties. Example:

             

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

Suppose you also want to renderarticle.title, which isn't in thearticle.authorcontext. It would be evaluated in the block asarticle.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><imgsrc="{{avatar_url}}">{{/with}}
             

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

             

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

You can use anelseblock in awithconstruct in case the context isfalsy. A falsy value is a value that translates to false when evaluated in a Boolean context. SeeHow conditions are evaluated.

Example:

             

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

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

Helpers

Helpersperform actions in templates. For example, theassethelper inserts the relative path of an asset. Example:

             

              
<imgsrc="{{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

Aconditional是一块呈现基于是否规范ified condition is true or false. You can use built-inHandlebars helpersto set upifandunlessconstructs. You can also use the custom conditional helperisto 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{{/除非}}
             

is, is-else

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

             

              
{{#isvalue1 value2}}block to renderifthe values are equal{{/is}}
             

Example:

             

              
{{#isarticle.author.name'John Venturini'}}<p>Cool!JohnVenturiniisthe authorofthisarticle!p>{{/is}}
             

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

             

              
{{#isvalue1 value2}}block to renderifthe values are equal{{else}}block to renderifthe values are not equal{{/is}}
             

How conditions are evaluated

A condition is usually a Help Center property such asarticle.internal, which has a boolean value oftrueorfalse. 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

• 如果该值是一个字符串,一个空字符串是错误的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, thecommentsproperty returns all the comments left on the requested article.

You can use theeachhelper 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 itsauthor.nameandcreated_atvalues.

Theeachhelper sets the context of the block to the objects in the array, which in the snippet above is thecommentobject. In other words, don't use{{comment.author.name}}in theeachblock above. To access the outer context, use the../notation. SeeContext.

Custom helpers

Custom helpers perform actions that are unique to Help Center. For a complete list of custom helpers, seeGlobal helpers,Shared helpers, andAdvanced helpers.

For example, the following snippet uses a custom helper namedexcerptto truncate a string:

             

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

Thecharactersattribute 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, seeexcerpt 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 thethiskeyword to pass the current root context to a helper in awithblock. Suppose the helper accepts anarticleobject 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}}--}}