Uso da linguagem de modelos da Central de Ajuda (Guide Professional)

Introdução

Cada tema da Central de Ajuda consiste em uma coleção de modelos de página editáveis que define o layout dos tipos diferentes de páginas na Central de Ajuda. Por exemplo, há um modelo para os artigos da base de conhecimento, um modelo para a lista de solicitações e etc.

Cada modelo consiste em uma mistura de marcação HTML e expressões Handlebars, identificáveis no modelo por chaves duplas. Handlebars é um mecanismo de modelo simples que permite que você insira ou manipule conteúdo em uma página no tempo de renderização e não no tempo do design.

A linguagem de modelo na Central de Ajuda é chamada de Curlybars e implementa um amplo subconjunto da linguagem Handlebars. Esse guia mostra como usar a linguagem para personalizar suas páginas na Central de Ajuda.

A Central de Ajuda fornece auxiliares e propriedades nomeadas para personalizar seu conteúdo. Alguns são compartilhados e estão disponíveis em todas as páginas da Central de Ajuda. O restante é específico da página.

Exemplo

{{#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}}

O exemplo gera uma lista de usuários que deixaram comentários na página. O auxiliar each reitera por cada valor na propriedade comments da página. Para cada comentário, os valores das propriedades author.avatar_url e author.name são inseridos no HTML.

Observação: antes de fazer mudanças personalizadas em sua Central de Ajuda, consulte algumas dicas de suporte em Práticas recomendadas para evitar o carregamento lento da Central de Ajuda por Jake Bantz.

Noções básicas sobre modelos

Essa seção apresenta os elementos fundamentais necessários para criar qualquer modelo. Para mais informações, consulte os Modelos da Central de Ajuda em developer.zendesk.com.

Um modelo Curlybars é constituído de dois elementos: texto a ser renderizado do modo em que se encontra e expressões Curlybars. Isso implica que um modelo vazio também é um modelo válido, e um modelo que contém apenas texto também é válido. Por exemplo, o seguinte é um modelo válido:

<h1>Article</h1>

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

Obviamente, se os modelos da Central de Ajuda suportassem apenas texto, não seria possível personalizá-los no tempo de renderização. Para adicionar lógica ao modelo, é preciso usar expressões Curlybars, que ficam entre chaves duplas({{ and }}).

Para adicionar lógica de modelo do exemplo anterior, é necessário modificar o modelo da seguinte maneira:

<h1>Article</h1>

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

{{article.author.name}}

As seções a seguir explicam como escrever expressões válidas para fazer alterações significativas no modelo.

Observe que o aninhamento de um par de chaves dentro de outro par de chaves não é uma sintaxe válida. Por exemplo, o seguinte não é permitido:

<h1>Article</h1>

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

{{ {{ ... }} }}

Comentários

Há situações em que ter algumas observações no modelo que não sejam exibidas na página renderizada pode ser útil. Para isso, o Curlybars permite fazer comentários colocando um ponto de exclamação logo depois da abertura das chaves, sem espaços: {{! ... }}. É possível usar essa sintaxe para adicionar um comentário de código no exemplo:

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

<h1>Article</h1>

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

Eis o que é enviado ao navegador após a renderização da página:

<h1>Article</h1>

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

Esse efeito de descartar qualquer elemento nos comentários pode, na verdade, ser útil ao desenvolver um modelo. Você pode querer fazer comentários e assinalar códigos para verificações, depuração e mais.

Comentários de bloco

Infelizmente, a sintaxe de comentário descrita até agora não é adequada para fazer comentários no código Curlybars. Para fazer comentários no código Curlybars, use a seguinte sintaxe: {{!-- ... ---}}. Esse tipo de comentário pode abranger várias linhas e comentar efetivamente o código. Por exemplo:

{{!
  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 }}

--}}

O modelo acima é renderizado da seguinte maneira:

<h1>Article</h1>

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

Literais

Para incluir valores que você deseja que o Curlybars interprete exatamente do modo em que estão escritos, o Curlybars suporta o conceito de literais. Um literal pode representar três tipos de valores: uma cadeia, um booliano, ou um número.

Para expressar uma cadeia, é possível usar aspas simples e duplas, mas não as misturar. Por exemplo, 'this is a valid string', "this is valid as well", mas "this is not valid'.

Um número pode ser qualquer inteiro positivo ou negativo. 123 é um número positivo válido, +123 representa o mesmo valor, e 00123 ainda é válido, assim como -123.

Um booliano é representado por true e false. Nenhuma outra variação é permitida. Por exemplo, TRUE and FALSE não são interpretados como boolianos em Curlybars.

É possível renderizar literais. Por exemplo:

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

A página é renderizada da seguinte maneira:

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

Propriedades

Todos os modelos na Central de Ajuda têm acesso a um contexto que representa dados sobre sua Central de Ajuda. Por exemplo, o modelo Página do artigo tem um objeto chamado article que expõe a estrutura do artigo solicitado pelos usuários. Para consultar todas as propriedades disponíveis para o uso em seus modelos, visite Modelos da Central de Ajuda em developer.zendesk.com.

Use notação de ponto para obter uma informação específica desses objetos. Um exemplo simples é article.title.

O nome totalmente qualificado de uma propriedade é, às vezes, chamado de um caminho. Por exemplo, name é uma propriedade do objeto author, mas article.author.name é seu caminho.

É possível exibir o valor de uma propriedade ao colocá-la entre chaves duplas. Voltando ao exemplo, pode ser necessário imprimir o nome do autor em um parágrafo separado:

<h1>Article</h1>

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

Digamos que um usuário deseja ver um artigo escrito por um agente chamado John Venturini. O modelo é renderizado da seguinte maneira:

<h1>Article</h1>

<p>Author: John Venturini</p>

Você também pode querer renderizar o próprio artigo. O objeto article tem uma propriedade body que apresenta o conteúdo do artigo. É possível modificar o modelo da seguinte maneira para renderizar o corpo do artigo:

<h1>Article</h1>

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

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

Condicionais

Além de renderizar valores de propriedade, a linguagem de modelo permite que você adicione lógica de renderização condicional aos seus modelos.

Por exemplo, você pode desejar renderizar um trecho do código de HTML caso o artigo solicitado seja interno. O contexto Página do artigo tem uma propriedade article.internal que retorna true se o artigo for interno e false caso não seja.

Você pode criar um bloco if com essa informação. A expressão if deve especificar uma condição que seja true ou false. O resultado determina se o conteúdo no bloco é renderizado ou não. Eis a sintaxe básica:

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

É possível modificar o modelo do exemplo da seguinte maneira:

<h1>Article</h1>

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

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

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

Você pode desejar renderizar um bloco quando a condição for false. Nesse caso, use um bloco unless. A sintaxe é similar a do bloco if:

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

De volta ao exemplo, suponha que você também queira renderizar uma mensagem quando um artigo não for interno. É possível modificar o modelo da seguinte maneira:

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

Esse tipo de lógica condicional ("se true faça isso, ou else faça aquilo") costuma ser obtida com um bloco if-else. A sintaxe é a seguinte:

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

É possível modificar o exemplo da seguinte maneira:

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

O bloco unless também apresenta uma variante unless-else. Você pode usá-lo para obter o mesmo resultado de um bloco 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>

Como as condições são avaliadas

Uma condição é, normalmente, uma propriedade da Central de Ajuda, como article.internal, que tem um valor booliano de true ou false. Algumas propriedades não têm valores boolianos. Essas propriedades são avaliadas da seguinte maneira:

• Se o valor for um número, então 0 é false e qualquer outro número é true.

• Se o valor for uma cadeia, uma cadeia vazia é false e qualquer outra cadeia é true.

• Se o valor for uma coleção de objetos, uma coleção vazia é false e qualquer outra coleção é true

• Se o valor for nulo, a expressão é false

Suponha que você deseje configurar algumas lógicas condicionais que verifiquem números. A Página do artigo tem uma propriedade chamada article.comment_count que contém o número total de comentários em um artigo. Você pode usar a condição if para testar se a contagem não é 0 e exibir uma mensagem alegre. Por exemplo:

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

Como cortar espaços

Quando o Curlybars processa um modelo, ele exibe qualquer texto no estado em que se encontra. Isso é bom e funciona bem quase sempre. Entretanto, às vezes é necessário ter mais controle sobre os caracteres em branco ao lado de uma expressão. Veja o seguinte código como exemplo:

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

Ele renderiza esse HTML quando highlighted for true:

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

Há um espaço à esquerda e outro à direita da palavra highlight. Obviamente, isso funciona bem, mas suponha que você não deseje renderizar os espaços no modelo. Você pode usar o caractere til (~).

Adicionar um caractere til em suas chaves de abertura ou fechamento corta o espaço do texto entre aspas. Por exemplo:

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

Os caracteres til cortam os espaços à direita e à esquerda da palavra highlight:

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

O caractere til corta qualquer caractere em branco que não tenha uma representação gráfica, mas afeta o espaçamento ou as linhas de divisão, como novas linhas, retorno de carro, avanço de linha, espaços simples ou tabulações. Isso significa que você pode levar o exemplo a um extremo e expressar o bloco if em mais linhas para torná-lo mais legível. Por exemplo:

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

Isso ainda é renderizado da seguinte maneira:

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

Esses exemplos não fazem muito sentido em um cenário real, mas a eficácia do uso do caractere til pode variar dependendo do caso.

Auxiliares

Acessar dados, exibi-los e adicionar algumas lógicas condicionais pode ser tudo o que você precisa em alguns modelos. Ainda assim, você pode gostar de outras funcionalidades. Por exemplo, você pode querer exibir uma cadeia localizada que mude de acordo com a localidade do solicitante da página. Ou você pode desejar truncar uma passagem de texto longa.

Você pode obter esse tipo de funcionalidade nos modelos com auxiliares. Para consultar todos os auxiliares disponíveis para o uso em seus modelos, visite Modelos da Central de Ajuda em developer.zendesk.com.

Por exemplo, você pode usar um auxiliar chamado excerpt no modelo da Página do artigo para truncar cadeias de caracteres. Nesse exemplo de artigo, suponha que você precisa mostrar uma versão truncada do título do artigo. É possível fazer isso modificando o modelo da seguinte maneira:

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

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

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

O exemplo acima mostra que as chaves são usadas para invocar um auxiliar. O auxiliar excerpt aceita um parâmetro que consiste em uma expressão que determina uma cadeia de caracteres. O auxiliar tem uma opção characters para especificar o número de caracteres que serão mantidos. A opção characters não é obrigatória. Se não a especificar, um valor padrão será usado. Consulte o excerpt nos Modelos da Central de Ajuda para obter mais detalhes.

A sintaxe para invocar um auxiliar é {{<helper> [<param> ...] [<key=value> ...]}}. O único elemento obrigatório é o nome do auxiliar. Os parâmetros e as opções podem variar dependendo do auxiliar.

Agora, suponha que você deseje atualizar o modelo para exibir uma mensagem alegre quando o nome do autor for John Venturini. Infelizmente, não é possível usar uma condição if para verificar se article.author.name é igual a "John Venturini" porque o if funciona apenas em uma expressão. Os operadores de comparação, como == não estão disponíveis.

Então, como adicionar essa lógica? Felizmente, é possível usar o auxiliar is. Ele coleta dois parâmetros e os testa quanto a igualdade. Por exemplo:

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

O trecho de código acima renderiza a mensagem alegre se o autor for John Venturini. Mas e se você desejar renderizar uma mensagem diferente se não for ele? A boa notícia é que o is também pode incluir um bloco else assim como a instrução if-else. Para restaurar a mensagem antiga se o autor não for John Venturini, é possível adicionar um bloco else da seguinte maneira:

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

Alteração de escopo

O acesso a dados é bastante simples com o uso de notação de ponto, especialmente quando o caminho para a informação que precisamos não é muito longo. Por exemplo: article.title. Entretanto, em algumas circunstâncias, você pode desejar acessar uma propriedade com um caminho maior. Por exemplo: article.author.name. Se desejar, é possível usar caminhos maiores nos modelos. Por exemplo, é possível adicionar o avatar e o nome do autor no exemplo, da seguinte maneira:

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

O trecho de código acima funciona adequadamente, mas os caminhos de propriedade longos fazem com que o código fique um pouco poluído. Um modo de resolver o problema é usar o constructo especial with. O with aceita um parâmetro que representa o contexto base a ser usado no bloco de código associado a ele. A sintaxe é a seguinte:

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

É possível melhorar o exemplo da seguinte maneira:

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

O parâmetro article.author elimina a necessidade de incluir article.author em quaisquer caminhos no bloco. Então {{name}} dentro do bloco é equivalente a article.author.name fora do bloco.

Não é possível usar article.author.name, pois ele seria avaliado como article.author.article.author.name. Da mesma forma, não é possível acessar o título do artigo no bloco com article.title, pois o objeto do artigo é acessível apenas no contexto raiz, que está fora do bloco.

Para sair do contexto definido por with e acessar o contexto externo, use a notação ../ no caminho. É possível renderizar o título do artigo dentro do bloco with da seguinte maneira:

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

É possível usar a notação ../ repetidamente no mesmo caminho. Ela voltará para o mesmo número de contextos. O seguinte exemplo ainda funcionará como esperado:

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

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

    ...

{{/with}}

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

Talvez você deseje ser defensivo e renderizar uma mensagem específica sempre que o autor não for especificado. É possível usar um bloco if para fazer isso, da seguinte maneira:

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

Observe que, na Central de Ajuda, article.author nunca é nulo. Aqui, isso é possível apenas como exemplo.

O trecho de código acima funciona perfeitamente, mas é possível obter o mesmo resultado com um bloco else no constructo with. O bloco else é executado se o parâmetro for false. É possível modificar o exemplo da seguinte maneira:

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

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

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

Usar um bloco else também torna o código mais legível.

Como passar o contexto raiz a um auxiliar

Use a palavra-chave this se quiser passar o contexto raiz atual para um auxiliar. Suponha que você tenha um auxiliar render_author que aceita um objeto article como parâmetro para exibir detalhes sobre seu autor. É possível usar a palavra-chave this da seguinte maneira:

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

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

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

this será resolvido como article.

Como acessar itens em uma matriz

Algumas propriedades da Central de Ajuda consistem em matrizes de objetos. Por exemplo, a propriedade attachments consiste em uma matriz de anexos.

Para acessar os itens em uma matriz, é necessário fazer a iteração em cada um deles. O auxiliar each faz exatamente isso. Por exemplo:

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

O trecho de código acima lista todos os anexos. Cada item da lista exibe dados específicos para um anexo, como url, name, e size.

Do mesmo modo que o with, o each muda o contexto em seu bloco. Isso significa que, se você desejar acessar o contexto externo, poderá usar a notação ../.

Você pode desejar renderizar uma mensagem quando uma matriz estiver vazia. É possível fazer isso facilmente usando um bloco if, da seguinte maneira:

...

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

Isso funciona bem, mas você também poderia usar um bloco else para deixar o código mais legível:

...

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

Comprimento

Cada matriz tem uma propriedade length implícita que fornece o número de elementos da matriz. Por exemplo, se você deseja exibir o número de anexos, use a propriedade length da seguinte maneira:

...

There are {{attachments.length}}.

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