使用帮助中心模板化语言

我的计划是什么?

本文涵盖以下主题：

• 简介
• 模板化基本信息
• 评论
• 阻止评论
• 文字
• 属性
• 条件
• 条件如何评估
• 装饰白人空间
• 助手
• 更改范围
• 将根背景信息传递给帮助者
• 在数组中访问项目
• 长度
• 次表达式

简介

每个帮助中心主题都包含一个 可编辑的页面模板 集合，可定义帮助中心不同类型的页面布局。包含用于知识库文章的模板、用于请求列表的模板等。

每个模板包括HTML标记和处理栏等表达式的混合，由双曲类别在模板中识别。处理栏 是一个简单的模板化引擎，使您可以在呈现时间而不是设计时插入或操作页面的内容。

帮助中心的模板化语言称为 柯利栏，并实施处理栏语言的大子集。此指南说明了如何使用语言来自定义帮助中心中的页面。

帮助中心为您提供帮助者和名称属性，以自定义您的内容。一些内容在所有帮助中心页面上都是共享的，可用。其余项是针对特定页面的。

例如

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

    <div class="comment-container">
      <header class="comment-header">
        <strong class="comment-author">
          {{author.name}}
        </strong>
      </header>
    </div>
  </li>
{{/each}}

范例生成了在页面上留下评论的用户列表。each帮助者通过页面comments属性中的每个值进行滚动。对于每个评论，这些author.avatar_urlauthor.name值和属性将插入HTML中。

注意：在对帮助中心进行自定义更改之前，请花几分钟时间查看支持提示 防止帮助中心加载时间差，方法是通过 杰克·班茨在模板化最佳实践之后。

模板化基本信息

这个组别介绍了您需要写入任意模板的构建块。如需更多信息，请查阅 developer.zendesk.com 上的 帮助中心模板。

曲条模板由两件事组成：动词文本以呈现为，以及柯利巴表达式。这意味着，一个空白的模板也是有效的模板，以及包含仅文本的模板也是有效的模板。例如，以下是有效的模板：

<h1>Article</h1>

<p>Some details on the article</p>

当然，如果帮助中心模板仅支持动词文本，则您无法在呈现时间进行真正自定义。要添加模板化逻辑，您需要库利巴表达式，这些表达式是封闭的双重卷曲类别（{{ 和 }}）。

要添加模板化逻辑到上一个例子，您可以修改模板如下：

<h1>Article</h1>

<p>Some details on the article</p>

{{article.author.name}}

以下部分解释了如何写入有效的表达式，以对模板进行有意义的更改。

请注意，在其它两对诅咒中嵌套一对曲子是有效的语法。例如，不允许以下内容：

<h1>Article</h1>

<p>Some details on the article</p>

{{ {{ ... }} }}

评论

有一些模板中有一些注释不会泄露到呈现页面可能会有用。为了这个目的，柯利巴允许在打开柯里巴后对评论置评，没有任何空格： {{! ... }}。您可以使用此语法在范例中添加代码评论：

{{!
  This template aims to
  show details of an article
}}

<h1>Article</h1>

<p>Some details on the article</p>

以下是在页面呈现后发送到浏览器的内容：

<h1>Article</h1>

<p>Some details on the article</p>

在开发模板时，放弃任何内容的效果实际上可以有用。您可能需要评论一些代码进行一些检查、调试以及更多操作。

阻止评论

很遗憾，到目前为止描述的评论语法不适合评论柯利巴代码。要评论柯利巴代码，请使用以下语法： {{!-- ... ---}}。这种评论可以跨越几行，并有效地评论出代码。例如：

{{!
  This template aims to
  show details of an article
}}

<h1>Article</h1>

<p>Some details on the article</p>

{{!--
  I want to commend out the following code:

  {{ ... some Curlybars expressions }}

--}}

上面的模板呈现如下：

<h1>Article</h1>

<p>Some details on the article</p>

文字

要包含您希望柯利巴可完全解释其写的值，柯利巴支持 字面概念。文本可以表示 3 种类型的值： 字符串、 布尔或 数字。

要表达字符串，您可以使用单一和双引号，但您无法混合。例如，，，'this is a valid string'"this is valid as well"但"this is not valid'。

数字可以是任意正负整数。 123 是有效的正数，表示相同的值， +123 仍然有效， 00123 -123 也有效。

一个布尔由 true 和 false表示。不允许其它变化。例如， TRUE 在柯利巴中，且 FALSE 未被标为布尔值。

您可以呈现文字。例如：

A string: {{ 'hello world' }}
A boolean: {{ true }}
A number: {{ 42 }}

页面呈现如下：

A string: 'hello world'
A boolean: true
A number: 42

属性

帮助中心的每一个模板都可访问代表您的帮助中心数据 的背景信息。例如，文章页面模板有一个名为 article 的对象，可暴露用户请求的文章结构。对于您可以在模板中使用的所有属性，请查阅 developer.zendesk.com 上的 帮助中心模板。

使用点注释从这些对象中拔出一个特定的信息。一个简单的范例是 article.title。

属性完全符合资格的名称有时称为 路径。例如， name 是对象 author 中的属性，但 article.author.name 是其路径。

您可以在双重卷曲类别中显示属性的值。返回范例，您可能需要在单独的段落中打印出作者的名称：

<h1>Article</h1>

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

比如说，一名用户想看到一篇名为约翰·文图里尼的专员写的文章。模板将如下呈现：

<h1>Article</h1>

<p>Author: John Venturini</p>

您也可以将文章呈现为自己。对象 article 有一个 body 包含文章内容的属性。您将修改模板如下，以呈现文章的正文：

<h1>Article</h1>

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

<article>{{article.body}}</article>

条件

除了呈现属性值之外，模板化语言还使您可以在您的模板中添加有条件的呈现逻辑。

例如，如果请求的文章是内部的，您可能需要呈现一个HTML片段。文章页面背景信息有一个article.internal属性，如果文章是内部的，false则返回true。

您可使用此信息创建一个 if 块。if表达式必须指定一个为 true 或 false 的条件。结果决定了块中的内容是否呈现或未呈现。以下是基本的语法：

{{#if condition}}
  This is rendered if the condition is true.
{{/if}}

您可以修改范例模板如下：

<h1>Article</h1>

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

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

<article>{{article.body}}</article>

当条件为 false 时，您可能需要呈现一个块。在这种情况下，请使用一个 unless 块。语法与 if 块相似：

{{#unless condition}}
  This is rendered if the condition is false.
{{/unless}}

返回范例，假设您还想在文章不是内部时呈现消息。您可以修改模板如下：

<h1>Article</h1>

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

{{#unless article.internal}}
  <p>This is a publicly visible article!</p>
{{/unless}}

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

<article>{{article.body}}</article>

这种有条件的逻辑——“如果真的做，否则做这样”——通常由一个 if-else 块处理。语法如下：

{{#if condition}}
  This is rendered if the condition is true.
{{else}}
  This is rendered if the condition is false.
{{/if}}

您可以修改范例如下：

<h1>Article</h1>

{{#if article.internal}}
  <p>This article is internal.</p>
{{else}}
  <p>This is a publicly visible article!</p>
{{/if}}

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

<article>{{article.body}}</article>

块 unless 还有一个 unless-else 变量。您可使用它来达到与块 if-else 相同的结果：

<h1>Article</h1>

{{#unless article.internal}}
  <p>This is a publicly visible article!</p>
{{else}}
  <p>This article is internal.</p>
{{/unless}}

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

<article>{{article.body}}</article>

条件如何评估

条件通常是帮助中心属性，如 article.internal，具有 true 或 false 的布尔值。一些属性没有布尔值。这些属性如下进行评估：

• 如果值是数字，则 0 为 false，并且任何其它数字都是 true

• 如果该值是字符串，则空白字符串为 false，并且任何其它字符串都是 true

• 如果值是对象集合，则空白集合为 false，并且任何其它集合都是 true

• 如果值为无效，则表达式为 false

想设置一些有条件的逻辑来检查数字。文章专页有一个 article.comment_count 属性，包含文章中的评论总数。您可以使用 if 条件来测试是否不是 0 计数，并显示一些高兴的消息。例如：

<h1>Article</h1>

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

<article>{{article.body}}</article>

{{#if article.comment_count}}
  <p>Yahoo! This article has got some comments!</p>
{{/if}}

装饰白人空间

当柯里栏处理模板时，它将显示任何动词文本为。这很好，大多数时候都很好。然而，有时您需要对表达式旁的空白字符有更多的控制。例如：请遵循以下代码：

<a href="..." class="{{#if highlighted}} highlight {{/if}}">Click me!</a>

它呈现以下HTML为 highlighted true：

<a href="..." class=" highlight ">Click me!</a>

在 单词突出显示周围有一个领先和一个跟踪空间。当然，这一点很好，但想让模板中保留空格而不呈现它们。您可以使用蒂尔德字符（~）。

在您的开或闭幕式字符中添加一个蒂尔德字符，将白色空间剪裁在受到装饰的文本中。例如：

<a href="..." class="{{#if highlighted~}} highlight {{~/if}}">Click me!</a>

蒂尔德字符修剪领先和一个在单词 突出显示周围空格：

<a href="..." class="highlight">Click me!</a>

蒂尔德字符修剪任何没有图形表示的空白字符，但影响填充物或分线，例如新行、标签、车送、行信息源、简单空格或标签。这意味着您可以用一个极端的例子，表达上一个行上的前 if 一个块，使其更可读。例如：

<a href="..." class="
  {{~#if highlighted~}}
    highlight
  {{~/if~}}
">Click me!</a>

这仍然呈现如下：

<a href="..." class="highlight">Click me!</a>

这些例子在现实生活中并不有意义，但使用蒂尔德字符的有效性可以从用例到用例有所不同。

助手

访问数据、显示并添加一些条件逻辑可以是一些模板中所需的所有内容。然而，您可能喜欢一些已添加的功能。例如，您可能需要显示一个本地化的字符串，根据页面请求者的区域设置更改。或者您可能需要截断一长段文本。

您可以通过 帮助器在模板中获取这种功能。对于您可以在模板中使用的所有帮助者，请查阅 developer.zendesk.com 上的 帮助中心模板。

例如，您可以使用一个名为文章页面模板的帮助来 excerpt 截断字符串。在文章范例中，假设您需要显示文章标题的截断版本。您可以通过修改模板来做到这一点：如下：

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

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

<article>{{article.body}}</article>

上面的例子显示，卷曲类别用于调用帮助者。excerpt帮助器接受一个参数，包括一个解析为字符串的表达式。帮助者可以选择 characters 指定保留的字符数。characters选项不必要。如果您未指定，则使用一个默认值。请查阅帮助中心模板中的摘录以获得更多详情。

调用帮助者的语法是 {{ [ ...] [ ...]}}。唯一必填元素是帮助者的名称。根据帮助者的不同参数和选项而有所不同。

现在，想更新模板，以便在作者的名字是约翰·文图里尼时显示一条欢呼的消息。很遗憾，您无法使用 if 条件来检查 article.author.name 是否等于 "John Venturini"，因为 if 仅可用于一个表达式。比较运算符如 == 不可用。

然后如何添加这样的逻辑？幸运的是，您可以使用 is 帮助者。它需要两个参数，并测试其平等。例如：

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

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

<article>{{article.body}}</article>

如果作者是约翰·文图里尼，上面的片段会呈现令人高兴的消息。但是如果你想呈现一个不同的消息， 如果这不是他？好消息是 is，也可以包括一个像声明一 else 样 if-else 的块。如果作者不是约翰·文图里尼，可以添加一个 else 块如下：

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

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

<article>{{article.body}}</article>

更改范围

访问数据非常简单，使用点指出，特别是当我们需要的信息路径太长时。例如：article.title。然而，在某些情况中，您可能想要访问带有更长路径的属性。例如：article.author.name。如果您想的话，您可以在模板中使用更长的路径。例如，您可以在以下例子中添加作者的姓名和阿文器：

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

<img src="{{article.author.avatar_url}}" alt="Author's avatar" height="42" width="42">
{{#is article.author.name 'John Venturini'}}
  <p>Cool! John Venturini is the author of this article!</p>
{{else}}
  <p>Author: {{article.author.name}}</p>
{{/is}}

<article>{{article.body}}</article>

上面代码片段很好，但长的属性路径使代码看起来有点混乱。问题一种方式是使用特殊 with 构建 with。接受一个参数，表示基础背景信息用于其关联的代码块。语法如下：

{{#with <context>}}
   ...
{{/with}}

您可以改进范例如下：

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

{{#with article.author}}
  <img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
  {{#is name 'John Venturini'}}
    <p>Cool! John Venturini is the author of this article!</p>
  {{else}}
    <p>Author: {{name}}</p>
  {{/is}}
{{/with}}

<article>{{article.body}}</article>

article.author参数可消除在块中的任何路径中加入article.author的需求。因此 {{name}}，在块内与 article.author.name 块外部相等。

您无法在块中使用 article.author.name，因为它将被评估为 article.author.article.author.name。同样，您无法访问块中文章的标题，因为文章对象仅在根背景信息中可访问，该块 article.title 以外的内容。

要从所设置 with 的背景信息中退出并访问外部背景信息，请使用 ../ 路径中的设置。您可在块内 with 呈现文章的标题：

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

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

  <img src="{{avatar_url}}" alt="Author's avatar" height="42" width="42">
  {{#is name 'John Venturini'}}
    <p>Cool! John Venturini is the author of this article!</p>
  {{else}}
    <p>Author: {{name}}</p>
  {{/is}}
{{/with}}

<article>{{article.body}}</article>

您可以在 ../ 同一条路径中使用该标签。它将返回相同数量的背景信息。例如，以下例子仍然会如期工作：

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

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

    ...

{{/with}}

<article>{{article.body}}</article>

当您作者未指定时，您可能需要防御并呈现一条特定的消息。您可以决定使用 if 块进行此操作，如下：

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

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

<article>{{article.body}}</article>

请注意帮助中心里， article.author 实际上从不无效。我们在这里使用这个例子只是为了例子而使用。

上面的片段工作正常，但是您可以用构建中的with块达到相同的结果else。如果参数是假的，则执行其它块。您可以修改范例如下：

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

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

<article>{{article.body}}</article>

else使用块也使代码更加可读。

将根背景信息传递给帮助者

this使用关键字将当前的根背景信息传递给帮助者。假设您有一个 render_author 可接受 article 对象为参数的帮助，以便显示其作者的详情。您可以使用 this 关键字如下：

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

{{#with article}}
  {{render_author this}}
{{/with}}

<article>{{article.body}}</article>

this 将被解决为 article。

在数组中访问项目

一些帮助中心属性包括对象数组。例如， attachments 属性包括一个附件数组。

要访问数组中的项目，您需要在每一个数组中更新一个项目。each帮助者确实这样做。例如：

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

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

<article>{{article.body}}</article>

{{#each attachments}}
  <a href="{{url}}" target="_blank">{{name}}</a>
  <span>({{size}})</span>
{{/each}}

上面的片段列出了所有附件。每个列表项目都显示特定于一个附件的数据，例如其 url、 name和 size。

就像 with， each 更改其块中的背景信息。也就是说，如果您想访问外部背景信息，您可以使用 ../ 该设置。

当您的数组为空时，您可能需要呈现一条消息。您可以使用块轻松实现此 if 功能，如下：

...

{{#if attachments}}
  {{#each attachments}}
    <a href="{{url}}" target="_blank">{{name}}</a>
    <span>({{size}})</span>
  {{/each}}
{{else}}
  Sorry, no attachments available!
{{/if}}

这很好，但您也可以使用 else 块来使代码更容易阅读：

...

{{#each attachments}}
  <a href="{{url}}" target="_blank">{{name}}</a>
  <span>({{size}})</span>
{{else}}
  Sorry, no attachments available!
{{/each}}

长度

每个数组都有一个嵌入到数组中的元素数的嵌入 length 属性。例如，如果您想显示附件数量，请使用 length 属性如下：

...

There are {{attachments.length}}.

{{#each attachments}}
  <a href="{{url}}" target="_blank">{{name}}</a>
  <span>({{size}})</span>
{{/each}}

次表达式

子表达式允许您在一个表达式中调用多个帮助者，并将内帮助者调用的结果作为外部帮助者的参数传递。子表达式由带号定界符。

以下例子显示了表达式中的子表达式：

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

子表达式可以嵌套：

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

子表达式可用于有条件的帮助者：

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

子表达式可用于数组分析器帮助者：

{{#each (slice (filter user.badges on="category_slug" equals="achievements") 
0 4)}}

   <section>
      <h3>{{name}}</h3>
      <div>{{description}}</div>
   </section>
{{/each}}

翻译免责声明：本文章使用自动翻译软件翻译，以便您了解基本内容。 我们已采取合理措施提供准确翻译，但不保证翻译准确性

如对翻译准确性有任何疑问，请以文章的英语版本为准。