Verwenden der Help-Center-Vorlagensprache (Guide Professional)

Einführung

Jedes Help-Center-Design besteht aus einer Sammlung bearbeitbarer Seitenvorlagen, die das Layout unterschiedlichen Seitenarten im Help Center definieren. So gibt es zum Beispiel eine Vorlage für Wissensdatenbankbeiträge, eine Vorlage für die Anfragenliste usw.

Jede Vorlage besteht aus einer Mischung aus HTML-Markup und Handlebars-ähnlichen Ausdrücken, die in der Vorlage anhand doppelter geschweifter Klammern erkennbar sind. Handlebars ist eine einfache Template-Engine, mit der Sie Inhalte in eine Seite einfügen oder bearbeiten können, und zwar zum Darstellungs- anstatt zum Designzeitpunkt.

Die Vorlagensprache im Help Center heißt Curlybars und implementiert einen Großteil der Handlebars-Sprache. Dieser Leitfaden zeigt Ihnen, wie Sie mithilfe von Curlybars Ihre Seiten im Help Center anpassen können.

Im Help Center gibt es Helper sowie benannte Eigenschaften zum Anpassen von Seiteninhalten. Manche davon sind auf allen Help-Center-Seiten verfügbar, andere sind seitenspezifisch.

Beispiel

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

Dieses Beispiel generiert eine Liste mit Benutzern, die auf einer Seite Kommentare hinterlassen haben. Der Helper each geht durch jeden Wert in der Eigenschaft comments der Seite. Für jeden Kommentar werden die Werte der Eigenschaften author.avatar_url und author.name in den HTML-Code eingefügt.

Hinweis: Bevor Sie Änderungen an Ihrem Help Center vornehmen, sollten Sie diesen Support-Tipp von Jake Bantz lesen: Durch Befolgen von Best Practices für Vorlagen langsame Ladezeiten im Help Center verhindern.

Grundlagen der Vorlagenerstellung

In diesem Abschnitt stellen wir die Bausteine vor, die Sie zum Schreiben von Vorlagen benötigen. Weitere Informationen finden Sie unter Help Center Templates auf developer.zendesk.com.

Eine Curlybars-Vorlage besteht aus zwei Elementen: wortwörtlicher Text, der wie eingegeben dargestellt wird, und Curlybars-Ausdrücke. Dies impliziert, dass eine leere Vorlage ebenso gültig ist wie eine Vorlage, die nur Text enthält. Folgendes ist beispielsweise eine gültige Vorlage:

<h1>Article</h1>

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

Wenn Help-Center-Vorlagen nur wortwörtlichen Text unterstützen würden, wäre es nicht möglich, sie zum Darstellungszeitpunkt anzupassen. Um Vorlagenlogik hinzuzufügen, brauchen Sie Curlybars-Ausdrücke, die in doppelte geschweifte Klammern gesetzt sind ({{ und }}).

Um Vorlagenlogik zum vorherigen Beispiel hinzuzufügen, können Sie die Vorlage wie folgt ändern:

<h1>Article</h1>

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

{{article.author.name}}

In den folgenden Abschnitten erfahren Sie, wie Sie anhand gültiger Ausdrücke sinnvolle Änderungen an der Vorlage vornehmen können.

Beachten Sie, dass das Verschachteln geschweifter Klammern innerhalb anderer geschweifter Klammern keine gültige Syntax ist. Folgendes ist beispielsweise nicht zulässig:

<h1>Article</h1>

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

{{ {{ ... }} }}

Kommentare

Manchmal können sich Notizen in der Vorlage, die auf der dargestellten Seite nicht erscheinen, als nützlich erweisen. In Curlybars können Sie Kommentare einfügen, indem Sie direkt nach der linken geschweiften Klammer ein Ausrufezeichen setzen (ohne Leerzeichen): {{! ... }}. Verwenden Sie diese Syntax, um im Beispiel einen Codekommentar hinzuzufügen:

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

<h1>Article</h1>

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

Zur Darstellung der Seite wird Folgendes an den Browser gesendet:

<h1>Article</h1>

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

Kommentare, die gelöscht werden können, sind beim Entwickeln einer Vorlage durchaus sinnvoll. So können Sie zum Beispiel Code auskommentieren, um Prüfungen durchzuführen, zu debuggen usw.

Blockkommentare

Leider ist die oben beschriebene Syntax zum Auskommentieren von Curlybars-Code nicht geeignet. Verwenden Sie die folgende Syntax, um Curlybars-Code auszukommentieren: {{!-- ... ---}}. Ein solcher Kommentar kann mehrere Zeilen umfassen und Code auf effiziente Weise auskommentieren. Beispiel:

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

--}}

Die Vorlage oben wird wie folgt dargestellt:

<h1>Article</h1>

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

Literale

Curlybars unterstützt Literale, damit Sie Werte einfügen können, die Curlybars genau wie eingegeben interpretiert. Ein Literal kann drei Arten von Werten wiedergeben: eine Zeichenfolge, einen Booleschen Wert oder eine Zahl..

Um eine Zeichenfolge auszudrücken, können Sie sowohl einfache als auch doppelte Anführungszeichen verwenden, allerdings nicht gemischt. Beispiel: 'gültige Zeichenfolge', "auch eine gültige Zeichenfolge", aber "keine gültige Zeichenfolge'.

Eine Zahl kann eine positive oder eine negative Ganzzahl sein. 123 ist eine gültige positive Zahl, +123 repräsentiert den gleichen Wert, 00123 ist auch gültig und -123 ebenfalls.

Es gibt zwei Boolesche Werte: true und false. Andere Variationen sind nicht zulässig. Beispiel: TRUE und FALSE werden in Curlybars nicht als Boolesche Werte interpretiert.

Sie können Literale darstellen. Beispiel:

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

Die Seite wird wie folgt dargestellt:

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

Eigenschaften

Jede Vorlage im Help Center hat Zugriff auf einen Kontext, der Daten über Ihr Help Center enthält. So hat beispielsweise die Vorlage „Beitragsseite“ ein Objekt namens article, das die Struktur des vom Benutzer angeforderten Beitrags offenlegt. Weitere Informationen zu allen Eigenschaften, die Sie in Ihren Vorlagen verwenden können, finden Sie unter Help Center Templates auf developer.zendesk.com.

Verwenden Sie die Punktnotation, um konkrete Informationen aus diesen Objekten zu extrahieren. Einfaches Beispiel: article.title.

Der voll qualifizierte Name einer Eigenschaft wird auch als Pfad bezeichnet. Beispiel: name ist eine Eigenschaft im Objekt author, aber ihr Pfad lautet article.author.name.

Sie können den Wert einer Eigenschaft anzeigen, indem Sie sie in doppelte geschweifte Klammern setzen. Im obigen Beispiel können Sie den Namen des Autors wie folgt in einem getrennten Absatz anzeigen:

<h1>Article</h1>

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

Angenommen, ein Benutzer möchte einen Beitrag von einem Agenten namens Jens Venturini sehen. Die Vorlage wird wie folgt dargestellt:

<h1>Article</h1>

<p>Author: John Venturini</p>

Sie können auch den Beitrag selbst darstellen. Zum Objekt article gibt es eine Eigenschaft namens body, die den Inhalt des Beitrags enthält. Um den Beitragsinhalt darzustellen, ändern Sie die Vorlage wie folgt:

<h1>Article</h1>

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

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

Konditionale Logik

Die Vorlagensprache ermöglicht nicht nur die Darstellung von Eigenschaftswerten, sondern auch das Hinzufügen konditionaler Darstellungslogik zu Ihren Vorlagen.

Beispielsweise können Sie ein bestimmtes HTML-Snippet darstellen, wenn es sich beim angeforderten Beitrag um einen internen Beitrag handelt. In der Vorlage „Beitragsseite“ gibt es eine Eigenschaft namens article.internal, die true zurückgibt, wenn es sich um einen internen Beitrag handelt (bzw. false, wenn nicht).

Sie können einen if-Block mit diesen Informationen erstellen. Der if-Ausdruck muss eine Bedingung angeben, die true oder false ist. Das Ergebnis bestimmt, ob der Inhalt des Blocks dargestellt wird oder nicht. Die Syntax sieht wie folgt aus:

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

Sie können die Beispielvorlage wie folgt ändern:

<h1>Article</h1>

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

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

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

Wenn Sie einen Block darstellen möchten, falls die Bedingung falsch ist, verwenden Sie einen unless-Block. Die Syntax ist ähnlich wie beim if-Block:

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

Angenommen, Sie möchten eine Meldung anzeigen, wenn es sich nicht um einen internen Beitrag handelt. Ändern Sie die Beispielvorlage in diesem Fall wie folgt:

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

Diese Art von konditionaler Logik – wenn wahr, A tun; wenn nicht, dann B – wird normalerweise als if-else-Block codiert. Die Syntax lautet wie folgt:

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

Sie können das Beispiel wie folgt ändern:

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

Zum unless-Block gibt es auch eine unless-else-Variante. Damit können Sie das gleiche Ergebnis erzielen wie mit einem if-else-Block:

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

Wie Bedingungen ausgewertet werden

Eine Bedingung ist normalerweise eine Help-Center-Eigenschaft wie article.internal mit dem Booleschen Wert true oder false. Manche Eigenschaften haben aber keine Booleschen Werte. Diese werden wie folgt ausgewertet.

• Wenn der Wert eine Zahl ist, gilt 0 als „false“ und jeder andere Wert als „true“.

• Wenn der Wert eine Zeichenfolge ist, gilt eine leere Zeichenfolge als „false“ und jede andere Zeichenfolge als „true“.

• Wenn der Wert eine Sammlung von Objekten ist, gilt eine leere Sammlung als „false“ und jede andere Sammlung als „true“.

• Wenn der Wert ein Nullwert ist, gilt der Ausdrück als „false“.

Angenommen, Sie möchten eine konditionale Logik zur Überprüfung von Zahlen einrichten. In der Vorlage „Beitragsseite“ gibt es eine Eigenschaft namens article.comment_count, die die Gesamtzahl von Kommentaren in einem Beitrag enthält. Mit einer if-Bedingung können Sie ermitteln, ob dieser Wert größer ist als 0 und dann eine freundliche Meldung anzeigen. Beispiel:

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

Entfernen von Whitespace

Wenn Curlybars eine Vorlage verarbeitet, wird wortwörtlicher Text wie eingegeben dargestellt. In den meisten Fällen ist das gut so. Es gibt aber Fälle, in denen Sie mehr Kontrolle über die Leerzeichen neben einem Ausdruck benötigen. Beispiel:

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

Wenn highlighted „true“ ist, wird der folgende HTML-Code dargestellt:

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

Vor und nach dem Wort highlight erscheint ein Leerzeichen. Dies wirkt sich zwar nicht auf die Funktion aus, ist aber unschön. Anhand einer Tilde (~) können Sie die Leerzeichen in der Vorlage lassen, ohne sie darzustellen.

Wenn Sie im linken oder rechten Klammernpaar eine Tilde eingeben, wird der Whitespace aus dem in geschweifte Klammern gesetzten Text entfernt. Beispiel:

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

Durch die Tilde werden die Leerzeichen vor und nach dem Wort highlight entfernt:

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

Durch die Tilde werden alle Whitespace-Zeichen wie Zeilenumbruchs-, Tabulator- und Leerzeichen entfernt, die zwar nicht nicht grafisch dargestellt werden, aber Leerraum bilden oder Zeilen trennen. Wenn Sie möchten, können Sie den if-Block oben mehrzeilig formatieren, damit er einfacher zu lesen ist. Beispiel:

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

Dargestellt wird aber nach wie vor dieser Text:

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

Diese Beispiele sind zwar eher theoretischer Natur, zeigen aber, wie die Tilde genutzt werden kann.

Helper

In vielen Vorlagen reicht es, auf Daten zuzugreifen, sie anzuzeigen und konditionale Logik hinzuzufügen. Bei Bedarf können Sie aber weiterführende Funktionen verwenden. Sie können beispielsweise eine lokalisierte Zeichenfolge anzeigen, die je nach dem Gebietsschema des Benutzers variiert, oder eine lange Textpassage nach einer bestimmten Anzahl von Zeichen abschneiden.

Diese Art von Funktionalität kann anhand von Helpern genutzt werden. Weitere Informationen zu allen Helpern, die Sie in Ihren Vorlagen verwenden können, finden Sie unter Help Center Templates auf developer.zendesk.com.

Beispielsweise können Sie in der Vorlage „Beitragsseite“ einen Helper namens excerpt verwenden, um Zeichenfolgen abzuschneiden. Angenommen, Sie möchten eine verkürzte Version des Beitragstitels anzeigen. Sie können hierzu die Vorlage wie folgt ändern:

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

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

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

Wie im obigen Beispiel zu sehen, werden Helper anhand von geschweiften Klammern aufgerufen. Als Parameter akzeptiert der Helper excerpt einen Ausdruck, der eine Zeichenfolge ergibt. Mit der Option characters können Sie angeben, wie viele Zeichen beibehalten werden sollen. Die Option characters ist nicht zwingend erforderlich. Wenn Sie sie nicht angeben, wird ein Standardwert verwendet. Weitere Informationen finden Sie unter Help Center Templates > excerpt auf developer.zendesk.com.

Die Syntax zum Aufruf eines Helpers lautet {{<helper> [<param> ...] [<key=value> ...]}}. Das einzige Element, das zwingend erforderlich ist, ist der Name des Helpers. Die Parameter und Optionen variieren je nach Helper.

Angenommen, es soll eine freundliche Meldung erscheinen, wenn der Name des Autors Jens Venturini lautet. Leider können Sie keine if-Bedingung verwenden, um zu prüfen, ob article.author.name gleich "John Venturini" ist, da if nur jeweils einen Ausdruck verarbeitet. Vergleichsoperatoren wie == werden nicht unterstützt.

Mit dem Helper is können Sie aber eine solche Logik problemlos hinzufügen. Dieser Helper akzeptiert zwei Parameter und prüft, ob sie sich entsprechen. Beispiel:

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

Das Snippet oben zeigt eine freundliche Meldung an, wenn Jens Venturini der Autor ist. Aber was, wenn eine andere Meldung erscheinen soll, falls der Autor nicht Jens Venturini ist? Kein Problem! Wie die Anweisung if-else kann auch der Helper is einen else-Block enthalten. Um erneut die vorherige Meldung anzuzeigen, wenn John Venturini nicht der Autor ist, können Sie einen else-Block hinzufügen:

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

Ändern des Kontexts

Über die Punktnotation können Sie schnell und einfach auf Daten zugreifen, besonders wenn der Pfad zu den benötigten Informationen nicht zu lang ist. Beispiel: article.title. In manchen Fällen ist aber der Zugriff auf eine Eigenschaft mit einem längeren Pfad erforderlich. Beispiel: article.author.name. Sie können längere Pfade in Vorlagen verwenden, wenn Sie möchten. So fügen Sie beispielsweise den Namen und Avatar des Autors hinzu:

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

Das Snippet oben funktioniert zwar problemlos, aber lange Eigenschaftspfade können den Code unübersichtlich machen. Um dies zu verhindern, können Sie das Sonderkonstrukt with verwenden. with akzeptiert einen Parameter, der den Grundkontext für den zugehörigen Codeblock festlegt. Die Syntax lautet wie folgt:

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

Sie können unser Beispiel wie folgt verfeinern:

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

Dank des Parameters article.author erübrigt sich die Angabe von article.author in allen Pfaden im Block. {{name}} innerhalb des Blocks entspricht also article.author.name außerhalb des Blocks.

Sie dürfen article.author.name nicht im Block verwenden, da dies als article.author.article.author.name ausgewertet würde. Analog dazu können Sie nicht über article.title auf den Titel des Beitrags im Block zugreifen, da das Objekt article nur im Stammkontext, d. h. außerhalb des Blocks, erreichbar ist.

Durch Verwendung der Notation ../im Pfad können Sie den durch with festgelegten Kontext verlassen und auf den äußeren Kontext zugreifen. Sie können den Titel des Beitrags im with-Block wie folgt darstellen:

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

Die Notation ../ kann wiederholt in ein und demselben Pfad verwendet werden und springt dann um die entsprechende Anzahl von Kontexten zurück. Das folgende Beispiel funktioniert weiterhin wie erwartet:

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

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

    ...

{{/with}}

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

Um eine bestimmte Meldung anzuzeigen, wenn der Name des Autors nicht angegeben wurde, können Sie einen if-Block verwenden:

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

Hinweis: Im Help Center hat article.author niemals einen Nullwert. Wir haben diesen Fall hier nur zur Veranschaulichung verwendet.

Das Snippet oben funktioniert zwar problemlos, aber Sie können das gleiche Ergebnis mit einem else-Block im Konstrukt with erreichen. Der else-Block wird nur ausgeführt, wenn der Parameter „false“ ist. Sie können das Beispiel wie folgt ändern:

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

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

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

Darüber hinaus macht der else-Block den Code übersichtlicher.

Übergeben des Stammkontexts an einen Helper

Mit dem Schlüsselwort this können Sie den aktuellen Stammkontext an einen Helper übergeben. Angenommen, Sie verwenden den Helper render_author, der ein article-Objekt als Parameter akzeptiert, um Details zum Autor anzuzeigen. Sie können das Schlüsselwort this wie folgt verwenden:

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

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

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

this wird als article aufgelöst.

Zugreifen auf Elemente in einem Array

Manche Help-Center-Eigenschaften bestehen aus Objekt-Arrays. Die Eigenschaft attachments besteht beispielsweise aus einem Array von Anhängen.

Um auf die Elemente in einem Array zuzugreifen, müssen Sie jedes einzeln durchlaufen. Dies können Sie mit dem Helper each erreichen. Beispiel:

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

Das Snippet oben listet alle Anhänge auf. Jedes Listenelement zeigt Daten zu einem bestimmten Anhang an, wie z. B. url, name und size.

Wie with ändert auch each den Kontext im jeweiligen Block. Mit der Notation ../ können Sie auf den äußeren Kontext zugreifen.

Es bietet sich an, eine Meldung anzuzeigen, wenn ein Array leer ist. Dies lässt sich mit einem if-Block erreichen:

...

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

Dies funktioniert zwar problemlos, aber Sie können auch einen else-Block verwenden, um den Code übersichtlicher zu machen:

...

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

Länge

Zu jedem Array gibt es eine implizite length-Eigenschaft, die die Anzahl von Elementen im Array angibt. Wenn Sie beispielsweise die Anzahl von Anhängen anzeigen möchten, verwenden Sie die Eigenschaft length wie folgt:

...

There are {{attachments.length}}.

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