Introduction

Chaque thème du Centre d’aide se compose d’un jeu de modèles de pages modifiables qui définissent la mise en page de différents types de pages dans le Centre d’aide. Par exemple, il y a un modèle pour les articles de la base de connaissances, un modèle pour la liste de demandes, etc.

Chaque modèle est composé d’un mélange de balises HTML et d’expressions de type Handlebars, reconnaissables dans le modèle grâce aux doubles accolades. Handlebars est un moteur de création de modèles simple qui vous permet d’insérer ou de manipuler du contenu sur une page au moment du rendu, plutôt qu’au moment de la conception.

Le langage de création de modèles du Centre d’aide s’appelle Curlybars et met en œuvre un vaste sous-ensemble du langage Handlebars. Ce guide vous explique comment utiliser ce langage pour personnaliser les pages de votre Centre d’aide.

Le Centre d’aide vous fournit des aides et des propriétés nommées pour personnaliser votre contenu. Certaines sont partagées et disponibles pour toutes les pages du Centre d’aide. D’autres sont spécifiques à une page.

Exemple

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

Cet exemple génère une liste des utilisateurs qui ont laissé des commentaires sur la page. L’assistant each permet l’itération pour chaque valeur dans la propriété comments de la page. Pour chaque commentaire, les valeurs des propriétés author.avatar_url et author.name sont insérées dans le code HTML.

Remarque – Avant de personnaliser votre Centre d’aide, consultez l’astuce Éviter des temps de chargement médiocres pour le Centre d’aide en suivant les meilleures pratiques de modèles par Jake Bantz.

Bases de la création de modèles

Cette section présente les éléments de base dont vous avez besoin pour écrire n’importe quel modèle. Pour en savoir plus, consultez la section portant sur les modèles du Centre d’aide sur developer.zendesk.com.

Un modèle Curlybars se compose de deux éléments : du texte littéral qui doit être rendu tel quel, et des expressions Curlybars. Cela implique qu’un modèle vide et un modèle ne contenant que du texte sont aussi des modèles valides. Par exemple, ce qui suit est un modèle valide :

<h1>Article</h1>

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

Bien sûr, si les modèles du Centre d’aide ne prenaient en charge que le texte littéral, vous ne pourriez pas vraiment les personnaliser au moment du rendu. Pour ajouter la logique de création de modèles, il vous faut des expressions Curlybars, contenues dans des doubles accolades ({{ et }}).

Pour ajouter une logique de création de modèles à l’exemple précédent, vous pouvez modifier le modèle comme suit :

<h1>Article</h1>

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

{{article.author.name}}

Les sections suivantes expliquent comment écrire des expressions valides pour apporter des modifications pertinentes au modèle.

Attention, l’imbrication d’une paire d’accolades dans une autre paire d’accolades n’est pas une syntaxe valide. Par exemple, ce qui suit n’est pas autorisé :

<h1>Article</h1>

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

{{ {{ ... }} }}

Commentaires

Dans certains cas, il peut s’avérer pratique d’inclure des notes au modèle qui ne s’affichent pas dans la page rendue. À cette fin, Curlybars vous permet d’insérer des commentaires en plaçant un point d’exclamation immédiatement après les accolades de début, sans espace : {{! ... }}. Vous pouvez utiliser cette syntaxe pour ajouter un commentaire dans l’exemple :

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

<h1>Article</h1>

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

Voici ce qui est envoyé au navigateur une fois la page rendue :

<h1>Article</h1>

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

Le fait que tout ce qui se trouve au sein des commentaires soit ignoré peut s’avérer utile quand vous développez un modèle. Vous pouvez mettre certaines parties du code en commentaires pour effectuer des tests, du débogage, etc.

Blocs de commentaires

Malheureusement, la syntaxe de commentaires décrite jusqu’à maintenant ne permet pas de mettre le code Curlybars en commentaires. Pour mettre le code Curlybars en commentaires, utilisez la syntaxe suivante : {{!-- ... ---}}. Ce type de commentaire peut s’étendre sur plusieurs lignes et mettre le code en commentaires. Exemple :

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

--}}

Le modèle ci-dessus est rendu comme suit :

<h1>Article</h1>

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

Littéraux

Pour inclure des valeurs que vous voulez que Curlybars interprète exactement comme elles sont écrites, Curlybars prend en charge le concept de littéraux. Un littéral peut représenter trois types de valeurs : une chaîne, une valeur booléenne ou un nombre.

Pour exprimer une chaîne, vous pouvez utiliser les guillemets simples et doubles, mais vous ne pouvez pas mélanger les deux. Par exemple : 'this is a valid string', "this is valid as well", mais "this is not valid'.

Un nombre peut être un entier positif ou négatif. 123 est un nombre positif valide, +123 représente la même valeur, et 00123 et -123 sont également valides.

Une valeur booléenne est représentée par true et false. Aucune autre variante n’est autorisée. Par exemple, TRUE et FALSE ne sont pas interprétées comme des valeurs booléennes dans Curlybars.

Vous pouvez effectuer le rendu des littéraux. Exemple :

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

La page est rendue comme suit :

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

Propriétés

Chaque modèle du Centre d’aide a accès à un contexte qui représente des données au sujet de votre Centre d’aide. Par exemple, le modèle de page d’article contient un objet intitulé article qui expose la structure de l’article demandé par les utilisateurs. Pour voir toutes les propriétés que vous pouvez utiliser dans vos modèles, consultez la section portant sur les modèles du Centre d’aide sur developer.zendesk.com.

Utilisez la notation par points pour extraire des informations spécifiques de ces objets. Un exemple simple est article.title.

On appelle parfois le nom complet d’une propriété un chemin. Par exemple, name est une propriété de l’objet author, mais article.author.name est son chemin.

Vous pouvez afficher la valeur d’une propriété en la plaçant entre doubles accolades. Revenons à notre exemple. Vous pourriez vouloir afficher le nom de l’auteur dans un paragraphe distinct :

<h1>Article</h1>

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

Supposons qu’un utilisateur veuille voir un article écrit par un agent du nom de John Venturini. Le modèle sera rendu comme suit :

<h1>Article</h1>

<p>Author: John Venturini</p>

Vous pouvez aussi vouloir effectuer le rendu de l’article lui-même. L’objet article a une propriété body qui contient le contenu de l’article. Vous modifieriez le modèle comme suit pour rendre le corps de l’article :

<h1>Article</h1>

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

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

Éléments conditionnels

En plus du rendu des valeurs des propriétés, le langage de création de modèles vous permet d’ajouter une logique de rendu conditionnelle à vos modèles.

Par exemple, vous pourriez vouloir rendre un snippet de code HTML si l’article demandé est interne. Le contexte de la page d’article a une propriété article.internal qui renvoie true si l’article est interne et false si ce n’est pas le cas.

Avec ces informations, vous pouvez créer un bloc if. L’expression if doit spécifier une condition vraie ou fausse. Le rendu du contenu du bloc dépend du résultat. Voici la syntaxe de base :

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

Vous pouvez modifier l’exemple de modèle comme suit :

<h1>Article</h1>

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

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

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

Vous pouvez vouloir effectuer le rendu d’un bloc quand la condition est fausse. Dans ce cas, utilisez un bloc unless. La syntaxe est similaire à celle du bloc if :

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

Revenons à notre exemple. Supposons que vous vouliez aussi rendre un message quand un article n’est pas interne. Vous pouvez modifier le modèle comme suit :

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

Ce type de logique conditionnelle (si vraie, faire ceci, sinon, faire cela) est généralement traitée par un bloc if-else. La syntaxe est la suivante :

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

Vous pouvez modifier l’exemple comme suit :

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

Le bloc unless a également une variante unless-else. Vous pouvez l’utiliser pour obtenir le même résultat qu’avec un bloc 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>

Évaluation des conditions

Une condition est généralement une propriété du Centre d’aide, comme article.internal, qui a une valeur booléenne true ou false. Mais certaines propriétés n’ont pas de valeur booléenne. Ces propriétés sont évaluées comme suit :

  • Si la valeur est un nombre, alors 0 est false et tout autre nombre est true.

  • Si la valeur est une chaîne, une chaîne vide est false et toute autre chaîne est true.

  • Si la valeur est un groupe d’objets, un groupe vide est false et tout autre groupe est true.

  • Si la valeur est nulle, l’expression est false.

Supposons que vous vouliez configurer une logique conditionnelle qui vérifie les nombres. La page d’article a une propriété article.comment_count qui contient le nombre total de commentaires dans un article. Vous pouvez utiliser la condition if pour vérifier que le nombre n’est pas égal à 0 et afficher un message. Exemple :

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

Élimination de l’espace blanc

Quand Curlybars traite un modèle, il affiche tout texte littéral tel quel. C’est une bonne chose et cela fonctionne bien la plupart du temps. Cependant, il peut arriver que vous ayez besoin d’avoir plus de contrôle sur les caractères blancs à côté d’une expression. Prenons le code suivant par exemple :

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

Cela rend le code HTML suivant quand highlighted est vrai :

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

Il y a un espace avant et un espace après le mot highlight. Cela fonctionne, mais supposons que vous vouliez conserver les espaces dans le modèle sans qu’ils soient rendus. Vous pouvez utiliser le tilde (~).

En ajoutant un tilde à l’intérieur de vos accolades de début ou de fin, vous éliminez l’espace blanc du texte qu’elles contiennent. Exemple :

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

Le tilde élimine l’espace avant et l’espace après le mot highlight :

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

Le tilde élimine tout caractère blanc qui n’a pas de représentation graphique mais qui affecte l’espacement ou les lignes de division, comme les nouvelles lignes, les tabulations, retours chariot, sauts de ligne ou espaces simples. Cela veut dire que vous pouvez pousser l’exemple à l’extrême et exprimer le bloc if précédent sur plus de lignes pour une meilleure lisibilité. Exemple :

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

Cela est toujours rendu comme suit :

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

Ces exemples n’ont pas grand sens dans la vie réelle, mais l’efficacité de l’utilisation du tilde peut varier au cas par cas.

Assistants

Accéder aux données, les afficher et ajouter une logique conditionnelle... cela peut vous suffire dans certains modèles. Mais vous pouvez avoir besoin de fonctionnalités supplémentaires. Par exemple, vous voulez peut-être afficher une chaîne traduite qui change en fonction de la langue du demandeur de la page. Ou tronquer un long texte.

Vous pouvez bénéficier de ce type de fonctionnalités dans les modèles grâce aux assistants. Pour voir tous les assistants que vous pouvez utiliser dans vos modèles, consultez la section portant sur les modèles du Centre d’aide sur developer.zendesk.com.

Par exemple, vous pouvez utiliser un assistant intitulé excerpt dans le modèle de page d’article pour tronquer des chaînes. Dans l’exemple d’article, supposons que vous deviez afficher une version tronquée du titre de l’article. Vous pouvez le faire en modifiant le modèle comme suit :

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

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

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

L’exemple ci-dessus indique que les accolades sont utilisées pour invoquer un assistant. L’assistant excerpt accepte un paramètre qui se compose d’une expression dont la résolution est une chaîne. L’assistant a une option characters permettant de spécifier le nombre de caractères à conserver. L’option characters n’est pas obligatoire. Si vous ne la spécifiez pas, une valeur par défaut est utilisée. Voir excerpt dans les modèles du Centre d’aide pour en savoir plus.

La syntaxe pour invoquer un assistant est {{<helper> [<param> ...] [<key=value> ...]}}. Le seul élément obligatoire est le nom de l’assistant. Les paramètres et les options varient selon l’assistant.

Maintenant, supposons que vous vouliez mettre le modèle à jour pour afficher un message de satisfaction quand le nom de l’auteur est John Venturini. Malheureusement, vous ne pouvez pas utiliser de condition if pour vérifier que article.author.name est égal à "John Venturini" car if ne fonctionne qu’avec une seule expression. Les opérateurs de comparaison comme ==, quant à eux, ne sont pas disponibles.

Mais alors, comment ajouter une telle logique ? Heureusement, vous pouvez utiliser l’assistant is. Il prend deux paramètres et les compare pour voir s’ils sont égaux. Exemple :

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

Le snippet ci-dessus rend le message de satisfaction si l’auteur est John Venturini. Mais que faire si vous voulez rendre un autre message s’il s’agit d’un auteur différent ? Eh bien, l’assistant is peut également inclure un bloc else, exactement comme les déclarations if-else. Pour rétablir l’ancien message si l’auteur n’est pas John Venturini, vous pouvez ajouter un bloc else comme suit :

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

Modification de la portée

L’accès aux données est relativement simple avec la notation par points, surtout quand le chemin d’accès aux informations requises est trop long. Exemple : article.title. Mais il est possible que dans certains cas, vous ayez besoin d’accéder à une propriété avec un chemin plus long. Exemple : article.author.name. Vous pouvez utiliser des chemins plus longs dans les modèles. Par exemple, vous pouvez ajouter le nom et l’avatar de l’auteur dans l’exemple, comme suit :

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

Le snippet ci-dessus fonctionne, mais les longs chemins des propriétés rendent le code un peu difficile à lire. Pour éviter ce problème, vous pouvez utiliser la construction spéciale with. with accepte un paramètre qui représente le contexte de base à utiliser dans le bloc de code associé. La syntaxe est la suivante :

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

Vous pouvez améliorer l’exemple comme suit :

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

Le paramètre article.author évite d’avoir à inclure article.author dans les chemins du bloc de code. Ainsi, {{name}} à l’intérieur du bloc correspond à article.author.name hors du bloc.

Vous ne pouvez pas utiliser article.author.name dans le bloc de code car il serait considéré comme article.author.article.author.name. De la même façon, vous ne pouvez pas accéder au titre de l’article dans le bloc de code avec article.title car l’objet de l’article est accessible uniquement dans le contexte racine, qui se trouve hors du bloc de code.

Pour sortir du contexte défini par with et accéder au contexte extérieur, utilisez la notation .../ dans le chemin. Vous pouvez rendre le titre de l’article à l’intérieur du bloc with comme suit :

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

Vous pouvez utiliser la notation .../ plusieurs fois dans le même chemin. Elle remontera en arrière du même nombre de contextes. L’exemple suivant continuera de fonctionner comme prévu :

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

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

    ...

{{/with}}

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

Vous pouvez vouloir adopter une approche proactive et rendre un message spécifique chaque fois que l’auteur n’est pas spécifié. Pour ce faire, vous pouvez utiliser un bloc if comme suit :

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

Remarque – Dans le Centre d’aide, article.author n’est jamais nul. Nous l’avons supposé ici uniquement pour notre exemple.

Le snippet fonctionne, mais vous pouvez obtenir le même résultat avec un bloc else dans la construction with. Le bloc else s’exécute si le paramètre est faux. Vous pouvez modifier l’exemple comme suit :

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

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

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

L’utilisation d’un bloc else facilite également la lecture du code.

Transmission du contexte racine à un aide

Utilisez le mot-clé this pour transmettre le contexte racine actuel à un aide. Supposons que vous ayez un assistant render_author qui accepte un objet article comme paramètre afin d’afficher les détails de son auteur. Vous pouvez utiliser le mot-clé this comme suit :

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

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

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

this sera résolu comme article.

Accès aux éléments d’une collection

Certaines propriétés du Centre d’aide sont des collections d’objets. Par exemple, la propriété attachments est une collection de pièces jointes.

Pour accéder aux éléments de cette collection, vous devez effectuer une itération pour chacune d’entre elles. C’est exactement ce que fait l’assistant each. Exemple :

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

Le snippet ci-dessus affiche la liste de toutes les pièces jointes. Chaque élément de la liste affiche des données spécifiques à une pièce jointe, comme url, name et size.

Comme with, each change le contexte de son bloc. Cela signifie que si vous voulez accéder au contexte extérieur, vous pouvez utiliser la notation ../.

Vous pouvez vouloir effectuer le rendu d’un message quand une collection est vide. Vous pouvez facilement le faire en utilisant un bloc if, comme suit :

...

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

Cela fonctionne, mais vous pourriez aussi utiliser un bloc else pour faciliter la lecture du code :

...

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

Longueur

Chaque collection a une propriété de longueur (length) implicite, qui donne le nombre d’éléments qu’elle contient. Par exemple, si vous voulez afficher le nombre de pièces jointes, utilisez la propriété length comme suit :

...

There are {{attachments.length}}.

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