Handlebars Referenz

Syntax

Dokumentvorlagen verwenden die Template-Sprache Handlebars. Sie schreiben eine Vorlage in HTML und verweisen mit Handlebars-Ausdrücken auf dynamische Inhalte.

Variablen

Die Variablen eines Dokuments stehen direkt im Kontext zur Verfügung. Für den Zugriff auf eine Variable verwenden Sie folgende Syntax:

{{NameOfTheVariable}}

Manche Variablen sind in Objekten verschachtelt. Innerhalb von Objekten navigieren Sie mit der Punktnotation:

{{Object.Subobject.Name}}

Kontext

Dokumente haben zwei Kontexte: den primären Kontext und, darin verschachtelt, den Meta-Kontext.

Primärer Kontext

Der primäre Kontext enthält alle Variablen eines Dokuments. Sie können über inputs in der Vorlage verändert werden. Bei den meisten Dokumenten werden viele Variablen bereits während der Erzeugung gesetzt. Je nach Dokumenttyp können einzelne Variablen gesperrt und damit unveränderlich sein. Das gilt zum Beispiel für Geldbeträge.

Meta-Kontext

Jedes Dokument hat zusätzlich einen Meta-Kontext. Er steht im Hauptkontext als Eigenschaft Document zur Verfügung und enthält alle Metadaten des Dokuments, etwa die Beziehungen und weitere direkt zugewiesene Attribute. So greifen Sie beispielsweise auf den Namen des Zahlungsempfängers zu:

{{Document.creditor.name}}

Beispiel

Zum Einstieg ein kurzes Beispiel, wie eine einfache Dokumentvorlage aussehen kann.

Falls Sie damit Mühe haben, wenden Sie sich besser an Ihren EApp-Integrator.

<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <style>
      body {
        font-size: 3mm;
        margin: 0;
        max-width: none;
      }
      @page{
        size: A4;
        margin: 10mm;
        margin-left: 20mm;
        margin-top: 27mm;
      }
      @media only screen {
        body {
          margin: 10mm;
          margin-left: 20mm;
          margin-top: 27mm;
          box-sizing: border-box;
        }
      }


    </style>
  </head>
  <body>
    <div class="your-document-header">
      {{translate "Document ID"}}: {{Document.id}}
    </div>
    <div class="your-document-body">
      <table>
        <tr>
          <th>{{translate "Name"}}</th>
          <th>{{translate "Address"}}</th>
        </tr>

      {{#each Persons}}
        <tr>
          <td>{{Name}}</td>
          <td>{{Address}}</td>
        </tr>
      {{/each}}
    </div>
  </body>
</html>

Standardfunktionen:

if: bedingt ausgeben unless: umgekehrtes if each: über eine Liste iterieren with: Kontext wechseln lookup: Parameter dynamisch auflösen length: Einträge einer Liste zählen

length

Um die Einträge einer Liste zu zählen, verwenden Sie das Attribut length:

{{Object.lengt}}

EApp-spezifische Funktionen

translate: übersetzt einen Schlüssel input: erlaubt eigenen Text in einem Eingabefeld textarea: erlaubt eigenen Text in einem mehrzeiligen Eingabefeld image: zeigt ein Bild aus derselben Vorlagenbibliothek datetime: zeigt ein Feld mit einem Datum in einem bestimmten Format number: zeigt ein Feld mit einer Zahl in einem bestimmten Format calculate: zeigt einen selbst berechneten Wert payment-slip: zeigt einen Einzahlungsschein match: erlaubt das Filtern eines bestimmten Objekts im Inhalt

translate

Übersetzt einen Schlüssel entsprechend der Sprache des Dokuments.

Parameter

Parameter Inhalt Beispiele
1 Zeichenkette oder Variable Date oder Invoice

Beispiele

{{translate "Date"}}
{{translate "Invoice"}} for {{translate type}}

input

Zeigt der Benutzerin oder dem Benutzer im Bearbeitungsmodus ein Eingabefeld für eigenen Text. Im Anzeigemodus wird dieser Text dann ausgegeben.

Parameter

Parameter Inhalt optional Beispiele
1 Referenz greetings oder customer_reference
style Zeichenkette ja height: 100% oder color: white; background-color: red;
type Zeichenkette ja, Standard text text oder number
raw-output Bool ja, Standard false true oder false

Beispiele

{{input "greetings"}}
{{input "customer_reference" style="height:100%;color:white;background-color:red;" type="number" raw-output=true}}

textarea

Zeigt der Benutzerin oder dem Benutzer im Bearbeitungsmodus ein mehrzeiliges Eingabefeld für eigenen Text. Im Anzeigemodus wird dieser Text dann ausgegeben.

Parameter

Parameter Inhalt optional Beispiele
1 Referenz address oder description
style Zeichenkette ja height: 100% oder color: white; background-color: red;

Beispiele

{{textarea "address"}}
{{textarea "description" style="height:100%;color:white;background-color:red;"}}

image

Fügt der Dokumentvorlage ein Bild hinzu. Erlaubt sind nur Bilder aus derselben Vorlagenbibliothek wie die Vorlage.

Parameter

Parameter Inhalt optional Beispiele
1 Bild-ID (Zeichenkette) 1mag6d1d
style Zeichenkette ja height: 100% oder width:200px; border: 2px solid black

Beispiele

{{image "1mag6d1d"}}
{{image "abcd1234" style="width:200px; border: 2px solid black"}}

datetime

Zeigt ein Datum in einem bestimmten Format und in der Sprachregion des Dokuments.

Parameter

Parameter Inhalt optional Beispiele
1 oder Inhalt ISO8601-Datumszeichenkette 2000-01-01T00:00:01 oder {{var_with_date}}
date-format none, full, long, medium, short ja, Standard long
time-format none, full, long, medium, short ja, Standard none

Beispiele

{{datetime invoice_date}}
{{#datetime}}2000-01-01T00:00:01{{/datetime}}
{{datetime "2000-01-01T00:00:01" date-format="short" time-format="short"}}

number

Zeigt eine Zahl in einem bestimmten Format und in der Sprachregion des Dokuments.

Parameter

Parameter Inhalt optional Beispiele
1 oder Inhalt numerisch 123456 oder amount
precision min oder min,max ja (Standard: 2) 1 oder 2,4
rounding-mode down oder up ja (Standard: nearest)
rounding-increment Zeichenkette ja (Standard: 0) 0.2 oder 0.05
format none, decimal oder currency ja (Standard: decimal)
currency ISO4217-Währungszeichenkette ja (Standard: eur) usd oder gbp
currency-display none, symbol, code, name ja (Standard: symbol)

Beispiele

{{number amount}}
{{#number}}1234.67{{/number}}
{{number "1234.6789" precision="2,4" rounding-mode="down" rounding-increment="0.0002" format="currency" currency="usd" currency-display="none"}}
{{#number}}{{#calculate}}10+15{{/calculate}}{{/number}}

calculate

Zeigt ein Feld mit einem selbst berechneten Wert.

Hinweis: Das Ergebnis einer Berechnung ist immer eine reine Zahl. Formatieren können Sie es, indem Sie die Berechnung in die number-Funktion einschliessen.

Parameter

Parameter Inhalt optional Beispiele
Inhalt Zeichenkette Siehe Beispiele unten

Beispiele

{{#calculate}}{{amount}}+10{{/calculate}}
{{#calculate}}{{amount}}*{{vat_rate}}{{/calculate}}

Unterstützte Symbole

Symbol Beschreibung Beispiel
+ Additionsoperator 2+3 = 5
- Subtraktionsoperator 2-3 = -1
* Multiplikationsoperator 2*3 = 6
/ Divisionsoperator 3/2 = 1.5
Mod Modulo-Operator 3 Mod 2 = 1
^ Potenzoperator 2^3 = 8
root Quadratwurzel-Funktion root 4 = 2
( ) Klammern 2*(3+4) = 14
pi Mathematische Konstante pi pi = 3.14...

payment-slip

Zeigt ein Feld mit einem dynamischen Wert, optional in einem bestimmten Format. Alle Parameter ausser dem Typ können mit Mustache-Syntax gerendert werden und verwenden Dokumentvariablen.

Parameter

Parameter Inhalt optional Standard
1 Typ des Einzahlungsscheins ch-qr – zurzeit ist nur die Schweizer QR-Rechnung verfügbar
creditor-name Name des Zahlungsempfängers ja {{Document.creditor.name}}
creditor-addressline-1 Erste Adresszeile des Zahlungsempfängers ja
creditor-addressline-2 Zweite Adresszeile des Zahlungsempfängers ja
creditor-city Ort des Zahlungsempfängers ja {{Document.creditor.address_town}}
creditor-country Land des Zahlungsempfängers ja {{Document.creditor.address_country_code}}
creditor-postcode Postleitzahl des Zahlungsempfängers ja {{Document.creditor.address_zip}}
creditor-iban IBAN des Zahlungsempfängers ja {{Document.creditor.iban}}
debtor-name Name des Zahlungspflichtigen ja {{Document.receiver.name}}
debtor-addressline-1 Erste Adresszeile des Zahlungspflichtigen ja
debtor-addressline-2 Zweite Adresszeile des Zahlungspflichtigen ja
debtor-city Ort des Zahlungspflichtigen ja {{Document.creditor.address_town}}
debtor-country Land des Zahlungspflichtigen ja {{Document.creditor.address_country_cide}}
debtor-postcode Postleitzahl des Zahlungspflichtigen ja {{Document.creditor.address_zip}}
payment-amount Zahlungsbetrag ja {{BalanceOutstanding}}
payment-currency Zahlungswährung ja {{CurrencySymbol}}
reference-type Referenztyp. Erlaubt sind SCOR und NON ja SCOR
reference Referenzzeichenkette ja {{Document.id}}

Beispiele

{{payment-slip "ch-qr"}}
{{payment-slip "ch-qr" creditor-name="Other Name" creditor-addressline-1="Other Address" creditor-addressline-2="4545 Other Town" creditor-city="Other Town" creditor-country="DE" creditor-postcode="4545" creditor-iban="DE93 0076 2011 6238 5295 1" debtor-name="Third name" debtor-addressline-1="Third address" debtor-addressline-2="6767 Third Town" debtor-city="Third Town" debtor-country="CH" debtor-postcode="6767" payment-amount="245.35" payment-currency="EUR" reference="CustomReference"}}

match

Der MatchHelper stellt eine Hilfsfunktion bereit, um Zeichenketten in Handlebars-Vorlagen mit regulären Ausdrücken abzugleichen. Damit lassen sich in Ihren Handlebars-Vorlagen bestimmte Muster im Inhalt filtern oder suchen.

Parameter

Parameter Inhalt optional Beispiele
1 Referenz Invoice
pattern Muster als regulärer Ausdruck nein "\\d+" für Ziffern
flag Optionale Regex-Flags ja "g" für globalen Abgleich

Beispiele

{{#if (match Invoice pattern="12345")}}
  Contains a number!
{{else}}
  No numbers found.
{{/if}}

{{#if (match Invoice pattern="12345" flags="g")}}
  Contains a number!
{{else}}
  No numbers found.
{{/if}}

electronic-invoice

Der ElectronicInvoiceHelper stellt eine Hilfsfunktion bereit, um in Handlebars-Vorlagen elektronische Rechnungen zu erzeugen. Damit lassen sich elektronische Rechnungen für ZUGFeRD und Factur-X erzeugen.

Parameter

Parameter Inhalt optional Beispiele
1 Rechnungstyp nein factur-x
language Sprache ja {{language}}
summarize-items Positionen zusammenfassen ja 'title' or ''
invoice-id Rechnungs-ID ja {{Document.id}}
invoice-title Rechnungstitel ja {{Document.name}}
invoice-date Rechnungsdatum ja {{InvoiceDate}}
creditor-hash ID-Hash des Zahlungsempfängers ja {{Document.creditor.id}}
creditor-name Name des Zahlungsempfängers ja {{Document.creditor.name}}
creditor-address-lineone Erste Adresszeile des Zahlungsempfängers ja {{Document.creditor.additional_name}} ?? {{Document.creditor.address_1}}
creditor-address-linetwo Zweite Adresszeile des Zahlungsempfängers ja {{Document.creditor.additional_name}} ? {{Document.creditor.address_1}} : {{Document.creditor.address_2}}
creditor-address-linethree Dritte Adresszeile des Zahlungsempfängers ja {{Document.creditor.additional_name}} ? {{Document.creditor.address_2}} : ''
creditor-city Ort des Zahlungsempfängers ja {{Document.creditor.address_town}}
creditor-country Land des Zahlungsempfängers ja {{Document.creditor.address_country_code}}
creditor-postcode Postleitzahl des Zahlungsempfängers ja {{Document.creditor.address_zip}}
creditor-iban IBAN des Zahlungsempfängers ja {{Document.creditor.iban}}
creditor-email E-Mail des Zahlungsempfängers ja {{Document.creditor.email}}
debtor-hash ID-Hash des Zahlungspflichtigen ja {{Document.receiver.id}}
debtor-name Name des Zahlungspflichtigen ja {{Document.receiver.name}}
debtor-address-lineone Erste Adresszeile des Zahlungspflichtigen ja {{Document.receiver.additional_name}} ?? {{Document.receiver.address_1}}
debtor-address-linetwo Zweite Adresszeile des Zahlungspflichtigen ja {{Document.receiver.additional_name}} ? {{Document.receiver.address_1}} : {{Document.receiver.address_2}}
debtor-address-linethree Dritte Adresszeile des Zahlungspflichtigen ja {{Document.receiver.additional_name}} ? {{Document.receiver.address_2}} : ''
debtor-city Ort des Zahlungspflichtigen ja {{Document.receiver.address_town}}
debtor-country Land des Zahlungspflichtigen ja {{Document.receiver.address_country_code}}
debtor-postcode Postleitzahl des Zahlungspflichtigen ja {{Document.receiver.address_zip}}
debtor-iban IBAN des Zahlungspflichtigen ja {{Document.receiver.iban}}
debtor-email E-Mail des Zahlungspflichtigen ja {{Document.receiver.email}}
debtor-preferred-document-delivery Gewünschter Dokumentversand des Zahlungspflichtigen ja {{Document.receiver.preferred_document_delivery}}
payment-subtotal Zwischentotal ja {{Subtotal}}
payment-total Gesamttotal ja {{Total}}
due-payable Zahlungsbetrag ja {{BalanceOutstanding}}
payment-currency Zahlungswährung ja {{CurrencySymbol}} ?? {{Currency}} ?? 'CHF'

Beispiele

{{electronic-invoice "factur-x"}}
{{electronic-invoice "factur-x" language="en" summarize-items="item-name" invoice-id="i1" invoice-title="it" invoice-date="2099-12-12" creditor-hash="c1" creditor-name="cn" creditor-address-lineone="cl1"" creditor-address-linetwo="cl2" creditor-address-linethree="cl3" creditor-country="cc" creditor-postcode="9988" creditor-city="cc" creditor-email="ce" debtor-hash="d1" debtor-name="dn" debtor-address-lineone="dl1" debtor-address-linetwo="dl2" debtor-address-linethree="dl3" debtor-country="dc" debtor-postcode="6655" debtor-city="dc" debtor-email="de" debtor-preferred-document-delivery="PhysicalMail" payment-subtotal="50.00" payment-total="99.99" due-payable="99.90" payment-currency="pcu"}}

Zuletzt aktualisiert: 2021-09-16