Introduction

Chaque thème du Centre d’aide se compose d’un jeu demodèles de pages modifiables, definissent 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.Handlebarsest 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’appelleCurlybarset 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.

勒中心d 'aide你们fournit des助手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}} 
 
  
 
 
  {{author.name}}  
 
 
 {{/each}}

Cet exemple génère une liste des utilisateurs qui ont laissé des commentaires sur la page. L’assistanteachpermet l’itération pour chaque valeur dans la propriétécommentsde la page. Pour chaque commentaire, les valeurs des propriétésauthor.avatar_urletauthor.namesont insérées dans le code HTML.

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 lesmodèles du Centre d’aidesur 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 :

Article
 
Some details on the article

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 :

Article
 
Some details on the article
 {{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é :

Article
 
Some details on the article
 {{ {{ ... }} }}

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 }} 
Article
 
Some details on the article

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

Article
 
Some details on the article

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 }} 
Article
 
Some details on the article
 {{!-- I want to commend out the following code: {{ ... some Curlybars expressions }} --}}

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

Article
 
Some details on the article

Littéraux

Pour inclure des valeurs que vous voulez que Curlybars interprète exactement comme elles sont écrites, Curlybars prend en charge le concept delittéraux. Un littéral peut représenter trois types de valeurs : unechaîne, unevaleur booléenneou unnombre.

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“这不是有效的.

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

Une valeur booléenne est représentée partrueetfalse. Aucune autre variante n’est autorisée. Par exemple,TRUEetFALSEne 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 à uncontextequi 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éarticlequi 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 lesmodèles du Centre d’aidesur developer.zendesk.com.

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

On appelle parfois le nom complet d’une propriété unchemin. Par exemple,nameest une propriété de l’objetauthor, maisarticle.author.nameest 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 :

Article
 
Author: {{article.author.name}}

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

Article
 
Author: John Venturini

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

Article
 
Author: {{article.author.name}}
 
{{article.body}}

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

比如,你们将vouloir rendre联合国snippet de code HTML si l’article demandé est interne. Le contexte de la page d’article a une propriétéarticle.internalqui renvoietruesi l’article est interne etfalsesi ce n’est pas le cas.

Avec ces informations, vous pouvez créer un blocif. L’expressionifdoit 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 :

Article
 {{#if article.internal}} 
This article is internal.
 {{/if}} 
Author: {{article.author.name}}
 
{{article.body}}

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

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

Article
 {{#if article.internal}} 
This article is internal.
 {{/if}} {{#unless article.internal}} 
This is a publicly visible article!
 {{/unless}} 
Author: {{article.author.name}}
 
{{article.body}}

Ce type de logique conditionnelle (si vraie, faire ceci, sinon, faire cela) est généralement traitée par un blocif-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 :

Article
 {{#if article.internal}} 
This article is internal.
 {{else}} 
This is a publicly visible article!
 {{/if}} 
Author: {{article.author.name}}
 
{{article.body}}

Le blocunlessa également une varianteunless-else. Vous pouvez l’utiliser pour obtenir le même résultat qu’avec un blocif-else:

Article
 {{#unless article.internal}} 
This is a publicly visible article!
 {{else}} 
This article is internal.
 {{/unless}} 
Author: {{article.author.name}}
 
{{article.body}}

Évaluation des conditions

Une condition est généralement une propriété du Centre d’aide, commearticle.internal, qui a une valeur booléennetrueoufalse. 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.

• 如果数值是联合国groupe d 'objets,联合国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_countqui contient le nombre total de commentaires dans un article. Vous pouvez utiliser la conditionifpour vérifier que le nombre n’est pas égal à0et afficher un message. Exemple :

Article
 
Author: {{article.author.name}}
 
{{article.body}}
 {{#if article.comment_count}} 
Yahoo! This article has got some comments!
 {{/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 :

Click me!

Cela rend le code HTML suivant quandhighlightedest vrai :

Click me!

Il y a un espace avant et un espace après le mothighlight. 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 :

Click me!

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

Click me!

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 blocifprécédent sur plus de lignes pour une meilleure lisibilité. Exemple :

Click me!

Cela est toujours rendu comme suit :

Click me!

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 auxassistants. Pour voir tous les assistants que vous pouvez utiliser dans vos modèles, consultez la section portant sur lesmodèles du Centre d’aidesur developer.zendesk.com.

Par exemple, vous pouvez utiliser un assistant intituléexcerptdans 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 :

{{excerpt article.title characters=50}}
 
Author: {{article.author.name}}
 
{{article.body}}

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

La syntaxe pour invoquer un assistant est{{ [ ...] [ ...]}}. 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 conditionifpour vérifier quearticle.author.nameest égal à"John Venturini"carifne 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’assistantis. Il prend deux paramètres et les compare pour voir s’ils sont égaux. Exemple :

{{excerpt article.title characters=50}}
 {{#is article.author.name 'John Venturini'}} 
Cool! John Venturini is the author of this article!
 {{/is}} 
{{article.body}}

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’assistantispeut également inclure un blocelse, exactement comme les déclarationsif-else. Pour rétablir l’ancien message si l’auteur n’est pas John Venturini, vous pouvez ajouter un blocelsecomme suit :

{{excerpt article.title characters=50}}
 {{#is article.author.name 'John Venturini'}} 
Cool! John Venturini is the author of this article!
 {{else}} 
Author: {{article.author.name}}
 {{/is}} 
{{article.body}}

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 :

{{excerpt article.title characters=50}}
  {{#is article.author.name 'John Venturini'}} 
Cool! John Venturini is the author of this article!
 {{else}} 
Author: {{article.author.name}}
 {{/is}} 
{{article.body}}

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écialewith.withaccepte un paramètre qui représente le contexte de base à utiliser dans le bloc de code associé. La syntaxe est la suivante :

{{#with }} ... {{/with}}

Vous pouvez améliorer l’exemple comme suit :

{{excerpt article.title characters=50}}
 {{#with article.author}}  {{#is name 'John Venturini'}} 
Cool! John Venturini is the author of this article!
 {{else}} 
Author: {{name}}
 {{/is}} {{/with}} 
{{article.body}}

Le paramètrearticle.authorévite d’avoir à inclurearticle.authordans les chemins du bloc de code. Ainsi,{{name}}à l’intérieur du bloc correspond àarticle.author.namehors du bloc.

Vous ne pouvez pas utiliserarticle.author.namedans le bloc de code car il serait considéré commearticle.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 avecarticle.titlecar 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 parwithet accéder au contexte extérieur, utilisez la notation .../dans le chemin. Vous pouvez rendre le titre de l’article à l’intérieur du blocwithcomme suit :

{{excerpt article.title characters=50}}
 {{#with article.author}} {{../article.title}}  {{#is name 'John Venturini'}} 
Cool! John Venturini is the author of this article!
 {{else}} 
Author: {{name}}
 {{/is}} {{/with}} 
{{article.body}}

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 :

{{excerpt article.title characters=50}}
 {{#with article}} {{#with author}} {{../../article.title}} ... {{/with}} 
{{article.body}}

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 blocifcomme suit :

{{excerpt article.title characters=50}}
 {{#if article.author}} {{#with article.author}} ... {{/with}} {{else}} No author is present for this article! {{/if}} 
{{article.body}}

Remarque – Dans le Centre d’aide,article.authorn’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 blocelsedans la constructionwith. Le bloc else s’exécute si le paramètre est faux. Vous pouvez modifier l’exemple comme suit :

{{excerpt article.title characters=50}}
 {{#with article.author}} ... {{else}} No author is present for this article! {{/with}} 
{{article.body}}

L’utilisation d’un blocelsefacilite également la lecture du code.

Transmission du contexte racine à un aide

Utilisez le mot-cléthispour transmettre le contexte racine actuel à un aide. Supposons que vous ayez un assistantrender_authorqui accepte un objetarticlecomme paramètre afin d’afficher les détails de son auteur. Vous pouvez utiliser le mot-cléthiscomme suit :

{{excerpt article.title characters=50}}
 {{#with article}} {{render_author this}} {{/with}} 
{{article.body}}

thissera résolu commearticle.

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éattachmentsest 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’assistanteach. Exemple :

{{excerpt article.title characters=50}}
 {{#with article.author}} ... {{/with}} 
{{article.body}}
 {{#each attachments}} {{name}} ({{size}}) {{/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, commeurl,nameetsize.

Commewith,eachchange 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 blocif, comme suit :

... {{#if attachments}} {#each attachments}} {{name}} ({{size}}) {{/each}} {{else}} Sorry, no attachments available! {{/if}}

Cela fonctionne,但是你们将也使用un blocelsepour faciliter la lecture du code :

... {#each attachments}} {{name}} ({{size}}) {{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élengthcomme suit :

... There are {{attachments.length}}. {#each attachments}} {{name}} ({{size}}) {{/each}}