Handlebars-Helper – Vollständige Referenz

In Pantarey werden Handlebars-Vorlagen an mehreren Stellen eingesetzt – z. B. bei der PDF-Erstellung, bei Textvorlagen oder in externen Aufgaben. Alle Vorlagen haben Zugriff auf dieselben Helper-Funktionen, mit denen sich Daten direkt im Template formatieren, berechnen und aufbereiten lassen.

So können Rechnungen, Berichte und Benachrichtigungen professionell gestaltet werden, ohne zusätzliche Prozessschritte.

Wo werden Handlebars-Vorlagen verwendet?

Einsatzbereich	Service / Funktion
PDF-Dokumente	PDF aus Handlebars-Template erstellen
Texte generieren	Text aus Handlebars-Template erstellen
E-Mails aus Vorlage	E-Mail aus Handlebars-Template (Microsoft Graph)
Externe Aufgaben	Externer User Task – HTML-Vorlagen

Grundlagen

Handlebars-Platzhalter werden mit doppelten geschweiften Klammern geschrieben:

<p>Kunde: {{kundenname}}</p>
<p>Betrag: {{currency_eur rechnungsbetrag}}</p>

Die Werte kommen aus dem content-Objekt, das beim Aufruf des Service Tasks übergeben wird.

Dreifache Klammern für HTML

Standardmäßig escaped Handlebars HTML-Sonderzeichen. Wenn der Ausgabewert HTML enthält (z. B. bei qrCode oder htmlify), müssen dreifache Klammern {{{ }}} verwendet werden.

Datum und Uhrzeit

Helper	Beschreibung	Beispiel	Ergebnis
`dateTimeFormat`	Datum/Zeit formatieren (ISO → lokalisiert)	`{{dateTimeFormat erstelldatum "de-DE" "Europe/Berlin"}}`	`22.12.2024, 11:30`
`dateTimeFormatWithSettings`	Datum/Zeit mit erweiterten Optionen	`{{dateTimeFormatWithSettings datum "de-DE" "Europe/Berlin"}}`	`22.12.2024, 11:30`
`toGermanDate`	ISO-Datum → deutsches Format	`{{toGermanDate "2025-01-15"}}`	`15.01.2025`
`currentDate`	Heutiges Datum	`{{currentDate "de-DE" "Europe/Berlin"}}`	`08.04.2026`
`currentDateTime`	Heutiges Datum + Uhrzeit	`{{currentDateTime "de-DE" "Europe/Berlin"}}`	`08.04.2026, 14:30`
`addDaysToCurrentDate`	Tage zum heutigen Datum addieren	`{{addDaysToCurrentDate 14}}`	`22.04.2026`
`month_name`	Monatsname aus Datum	`{{month_name "2025-03-15"}}`	`März`
`year`	Jahreszahl aus Datum	`{{year "2025-03-15"}}`	`2025`

Beispiel – Zahlungsfrist:

<p>Rechnungsdatum: {{toGermanDate rechnungsdatum}}</p>
<p>Zahlbar bis: {{addDaysToCurrentDate 30}}</p>

Zahlen und Währung

Helper	Beschreibung	Beispiel	Ergebnis
`currency_eur`	Euro-Formatierung	`{{currency_eur 1234.56}}`	`1.234,56 €`
`currency_dollar`	Dollar-Formatierung	`{{currency_dollar 1234.56}}`	`$1,234.56`
`numberFormat`	Zahl mit Tausender-Trennzeichen	`{{numberFormat 50000}}`	`50.000`
`multiply`	Multiplikation	`{{multiply preis menge}}`
`add`	Addition	`{{add wert1 wert2}}`
`round`	Runden auf Dezimalstellen	`{{round 3.14159 2}}`	`3.14`

Beispiel – Rechnungsposition:

<td>{{numberFormat menge}} Stk.</td>
<td>{{currency_eur einzelpreis}}</td>
<td>{{currency_eur (multiply einzelpreis menge)}}</td>

Bedingungen

Bedingungs-Helper sind Block-Helper – sie umschließen den Inhalt, der nur bei erfüllter Bedingung angezeigt wird.

Helper	Beschreibung	Beispiel
`ifEquals`	Gleichheit prüfen	`{{#ifEquals status "approved"}}Genehmigt{{/ifEquals}}`
`greaterThan`	Größer als	`{{#greaterThan betrag 1000}}Großauftrag{{/greaterThan}}`
`lessThan`	Kleiner als	`{{#lessThan betrag 100}}Kleinbetrag{{/lessThan}}`
`greaterOrEqualThan`	Größer oder gleich	`{{#greaterOrEqualThan punkte 50}}Bestanden{{/greaterOrEqualThan}}`
`lessOrEqualThan`	Kleiner oder gleich	`{{#lessOrEqualThan lagerbestand 10}}Nachbestellen{{/lessOrEqualThan}}`

Alle Bedingungs-Helper unterstützen einen {{else}}-Block:

{{#greaterThan betrag 1000}}
  <span class="highlight">Großauftrag</span>
{{else}}
  <span>Standardauftrag</span>
{{/greaterThan}}

Text und Formatierung

Helper	Beschreibung	Beispiel
`replace`	Text ersetzen	`{{replace firmenname "GmbH" "AG"}}`
`htmlify`	Zeilenumbrüche → `<br>`, Seitenumbrüche → Page Break	`{{{htmlify beschreibung}}}`
`renderString`	Handlebars-Ausdruck innerhalb eines Strings auswerten	`{{{renderString dynamischerText this}}}`
`buildString`	Strings zusammensetzen (z. B. als Sub-Expression)	`{{{qrCode (buildString "BCD\n" bic "\n" name)}}}`

htmlify im Detail

Der htmlify-Helper wandelt Fließtext in HTML um:

Zeilenumbrüche (\n) werden zu <br>
<pagebreak> wird zu einem Seitenumbruch (für PDFs)

<div>{{{htmlify freitextfeld}}}</div>

Dreifache Klammern

htmlify und renderString geben HTML zurück – immer {{{ }}} verwenden.

Listen und Paginierung

Helper	Beschreibung	Beispiel
`concat`	Arrays zusammenführen	`{{#each (concat listeA listeB)}}...{{/each}}`
`paginate`	Array in Seiten aufteilen	`{{#paginate positionen 10}}...{{/paginate}}`

paginate im Detail

Der paginate-Helper teilt ein Array in gleich große Abschnitte auf – ideal für mehrseitige PDFs, bei denen z. B. nur 10 Positionen pro Seite angezeigt werden sollen.

{{#paginate positionen 10}}
  <div class="seite">
    <h2>Seite {{add pageIndex 1}}</h2>
    <table>
      {{#each slice}}
        <tr>
          <td>{{this.bezeichnung}}</td>
          <td>{{currency_eur this.betrag}}</td>
        </tr>
      {{/each}}
    </table>
  </div>
{{/paginate}}

Innerhalb des Blocks stehen zur Verfügung:

slice – die Einträge der aktuellen Seite
pageIndex – der Seitenindex (beginnt bei 0)

QR-Code

Helper	Beschreibung	Beispiel
`qrCode`	QR-Code als Data-URL erzeugen	`<img src="{{{qrCode zahlungslink}}}" width="200" />`
`buildString`	Strings zusammenbauen (z. B. für strukturierte QR-Daten)	`{{{qrCode (buildString "BCD\n" bic "\n" name)}}}`

QR-Codes werden als Base64-Data-URL erzeugt und direkt in ein <img>-Tag eingebettet. Die Gestaltung (Größe, Position) wird über HTML/CSS gesteuert.

Optionen

Option	Standard	Beschreibung
`width`	`200`	Bildbreite in Pixel
`margin`	`1`	Rand um den QR-Code (in Modulen)
`errorCorrectionLevel`	`"M"`	Fehlerkorrektur: `"L"`, `"M"`, `"Q"` oder `"H"`

<img src="{{{qrCode produktUrl width=300 margin=2 errorCorrectionLevel="H"}}}" width="300" />

GiroCode-Beispiel (Zahlungs-QR-Code)

Der GiroCode (EPC-QR-Code) ermöglicht es, Überweisungsdaten direkt in Banking-Apps zu scannen. Der Aufbau folgt einem festen Zeilenformat:

<img src="{{{qrCode (buildString
  "BCD\n001\n1\nSCT\n"
  bic "\n"
  empfaengerName "\n"
  iban "\nEUR"
  betrag "\n\n\nRechnung "
  rechnungsnummer
) width=250 errorCorrectionLevel="M"}}}" width="250" />

Dreifache Klammern erforderlich

qrCode gibt eine Data-URL zurück, die data:image/png;base64,... enthält. Mit doppelten Klammern {{ }} würde das Ergebnis HTML-escaped und das Bild nicht angezeigt.

Praxisbeispiel: Rechnung

Das folgende Beispiel zeigt eine vollständige Rechnungsvorlage mit Kopfbereich, Positionstabelle, Summen, Zahlungs-QR-Code und bedingtem Hinweis:

<html>
<body>
  <h1>Rechnung {{rechnungsnummer}}</h1>
  <p>Datum: {{toGermanDate rechnungsdatum}}</p>
  <p>Kunde: {{kundenname}}</p>

  <table>
    <thead>
      <tr>
        <th>Bezeichnung</th>
        <th>Menge</th>
        <th>Einzelpreis</th>
        <th>Gesamt</th>
      </tr>
    </thead>
    <tbody>
      {{#each positionen}}
      <tr>
        <td>{{this.bezeichnung}}</td>
        <td>{{numberFormat this.menge}}</td>
        <td>{{currency_eur this.einzelpreis}}</td>
        <td>{{currency_eur (multiply this.einzelpreis this.menge)}}</td>
      </tr>
      {{/each}}
    </tbody>
  </table>

  <p><strong>Nettobetrag:</strong> {{currency_eur nettobetrag}}</p>
  <p><strong>MwSt. 19 %:</strong> {{currency_eur (multiply nettobetrag 0.19)}}</p>
  <p><strong>Gesamtbetrag:</strong> {{currency_eur bruttobetrag}}</p>

  {{#greaterThan bruttobetrag 500}}
    <p><em>Bitte überweisen Sie den Betrag innerhalb von 14 Tagen.</em></p>
  {{/greaterThan}}

  <div style="margin-top: 20px;">
    <p>Scannen für Überweisung:</p>
    <img src="{{{qrCode (buildString "BCD\n001\n1\nSCT\n" bic "\n" firmenname "\n" iban "\nEUR" bruttobetrag "\n\n\nRechnung " rechnungsnummer)}}}" width="200" />
  </div>

  <footer>
    <p>Erstellt am {{currentDate "de-DE" "Europe/Berlin"}}</p>
  </footer>
</body>
</html>

Zusammenfassung aller Helper

Helper	Kategorie	Dreifache Klammern nötig
`dateTimeFormat`	Datum	Nein
`dateTimeFormatWithSettings`	Datum	Nein
`toGermanDate`	Datum	Nein
`currentDate`	Datum	Nein
`currentDateTime`	Datum	Nein
`addDaysToCurrentDate`	Datum	Nein
`month_name`	Datum	Nein
`year`	Datum	Nein
`currency_eur`	Zahlen	Nein
`currency_dollar`	Zahlen	Nein
`numberFormat`	Zahlen	Nein
`multiply`	Zahlen	Nein
`add`	Zahlen	Nein
`round`	Zahlen	Nein
`ifEquals`	Bedingung	Nein
`greaterThan`	Bedingung	Nein
`lessThan`	Bedingung	Nein
`greaterOrEqualThan`	Bedingung	Nein
`lessOrEqualThan`	Bedingung	Nein
`replace`	Text	Nein
`htmlify`	Text	Ja
`renderString`	Text	Ja
`buildString`	Text	— (Sub-Expression)
`concat`	Listen	Nein
`paginate`	Listen	Nein
`qrCode`	QR-Code	Ja