| Suite | Growth, Professional, Enterprise, or Enterprise Plus |
| Support with | Guide all plans |
Questo articolo include i seguenti argomenti:
- Introduzione
- Nozioni di base sulla creazione di modelli
- Commenti
- Blocca commenti
- Valori letterali
- Proprietà
- Condizionali
- Come vengono valutate le condizioni
- Rimozione dello spazio bianco
- Helper
- Modifica dell’ambito
- Passaggio del contesto radice a un helper
- Accesso agli elementi in un array
- Durata
- Sottoespressioni
Introduzione
Ogni tema centro assistenza è costituito da una raccolta di modelli di pagina modificabili che definiscono il layout dei diversi tipi di pagine nel centro assistenza. Ad esempio, è presente un modello per gli articoli della Knowledge base, un modello per l’elenco delle richieste e così via.
Ogni modello è costituito da una combinazione di markup HTML ed espressioni simili a Handlebar, identificabili nel modello da doppie parentesi graffe. Handlebars è un semplice motore di creazione di modelli che consente di inserire o modificare il contenuto di una pagina in fase di rendering anziché in fase di progettazione.
Il linguaggio di modellazione nel centro assistenza è chiamato Curlybars e implementa un ampio sottoinsieme del linguaggio Handlebars. Questa guida mostra come usare la lingua per personalizzare le pagine nel centro assistenza.
Il centro assistenza fornisce helper e proprietà con nome per personalizzare i contenuti. Alcuni sono condivisi e disponibili in tutte le pagine centro assistenza . Gli altri sono specifici della pagina.
Esempio
{{#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}}
L’esempio genera un elenco di utenti che hanno lasciato commenti sulla pagina. L'helper each itera su ogni valore della proprietà comments della pagina. Per ogni commento, i valori delle proprietà author.avatar_url e author.name vengono inseriti nell’HTML.
Nozioni di base sulla creazione di modelli
Questa sezione presenta gli elementi costitutivi necessari per scrivere qualsiasi modello. Per maggiori informazioni, consulta Modelli del centro assistenza su developer.zendesk.com.
Un modello Curlybars è composto da due elementi: il rendering del testo alla lettera e le espressioni Curlybars. Ciò implica che anche un modello vuoto è un modello valido, così come un modello che contiene solo testo. Ad esempio, il seguente è un modello valido:
<h1>Article</h1>
<p>Some details on the article</p>
Naturalmente, se i modelli del centro assistenza supportassero solo il testo letterale, non sarebbe possibile personalizzarli al momento del rendering. Per aggiungere la logica dei modelli, sono necessarie le espressioni Curlybars, che sono racchiuse tra parentesi graffe doppie ({{ e }}).
Per aggiungere la logica dei modelli all'esempio precedente, puoi modificare il modello come segue:
<h1>Article</h1>
<p>Some details on the article</p>
{{article.author.name}}
Le sezioni seguenti spiegano come scrivere espressioni valide per apportare modifiche significative al modello.
Tieni presente che la nidificazione di una coppia di curl all’interno di un’altra coppia di curl non è una sintassi valida. Ad esempio, non sono consentiti i seguenti valori:
<h1>Article</h1>
<p>Some details on the article</p>
{{ {{ ... }} }}
Commenti
Ci sono situazioni in cui potrebbe essere utile avere alcune note nel modello che non perdono nella pagina sottoposta a rendering. A questo scopo, Curlybars consente di aggiungere commenti mettendo un punto esclamativo subito dopo le parentesi graffe di apertura, senza alcuno spazio: {{! ... }}. Puoi usare questa sintassi per aggiungere un commento al codice nell’esempio:
{{!
This template aims to
show details of an article
}}
<h1>Article</h1>
<p>Some details on the article</p>
Ecco cosa viene inviato al browser dopo il rendering della pagina:
<h1>Article</h1>
<p>Some details on the article</p>
Questo effetto di scartare qualsiasi cosa all’interno dei commenti può tornare utile durante lo sviluppo di un modello. Potresti voler commentare del codice per fare dei controlli, eseguire il debug e altro ancora.
Blocca commenti
Purtroppo, la sintassi dei commenti descritta finora non è adatta per aggiungere commenti al codice Curlybars. Per aggiungere commenti al codice Curlybars, usa la sintassi seguente: {{!-- ... ---}}. Questo tipo di commento può estendersi su più righe e commentare efficacemente il codice. Esempio:
{{!
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 }}
--}}
Il modello qui sopra viene visualizzato come segue:
<h1>Article</h1>
<p>Some details on the article</p>
Valori letterali
Per includere i valori che vuoi che Curlybars interpreti esattamente come sono stati scritti, Curlybars supporta il concetto di letterali. Un valore letterale può rappresentare 3 tipi di valori: a string, a booleano a number.
Per scrivere una stringa, puoi usare sia le virgolette singole che quelle doppie, ma non puoi combinarle. Ad esempio, 'this is a valid string', "this is valid as well", ma "this is not valid'.
Un numero può essere qualsiasi numero intero positivo o negativo. 123 è un numero positivo valido, +123 rappresenta lo stesso valore, 00123 è ancora valido, e -123 è valido.
Un valore booleano è rappresentato da true e false. Non sono consentite altre varianti. Ad esempio, TRUE e FALSE non sono interpretati come valori booleani in Curlybars.
Puoi eseguire il rendering di valori letterali. Esempio:
A string: {{ 'hello world' }}
A boolean: {{ true }}
A number: {{ 42 }}
La pagina viene visualizzata come segue:
A string: 'hello world'
A boolean: true
A number: 42
Proprietà
Ogni modello nel centro assistenza ha accesso a un contesto che rappresenta i dati sul centro assistenza. Ad esempio, il modello Pagina articolo ha un oggetto denominato article che espone la struttura dell’articolo richiesto dagli utenti. Per tutte le proprietà che puoi usare nei modelli, consulta Modelli del Centro assistenza su developer.zendesk.com.
Usa la notazione con punti per estrarre informazioni specifiche da questi oggetti. Un semplice esempio è article.title.
Il nome completo di una proprietà è talvolta detto percorso. Ad esempio, name è una proprietà nell'oggetto author, ma article.author.name è il suo percorso.
Puoi visualizzare il valore di una proprietà racchiudendolo tra parentesi graffe doppie. Tornando all’esempio, potresti voler stampare il nome dell’autore in un paragrafo separato:
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
Supponiamo che un utente voglia vedere un articolo scritto da un agente di nome John Venturini. Il rendering del modello verrà eseguito come segue:
<h1>Article</h1>
<p>Author: John Venturini</p>
Potresti anche voler eseguire il rendering dell’articolo stesso. L'oggetto article ha una proprietà body che contiene il contenuto dell’articolo. Per visualizzare il corpo dell’articolo, devi modificare il modello come segue:
<h1>Article</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
Condizionali
Oltre al rendering dei valori delle proprietà, il linguaggio di creazione di modelli consente di aggiungere la logica di rendering condizionale ai modelli.
Ad esempio, potresti voler eseguire il rendering di un frammento di codice HTML nel caso in cui l’articolo richiesto sia interno. Il contesto Pagina articolo ha una proprietà article.internal che restituisce true se l’articolo è interno e false in caso contrario.
Puoi creare un if blocco con queste informazioni. L'espressione if deve specificare una condizione vera o falsa. Il risultato determina se il contenuto del blocco viene visualizzato o meno. Ecco la sintassi di base:
{{#if condition}}
This is rendered if the condition is true.
{{/if}}
Puoi modificare il modello di esempio come segue:
<h1>Article</h1>
{{#if article.internal}}
<p>This article is internal.</p>
{{/if}}
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
Potresti voler eseguire il rendering di un blocco quando la condizione è falsa. In tal caso, usa un blocco unless. La sintassi è simile al blocco if:
{{#unless condition}}
This is rendered if the condition is false.
{{/unless}}
Tornando all’esempio, supponiamo di voler visualizzare anche un messaggio quando un articolo non è interno. Puoi modificare il modello come segue:
<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>
Questo tipo di logica condizionale ("se vero fai questo, altrimenti fai quest'altro") viene generalmente gestito da un blocco if-else. La sintassi è la seguente:
{{#if condition}}
This is rendered if the condition is true.
{{else}}
This is rendered if the condition is false.
{{/if}}
Puoi modificare l’esempio come segue:
<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>
Il blocco unless ha anche una variante unless-else. Puoi usarla per ottenere lo stesso risultato che si ottiene con il blocco 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>
Come vengono valutate le condizioni
Una condizione è in genere una proprietà del centro assistenza come article.internal, con valore booleano true o false. Alcune proprietà non hanno valori booleani. Queste proprietà vengono valutate come segue:
-
Se il valore è un numero, 0 è false e qualsiasi altro numero è true
-
Se il valore è una stringa, una stringa vuota è false e qualsiasi altra stringa è true
-
Se il valore è una raccolta di oggetti, una raccolta vuota è false e qualsiasi altra raccolta è true
-
Se il valore è null, l’espressione è false
Supponiamo di voler impostare una logica condizionale per il controllo dei numeri. La pagina dell’articolo ha un article.comment_count contenente il numero totale di commenti in un articolo. Puoi usare la condizione if per verificare se il conteggio non è 0 e mostrare un messaggio incoraggiante. Esempio:
<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}}
Rimozione dello spazio bianco
Quando Curlybars elabora un modello, visualizza il testo letterale così com’è. Va bene e funziona bene per la maggior parte del tempo. Tuttavia, a volte è necessario avere maggiore controllo sui caratteri vuoti accanto a un'espressione. Prendi ad esempio il codice seguente:
<a href="..." class="{{#if highlighted}} highlight {{/if}}">Click me!</a>
Rende il codice HTML seguente quando highlighted è vero:
<a href="..." class=" highlight ">Click me!</a>
Attorno alla parola evidenziazionesono presenti uno spazio iniziale e uno finale. Ovviamente funziona bene, ma supponiamo di voler mantenere gli spazi nel modello senza renderli. Puoi usare il carattere tilde (~).
L’aggiunta di un carattere tilde nelle parentesi graffe di apertura o chiusura riduce lo spazio bianco dal testo racchiuso. Esempio:
<a href="..." class="{{#if highlighted~}} highlight {{~/if}}">Click me!</a>
I caratteri tilde ritagliano gli spazi iniziali e finali intorno alla parola evidenziano:
<a href="..." class="highlight">Click me!</a>
Il carattere tilde taglia qualsiasi carattere vuoto che non ha una rappresentazione grafica ma influisce sulla spaziatura o sulle righe divise, come nuove righe, tabulazioni, ritorni a capo, avanzamenti di riga, spazi semplici o tabulazioni. Ciò significa che puoi portare l’esempio all’estremo e scrivere il blocco if precedente su più righe per renderlo più leggibile. Esempio:
<a href="..." class="
{{~#if highlighted~}}
highlight
{{~/if~}}
">Click me!</a>
Il rendering è ancora il seguente:
<a href="..." class="highlight">Click me!</a>
Questi esempi non hanno molto senso nella realtà, ma l’efficacia dell’uso del carattere tilde può variare da caso a caso.
Aiutanti
L’accesso ai dati, la loro visualizzazione e l’aggiunta di logica condizionale possono essere tutto ciò che serve in alcuni modelli. Tuttavia, potrebbero interessarti alcune funzionalità aggiuntive. Ad esempio, potresti voler visualizzare una stringa localizzata che cambia in base alle impostazioni locali del richiedente della pagina. Oppure potresti voler troncare un lungo passaggio di testo.
Puoi ottenere questo tipo di funzionalità nei modelli con helper. Per tutti gli helper che puoi usare nei modelli, consulta Modelli del Centro assistenza su developer.zendesk.com.
Ad esempio, puoi usare un helper denominato excerpt nel modello di pagina Articolo per troncare le stringhe. Nell’esempio dell’articolo, supponi di dover mostrare una versione troncata del titolo dell’articolo. Puoi farlo modificando il modello come segue:
<h1>{{excerpt article.title characters=50}}</h1>
<p>Author: {{article.author.name}}</p>
<article>{{article.body}}</article>
L’esempio qui sopra mostra che le parentesi graffe vengono usate per richiamare un helper. Il excerpt helper accetta un parametro costituito da un’espressione che si risolve in una stringa. L’helper ha un'opzione characters per specificare il numero di caratteri da mantenere. L'opzione characters non è obbligatoria. Se non specifichi alcun valore, viene usato un valore predefinito. Per maggiori dettagli, consulta l’estratto in Modelli del centro assistenza.
La sintassi per richiamare un helper è {{<helper> [<param> ...] [<key=value> ...]}}. L’unico elemento obbligatorio è il nome dell’helper. I parametri e le opzioni variano a seconda dell’helper.
Supponiamo ora di voler aggiornare il modello per visualizzare un messaggio allegro quando l’autore si chiama John Venturini. Purtroppo non è possibile usare una condizione if per verificare se article.author.name è uguale a "John Venturini", perché if funziona su una sola espressione. Operatori di confronto come == non sono disponibili.
Come aggiungere una logica del genere, quindi? Fortunatamente, puoi usare l'helper is. Prende due parametri e ne verifica l’uguaglianza. Esempio:
<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>
Il frammento di codice qui sopra rende il messaggio allegro se l’autore è John Venturini. Ma cosa succede se vuoi visualizzare un messaggio diverso se non è lui? La buona notizia è che is può includere anche un blocco else, proprio come l'istruzione if-else. Per ripristinare il vecchio messaggio se l’autore non è John Venturini, puoi aggiungere un else bloccare come segue:
<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>
Modifica dell’ambito
L’accesso ai dati è piuttosto semplice usando la notazione a punti, soprattutto quando il percorso verso le informazioni di cui abbiamo bisogno non è troppo lungo. Esempio: article.title. In alcune circostanze, tuttavia, potresti voler accedere a una proprietà con un percorso più lungo. Esempio: article.author.name. Se lo desideri, puoi usare percorsi più lunghi nei modelli. Ad esempio, puoi aggiungere il nome dell’autore e l’avator nell’esempio come segue:
<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>
Il frammento di codice qui sopra funziona perfettamente, ma i percorsi delle proprietà lunghi fanno sembrare il codice un po’ disordinato. Un modo per aggirare il problema è usare lo speciale with costrutto. with accetta un parametro che rappresenta il contesto di base da usare nel blocco di codice ad esso associato. La sintassi è la seguente:
{{#with <context>}}
...
{{/with}}
Puoi migliorare l’esempio come segue:
<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>
Il parametro article.author elimina la necessità di includere article.author in qualsiasi percorso nel blocco. Quindi {{name}} all’interno del blocco è equivalente a article.author.name al di fuori del blocco.
Non puoi usare article.author.name nel blocco perché verrebbe valutato come article.author.article.author.name. Allo stesso modo, non puoi accedere al titolo dell’articolo nel blocco con article.title perché l’oggetto article è accessibile solo nel contesto radice, che è esterno al blocco.
Per uscire dal contesto impostato da with e accedere al contesto esterno, usa la notazione ../ nel percorso. Puoi visualizzare il titolo dell’articolo all’interno del blocco with come segue:
<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>
Puoi usare la notazione ../ più volte nello stesso percorso. Tornerai indietro dello stesso numero di livelli nel contesto. Ad esempio, il seguente esempio funzionerà ancora come previsto:
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{#with author}}
{{../../article.title}}
...
{{/with}}
<article>{{article.body}}</article>
Potresti voler essere sulla difensiva e visualizzare un messaggio specifico ogni volta che l’autore non è specificato. Per farlo, puoi decidere di usare un blocco if, come nell'esempio seguente:
<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>
Tieni presente che nel Centro assistenza article.author in realtà non è mai nullo. Qui abbiamo fatto questa assunzione solo a scopo di esempio.
Il frammento di codice qui sopra funziona perfettamente, ma puoi ottenere lo stesso risultato con un blocco else nel costrutto with. Il blocco else viene eseguito se il parametro è falso. Puoi modificare l’esempio come segue:
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article.author}}
...
{{else}}
No author is present for this article!
{{/with}}
<article>{{article.body}}</article>
Anche l'utilizzo di un blocco else rende il codice più leggibile.
Passaggio del contesto radice a un helper
Usa la parola chiave this per passare il contesto radice attuale a un helper. Supponiamo di avere a render_author helper che accetta un article oggetto come parametro per visualizzare i dettagli sul suo autore. Puoi usare la parola chiave this nel modo seguente:
<h1>{{excerpt article.title characters=50}}</h1>
{{#with article}}
{{render_author this}}
{{/with}}
<article>{{article.body}}</article>
this verrà risolto come article.
Accesso agli elementi in un array
Alcune proprietà centro assistenza sono costituite da array di oggetti. Ad esempio, la proprietà attachments è costituita da un array di allegati.
Per accedere agli elementi di un array, è necessario scorrerli uno a uno. L'helper each fa esattamente questo. Esempio:
<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}}
Il frammento di codice qui sopra elenca tutti gli allegati. Ciascun elemento dell’elenco mostra i dati specifici di un allegato, come url, name e size.
Mi piace with, each cambia il contesto nel relativo blocco. Ciò significa che se vuoi accedere al contesto esterno puoi usare la notazione ../.
Potresti voler visualizzare un messaggio quando un array è vuoto. Puoi facilmente ottenere questo risultato usando un blocco if, come mostrato di seguito:
...
{{#if attachments}}
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
{{else}}
Sorry, no attachments available!
{{/if}}
Questo funziona benissimo, ma puoi anche usare un blocco else per rendere il codice più leggibile:
...
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{else}}
Sorry, no attachments available!
{{/each}}
Durata
Ogni array ha una proprietà length implicita che restituisce il numero di elementi presenti nell’array. Ad esempio, se vuoi visualizzare il numero di allegati, usa la proprietà length come mostrato di seguito:
...
There are {{attachments.length}}.
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}Sottoespressioni
Le sottoespressioni consentono di richiamare più helper in una singola espressione e di passare i risultati delle chiamate degli helper interni come argomenti agli helper esterni. Le sottoespressioni sono delimitate da parentesi.
L’esempio seguente mostra una sottoespressione in un’espressione:
{{search placeholder=(dc "search_text")}}
Le sottoespressioni possono essere nidificate:
{{search placeholder=(excerpt (dc "search_text"))}}
Le sottoespressioni possono essere usate negli helper condizionali:
{{#if (compare collection.length "==" 0)}}
<div>Empty collection.</div>
{{else}}
<div>Your collection has {{collection.length}} items</div>
{{/if}}
Le sottoespressioni possono essere usate negli helper degli iteratori di array:
{{#each (slice (filter user.badges on="category_slug" equals="achievements")
0 4)}}
<section>
<h3>{{name}}</h3>
<div>{{description}}</div>
</section>
{{/each}}
0 commenti