Questo articolo include i seguenti argomenti:
- Introduzione
- Nozioni di base sui modelli
- Commenti
- Blocca commenti
- Valori letterali
- Proprietà
- Condizionali
- Modalità di valutazione delle condizioni
- Ritaglio dello spazio bianco
- Aiutanti
- Modifica dell’ambito
- Come passare il contesto radice a un helper
- Accesso agli elementi in un array
- Durata
- Sottoespressioni
Introduzione
Ogni tema del 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 è composto da una combinazione di markup HTML ed espressioni simili a Handlebars, 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 creazione dei modelli nel centro assistenza si chiama 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 del 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. Il each l’helper scorre ogni valore nella pagina comments proprietà. Per ogni commento, i valori di author.avatar_url e author.name vengono inserite nell’HTML.
Nozioni di base sui modelli
Questa sezione presenta gli elementi costitutivi necessari per scrivere qualsiasi modello. Per maggiori informazioni, consulta Modelli per Centro assistenza all’indirizzo developer.zendesk.com.
Un modello Curlybars è composto da due elementi: il testo da visualizzare alla lettera e le espressioni Curlybars. Ciò implica che anche un modello vuoto è valido e anche un modello contenente solo testo. Ad esempio, il seguente è un modello valido:
<h1>Article</h1>
<p>Some details on the article</p>
Ovviamente, se i modelli del centro assistenza supportano solo il testo letterale, non potresti 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 del modello 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 l’annidamento di una coppia di curl all’interno di un’altra coppia di curl non è una sintassi valida. Ad esempio, quanto segue non è consentito:
<h1>Article</h1>
<p>Some details on the article</p>
{{ {{ ... }} }}
Commenti
Ci sono situazioni in cui potrebbe essere utile avere delle note nel modello che non vengono inserite nella pagina visualizzata. A tale scopo, Curlybars permette di aggiungere commenti mettendo un punto esclamativo subito dopo i ricci di apertura, senza spazi: {{! ... }}. Puoi usare questa sintassi per aggiungere un commento di 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>
L’effetto di scartare qualsiasi cosa all’interno dei commenti può tornare utile durante lo sviluppo di un modello. Ti consigliamo di aggiungere dei commenti al codice per eseguire controlli, debug e altro.
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 seguente sintassi: {{!-- ... ---}}. Questo tipo di commento può estendersi su più righe e commentare il codice in modo efficace. 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 valori che Curlybars interpreta esattamente come sono stati scritti, supporta il concetto di letterali. Un valore letterale può rappresentare 3 tipi di valori: a string, a booleano a number.
Per esprimere una stringa, puoi usare sia virgolette singole che doppie, ma non possono essere mischiate. 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 booleani in Curlybars.
Puoi renderizzare i valori letterali. Esempio:
A string: {{ 'hello world' }}
A boolean: {{ true }}
A number: {{ 42 }}
Il rendering della pagina è il seguente:
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 del 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 tuoi modelli, consulta Modelli del Centro assistenza all’indirizzo developer.zendesk.com.
Usa la notazione con i punti per ricavare informazioni specifiche da questi oggetti. Un semplice esempio: article.title.
Il nome completo di una proprietà viene talvolta chiamato percorso. Ad esempio, name è una proprietà nel author oggetto, 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 desideri vedere un articolo scritto da un agente di nome John Venturini. Il rendering del modello sarà il seguente:
<h1>Article</h1>
<p>Author: John Venturini</p>
Potresti anche voler rendere l’articolo stesso. Il article l’oggetto ha a 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 della pagina dell’articolo ha un article.internal proprietà restituita true se l’articolo è interno e false in caso contrario.
Puoi creare un if blocco con queste informazioni. Il if l’espressione 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 file unless blocco. La sintassi è simile a quella di if blocco:
{{#unless condition}}
This is rendered if the condition is false.
{{/unless}}
Tornando all’esempio, supponiamo di voler eseguire il rendering di un messaggio anche 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 true, fai questo oppure fai quest'altro" - viene in genere gestito da un'istanza if-else blocco. 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 unless blocco ha anche l’estensione unless-else variante. Puoi usarlo per ottenere gli stessi risultati di un if-else blocco:
<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>
Modalità di valutazione delle 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, allora 0 è falso e qualsiasi altro numero è vero
-
Se il valore è una stringa, una stringa vuota è falsa e qualsiasi altra stringa è vera
-
Se il valore è una raccolta di oggetti, una raccolta vuota è falsa e qualsiasi altra raccolta è vera
-
Se il valore è null, l’espressione è false
Supponiamo di voler impostare una logica condizionale per il controllo dei numeri. La pagina degli articoli ha un article.comment_count contenente il numero totale di commenti in un articolo. Puoi usare il if condizione per verificare se il conteggio non lo è 0 e visualizza un messaggio allegro. 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}}
Ritaglio dello spazio bianco
Quando Curlybars elabora un modello, visualizza il testo alla lettera così com’è. Va bene e funziona bene la maggior parte delle volte. 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 seguente codice HTML when highlighted è vero:
<a href="..." class=" highlight ">Click me!</a>
Intorno alla parola evidenziatasono presenti uno spazio iniziale e uno finale. Ovviamente funziona correttamente, ma supponiamo che tu voglia mantenere gli spazi nel modello senza renderizzarli. Puoi usare il carattere tilde (~).
Aggiungendo una tilde nelle parentesi graffe di apertura o chiusura, si riducono gli spazi vuoti dal testo incluso. Esempio:
<a href="..." class="{{#if highlighted~}} highlight {{~/if}}">Click me!</a>
I caratteri tilde rifilano gli spazi iniziali e finali intorno alla parola e 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 linee divise, come i nuovi a capo, i caratteri di tabulazione, i ritorni a capo, gli avanzamenti di riga, gli spazi semplici o i caratteri di tabulazione. Ciò significa che puoi portare l’esempio all’estremo ed esprimere il precedente if bloccare 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 essere utili 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 tuoi modelli, consulta Modelli del Centro assistenza all’indirizzo developer.zendesk.com.
Ad esempio, puoi usare un helper chiamato excerpt nel modello di pagina Articoli per troncare le stringhe. Nell’articolo di esempio, 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 characters per specificare il numero di caratteri da conservare. Il characters l’opzione non è obbligatoria. Se non lo specifichi, viene usato un valore predefinito. Per maggiori dettagli, consulta l’ estratto in Modelli del Centro assistenza.
La sintassi per richiamare un helper è {{. L’unico elemento obbligatorio è il nome dell’helper. I parametri e le opzioni variano in base all’helper.
Supponiamo ora di voler aggiornare il modello in modo da visualizzare un messaggio allegro quando l’autore si chiama Giovanni Venturini. Purtroppo non puoi usare un file if condizione per verificare se article.author.name è uguale a "John Venturini" perché if funziona solo su un’espressione. Operatori di confronto come == non sono disponibili.
Come aggiungere una tale logica, quindi? Fortunatamente, puoi usare il is helper. 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 rendere un messaggio diverso se non è lui? La buona notizia è che is può includere anche un file else come il blocco if-else istruzione. Per ripristinare il vecchio messaggio se l’autore non è John Venturini, puoi aggiungere un file 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, specialmente 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 vuoi, 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 consiste nell’usare la funzione 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 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 definito da with e accedi al contesto esterno, usa l’estensione ../ notazione nel percorso. Puoi renderizzare il titolo dell’articolo all’interno del file with bloccare 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 il ../ più volte nello stesso percorso. Tornerà indietro nello stesso numero di contesti. 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>
Ti consigliamo di metterti sulla difensiva ed eseguire il rendering di un messaggio specifico ogni volta che non viene specificato l’autore. Potresti decidere di usare an if blocco per farlo, come segue:
<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. L’abbiamo assunto qui solo ai fini dell’esempio.
Il frammento di codice qui sopra funziona perfettamente, ma puoi ottenere lo stesso risultato con un else blocco nel file with costrutto. Se il parametro è falso, viene eseguito il blocco else. 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>
Usando un else block rende il codice più leggibile.
Come passare il contesto radice a un helper
Usa il this per passare il contesto radice corrente a un helper. Supponiamo di avere a render_author helper che accetta un article oggetto come parametro per visualizzare dettagli sul suo autore. Puoi usare il this parola chiave come segue:
<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à del centro assistenza sono costituite da array di oggetti. Ad esempio, il file attachments è composta da un array di allegati.
Per accedere agli elementi in un array, devi scorrere ognuno di essi. Il each helper 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. Ogni elemento dell’elenco visualizza i dati specifici di un allegato, come il suo 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 il file ../ notazione.
Potresti voler rendere un messaggio quando un array è vuoto. Puoi facilmente ottenere questo risultato usando un file if blocco, come segue:
...
{{#if attachments}}
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{/each}}
{{else}}
Sorry, no attachments available!
{{/if}}
Funziona bene, ma puoi anche usare un file else per facilitare la lettura del codice:
...
{{#each attachments}}
<a href="{{url}}" target="_blank">{{name}}</a>
<span>({{size}})</span>
{{else}}
Sorry, no attachments available!
{{/each}}
Durata
Ogni array ha un valore implicito length che fornisce il numero di elementi nell’array. Ad esempio, se vuoi visualizzare il numero di allegati, usa il file length proprietà come segue:
...
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 all’interno di 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 annidate:
{{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}}
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.