Helper-Referenz

Generierte Seite

Aus den Helper-Definitionen in packages/engine erzeugt von apps/docs/scripts/gen-helpers.ts; nicht von Hand bearbeiten.

Die Helper sind in allen drei Engines unter denselben Namen mit derselben Bedeutung registriert, aber nicht mit derselben Syntax: Jinja2 übergibt Filterargumente in Klammern ({{ value | money("EUR") }}) und kann einen Helper auch als Funktion aufrufen, Liquid übergibt sie nach einem Doppelpunkt ({{ value | money: "EUR" }}) und kennt keine Objektliterale, Handlebars übergibt sie positionell mit Hash-Argumenten ({{money value "EUR"}}, width=120). Jede Zeile zeigt den Aufruf deshalb in allen dreien; jeden davon rendert helper-examples.spec.ts, was Sie kopieren, läuft also.

Formatierung

Beträge, Zahlen und Datumsangaben folgen Locale, Zeitzone und Währung aus den Einstellungen der Vorlage, sofern kein Argument etwas anderes sagt.

Helper	Signatur	Beschreibung	Beispiel
money (Aliase: currency)	money(value, currency?, locale?)	Formatiert eine Zahl als Währung mit Intl.NumberFormat. Die Vorgaben kommen aus den Einstellungen der Vorlage. Text, der keine Zahl ist, erscheint unverändert; eine Rechnung, die NaN ergibt, bricht das Rendern ab.	Jinja2 {{ line.total | money('EUR') }} → 1.234,50 € Liquid {{ line.total | money: 'EUR' }} → 1.234,50 € Handlebars {{money line.total 'EUR'}} → 1.234,50 €
number	number(value, decimals?, locale?)	Formatiert eine Zahl mit Tausendertrennung. Mit decimals genau so viele Nachkommastellen (kaufmännisch gerundet), ohne so viele, wie die Zahl hat, höchstens drei: 1234.5 → 1.234,5 und 2.34567 → 2,346. Für ganze Zahlen number(0).	Jinja2 {{ qty | number(2) }} → 1.234,00 Liquid {{ qty | number: 2 }} → 1.234,00 Handlebars {{number qty 2}} → 1.234,00
date	date(value, format?, tz?, locale?)	Formatiert ein Datum mit date-fns-Tokens (etwa 'dd.MM.yyyy', 'PPP'). Nimmt ISO-Strings, Epoch-Zahlen und 'now'.	Jinja2 {{ invoice.date | date('dd.MM.yyyy') }} Liquid {{ invoice.date | date: 'dd.MM.yyyy' }} Handlebars {{date invoice.date 'dd.MM.yyyy'}}
dateAdd (Aliase: date_add)	dateAdd(value, amount, unit)	Addiert Tage, Wochen, Monate oder Jahre auf ein Datum; liefert einen ISO-String zum Weiterformatieren.	Jinja2 {{ invoice.date | dateAdd(14, 'days') | date('PP') }} Liquid {{ invoice.date | dateAdd: 14, 'days' | date: 'PP' }} Handlebars {{date (dateAdd invoice.date 14 'days') 'PP'}}
add (Aliase: plus)	add(a, b)	a + b (Handlebars hat keine eigene Arithmetik).	Jinja2 {{ line.qty | add(1) }} Liquid {{ line.qty | add: 1 }} Handlebars {{#each invoice.lines}}{{add @index 1}}{{/each}}
subtract (Aliase: minus, sub)	subtract(a, b)	a minus b.	Jinja2 {{ total | subtract(discount) }} Liquid {{ total | subtract: discount }} Handlebars {{subtract total discount}}
multiply (Aliase: times, mul)	multiply(a, b)	a mal b.	Jinja2 {{ line.qty | multiply(line.price) | money }} Liquid {{ line.qty | multiply: line.price | money }} Handlebars {{money (multiply line.qty line.price)}}
divide (Aliase: divided_by, div)	divide(a, b)	a geteilt durch b; leer, wenn b 0 ist.	Jinja2 {{ total | divide(count) }} Liquid {{ total | divide: count }} Handlebars {{divide total count}}
round	round(value, decimals = 0, method = 'common')	Rundet auf die angegebenen Nachkommastellen wie Jinja2s round: 'common' kaufmännisch, 'floor' immer ab, 'ceil' immer auf.	Jinja2 {{ 2.345 | round(2) }} gives 2.35, {{ 2.349 | round(2, 'floor') }} gives 2.34 Liquid {{ 2.345 | round: 2 }} gives 2.35, {{ 2.349 | round: 2, 'floor' }} gives 2.34 Handlebars {{round 2.345 2}} gives 2.35, {{round 2.349 2 'floor'}} gives 2.34
numToWords (Aliase: num_to_words, spellout)	numToWords(value, locale?)	Schreibt eine Zahl in Worten aus (de, en, fr, es, it, nl).	Jinja2 {{ total | numToWords('de') }} → zweihundertdreiundvierzig Liquid {{ total | numToWords: 'de' }} → zweihundertdreiundvierzig Handlebars {{numToWords total 'de'}} → zweihundertdreiundvierzig

Text

String-Helper, Markdown und Übersetzungen über die Wörterbücher der Vorlage.

Helper	Signatur	Beschreibung	Beispiel
upper (Aliase: upcase)	upper(value)	Schreibt einen String in Großbuchstaben.	Jinja2 {{ name | upper }} Liquid {{ name | upper }} Handlebars {{upper name}}
lower (Aliase: downcase)	lower(value)	Schreibt einen String in Kleinbuchstaben.	Jinja2 {{ name | lower }} Liquid {{ name | lower }} Handlebars {{lower name}}
title (Aliase: capitalize_words)	title(value)	Schreibt jedes Wort groß.	Jinja2 {{ 'hello world' | title }} → Hello World Liquid {{ 'hello world' | title }} → Hello World Handlebars {{title 'hello world'}} → Hello World
truncate	truncate(value, length = 255, suffix = '…')	Kürzt einen String auf length Zeichen und hängt beim Kürzen das Suffix an.	Jinja2 {{ description | truncate(40) }} Liquid {{ description | truncate: 40 }} Handlebars {{truncate description 40}}
replace	replace(value, search, replacement)	Ersetzt jedes Vorkommen von search.	Jinja2 {{ iban | replace(' ', '') }} Liquid {{ iban | replace: ' ', '' }} Handlebars {{replace iban ' ' ''}}
split	split(value, separator = ',')	Zerlegt einen String in eine Liste.	Jinja2 {% for tag in keywords | split(',') %}{{ tag }}{% endfor %} Liquid {% assign tags = keywords | split: ',' %}{% for tag in tags %}{{ tag }}{% endfor %} Handlebars {{#each (split keywords ',')}}{{this}}{{/each}}
default (Aliase: d)	default(value, fallback)	Liefert den Ersatzwert, wenn der Wert leer, null oder undefined ist.	Jinja2 {{ customer.vat | default('—') }} Liquid {{ customer.vat | default: '—' }} Handlebars {{default customer.vat '—'}}
nl2br	nl2br(value)	Escapt den Text und macht aus Zeilenumbrüchen <br>.	Jinja2 {{ address | nl2br }} Liquid {{ address | nl2br }} Handlebars {{nl2br address}}
markdown	markdown(value)	Rendert Markdown zu HTML (ohne Sanitizer: Die Daten der Vorlage gelten als vertrauenswürdig).	Jinja2 {{ notes | markdown }} Liquid {{ notes | markdown }} Handlebars {{markdown notes}}
safe (Aliase: raw)	safe(value)	Markiert einen String als HTML, damit die Engine ihn nicht escapt.	Jinja2 {{ html_snippet | safe }} Liquid {{ html_snippet | safe }} Handlebars {{safe html_snippet}}
t (Aliase: translate)	t(key, params?)	Schlägt einen Schlüssel im i18n-Wörterbuch der Vorlage für das Locale der Anfrage nach; {name}-Platzhalter kommen aus params.	Jinja2 {{ t('invoice.title', { number: invoice.number }) }} Liquid {{ 'invoice.title' | t: number: invoice.number }} Handlebars {{t 'invoice.title' number=invoice.number}}

Listen

Auswerten und Gruppieren von Listen; alle arbeiten auf den Objekten Ihrer Daten.

Helper	Signatur	Beschreibung	Beispiel
join	join(list, separator = ', ')	Fügt eine Liste zu einem String zusammen.	Jinja2 {{ tags | join(' · ') }} Liquid {{ tags | join: ' · ' }} Handlebars {{join tags ' · '}}
sum	sum(list, path?)	Summe der Elemente oder von path in jedem Element.	Jinja2 {{ invoice.lines | sum('total') | money }} Liquid {{ invoice.lines | sum: 'total' | money }} Handlebars {{money (sum invoice.lines 'total')}}
avg	avg(list, path?)	Durchschnitt der Elemente oder von path in jedem Element.	Jinja2 {{ scores | avg | number(1) }} Liquid {{ scores | avg | number: 1 }} Handlebars {{number (avg scores) 1}}
min	min(list, path?)	Kleinste Zahl.	Jinja2 {{ prices | min }} Liquid {{ prices | min }} Handlebars {{min prices}}
max	max(list, path?)	Größte Zahl.	Jinja2 {{ prices | max }} Liquid {{ prices | max }} Handlebars {{max prices}}
groupBy (Aliase: group_by, groupby)	groupBy(list, path)	Gruppiert Elemente nach einem Feld; liefert eine Liste aus { key, items }.	Jinja2 {% for group in lines | groupBy('category') %}{{ group.key }}{% endfor %} Liquid {% assign groups = lines | groupBy: 'category' %}{% for group in groups %}{{ group.key }}{% endfor %} Handlebars {{#each (groupBy lines 'category')}}{{key}}{{/each}}
sortBy (Aliase: sort_by, sort)	sortBy(list, path?, direction = 'asc')	Sortiert Elemente nach einem Feld (Zahlen numerisch, Strings nach Locale).	Jinja2 {% for l in lines | sortBy('position') %}{{ l.sku }}{% endfor %} Liquid {% assign sorted = lines | sortBy: 'position' %}{% for l in sorted %}{{ l.sku }}{% endfor %} Handlebars {{#each (sortBy lines 'position')}}{{sku}}{{/each}}
where (Aliase: filter_by)	where(list, path, value?)	Behält Elemente, deren Feld value entspricht (oder wahr ist, wenn value fehlt).	Jinja2 {% for l in lines | where('taxable', true) %}{{ l.sku }}{% endfor %} Liquid {% assign taxable = lines | where: 'taxable', true %}{% for l in taxable %}{{ l.sku }}{% endfor %} Handlebars {{#each (where lines 'taxable' true)}}{{sku}}{{/each}}
pluck (Aliase: map)	pluck(list, path)	Zieht ein Feld aus jedem Element heraus.	Jinja2 {{ lines | pluck('sku') | join(', ') }} Liquid {{ lines | pluck: 'sku' | join: ', ' }} Handlebars {{join (pluck lines 'sku') ', '}}
chunk (Aliase: batch)	chunk(list, size)	Zerlegt eine Liste in Listen aus size Elementen (Zeilen von Etiketten, Spalten).	Jinja2 {% for row in labels | chunk(3) %}{{ row | join(', ') }}{% endfor %} Liquid {% assign rows = labels | chunk: 3 %}{% for row in rows %}{{ row | join: ', ' }}{% endfor %} Handlebars {{#each (chunk labels 3)}}{{join this ', '}}{{/each}}
range	range(start, end?, step = 1)	Liste von Zahlen von start bis end (ausschließlich).	Jinja2 {% for i in range(1, 4) %}{{ i }}{% endfor %} Liquid {% assign nums = 1 | range: 4 %}{% for i in nums %}{{ i }}{% endfor %} Handlebars {{#each (range 1 4)}}{{this}}{{/each}}
first	first(list)	Erstes Element.	Jinja2 {{ tags | first }} Liquid {{ tags | first }} Handlebars {{first tags}}
last	last(list)	Letztes Element.	Jinja2 {{ tags | last }} Liquid {{ tags | last }} Handlebars {{last tags}}
length (Aliase: size, count)	length(value)	Anzahl der Elemente einer Liste, der Schlüssel eines Objekts oder der Zeichen eines Strings.	Jinja2 {{ lines | length }} Liquid {{ lines | length }} Handlebars {{length lines}}

Logik

Vergleiche und boolesche Logik. Jinja2 und Liquid haben dafür Operatoren; in Handlebars sind diese Helper der einzige Weg zu einer Bedingung wie {{#if (gt invoice.total 1000)}}. Liquid erlaubt in einer Bedingung keinen Filter, deshalb weisen die Liquid-Beispiele den Vergleich zuerst zu.

Helper	Signatur	Beschreibung	Beispiel
eq	eq(a, b)	Wahr, wenn beide Werte gleich sind; 1 ist gleich "1".	Jinja2 {% if eq(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | eq: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (eq invoice.total 1000)}}…{{/if}}
ne	ne(a, b)	Wahr, wenn die Werte verschieden sind.	Jinja2 {% if ne(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | ne: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (ne invoice.total 1000)}}…{{/if}}
gt	gt(a, b)	Größer als; Zahlen als Zahlen, alles andere als Text.	Jinja2 {% if gt(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | gt: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (gt invoice.total 1000)}}…{{/if}}
gte	gte(a, b)	Größer oder gleich.	Jinja2 {% if gte(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | gte: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (gte invoice.total 1000)}}…{{/if}}
lt	lt(a, b)	Kleiner als.	Jinja2 {% if lt(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | lt: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (lt invoice.total 1000)}}…{{/if}}
lte	lte(a, b)	Kleiner oder gleich.	Jinja2 {% if lte(invoice.total, 1000) %}…{% endif %} Liquid {% assign hit = invoice.total | lte: 1000 %}{% if hit %}…{% endif %} Handlebars {{#if (lte invoice.total 1000)}}…{{/if}}
and	and(a, b, …)	Wahr, wenn jeder Wert wahr ist; eine leere Liste gilt als falsch.	Jinja2 {% if and(customer.vatId, eq(country, 'DE')) %}…{% endif %} Liquid {% assign german = country | eq: 'DE' %}{% assign both = customer.vatId | and: german %}{% if both %}…{% endif %} Handlebars {{#if (and customer.vatId (eq country 'DE'))}}…{{/if}}
or	or(a, b, …)	Wahr, wenn irgendein Wert wahr ist.	Jinja2 {% if or(invoice.paid, invoice.credited) %}…{% endif %} Liquid {% assign any = invoice.paid | or: invoice.credited %}{% if any %}…{% endif %} Handlebars {{#if (or invoice.paid invoice.credited)}}…{{/if}}
not	not(value)	Der umgekehrte Wahrheitswert.	Jinja2 {% if invoice.paid | not %}…{% endif %} Liquid {% assign unpaid = invoice.paid | not %}{% if unpaid %}…{% endif %} Handlebars {{#if (not invoice.paid)}}…{{/if}}

Codes

QR-Codes, Barcodes und der SEPA-Überweisungs-QR (GiroCode) als eingebettete SVG-Data-URIs.

Helper	Signatur	Beschreibung	Beispiel
qrcode (Aliase: qr)	qrcode(value, { size = 160, ecc = 'M', margin = 1, color, background })	QR-Code als SVG-Data-URI für das src eines <img>. Geben Sie dem Bild ein alt, das sagt, wohin der Code führt: Ein Screenreader kann ihn nicht scannen.	Jinja2 <img src="{{ qrcode(order.url, { size: 120 }) }}" alt="QR code: {{ order.url }}"> Liquid <img src="{{ order.url | qrcode: size: 120 }}" alt="QR code: {{ order.url }}"> Handlebars <img src="{{qrcode order.url size=120}}" alt="QR code: {{order.url}}">
barcode	barcode(value, { type = 'code128', height = 12, width, text = true, scale = 2 })	Barcode (code128, ean13, ean8, upc, itf14, code39, datamatrix, pdf417) als SVG-Data-URI. Geben Sie dem Bild ein alt mit dem Wert, den der Code enthält.	Jinja2 <img src="{{ barcode(item.sku, { type: 'code128' }) }}" alt="Barcode {{ item.sku }}"> Liquid <img src="{{ item.sku | barcode: type: 'code128' }}" alt="Barcode {{ item.sku }}"> Handlebars <img src="{{barcode item.sku type='code128'}}" alt="Barcode {{item.sku}}">
epcQr (Aliase: epc_qr, girocode)	epcQr({ name, iban, bic?, amount?, reference?, text? }, { size })	SEPA-Überweisungs-QR-Code (EPC069-12 / GiroCode), den Banking-Apps scannen, um eine Zahlung vorauszufüllen. Eine Rechnungsnummer gehört in text (den Verwendungszweck); reference ist nur für eine strukturierte Gläubigerreferenz (RF…). Geben Sie dem Bild ein alt und drucken Sie die Bankverbindung zusätzlich als Text: Der Code ist ein Bild.	Jinja2 <img src="{{ epcQr({ name: company.name, iban: company.iban, amount: invoice.total, text: invoice.number }) }}" alt="QR code to pay invoice {{ invoice.number }}"> Liquid <img src="{{ company.iban | epcQr: name: company.name, amount: invoice.total, text: invoice.number }}" alt="QR code to pay invoice {{ invoice.number }}"> Handlebars <img src="{{epcQr name=company.name iban=company.iban amount=invoice.total text=invoice.number}}" alt="QR code to pay invoice {{invoice.number}}">

Dokument

Seitenumbrüche, Bilder und Diagramme. asset löst einen Namen in der Dateibibliothek des Workspace auf (Seite Dateien oder POST /files); ein relativer Bildpfad löst sich gegen dieselbe Bibliothek auf.

Helper	Signatur	Beschreibung	Beispiel
asset	asset(name)	URL einer Datei aus der Bibliothek des Workspace (Logo, Hintergrund) auf dem CDN. Laden Sie sie auf der Seite Dateien oder mit POST /files hoch und nutzen Sie den Namen von dort; relative Bildpfade lösen sich gegen dieselbe Bibliothek auf.	Jinja2 <img src="{{ asset('logo.png') }}"> Liquid <img src="{{ 'logo.png' | asset }}"> Handlebars <img src="{{asset 'logo.png'}}">
pageBreak (Aliase: page_break)	pageBreak()	Beginnt im PDF eine neue Seite.	Jinja2 {{ pageBreak() }} Liquid {{ '' | pageBreak }} Handlebars {{pageBreak}}
chart	chart({ type, labels, values, label, color } | { type, labels, series } | { type, data, options }, { width, height, alt })	Zeichnet ein Chart.js-Diagramm (bar, line, pie, doughnut, radar, …) aus einfachen Daten: labels mit values, mehrere series aus { label, values, color } oder vollständige Chart.js-data und -options; Animationen sind aus, damit PDF und Vorschau übereinstimmen. alt sagt in Worten, was das Diagramm zeigt: Ein Screenreader liest es anstelle des Bildes vor, und ein Tagged PDF braucht es.	Jinja2 {{ chart({ type: 'line', labels: sales.labels, values: sales.quarters, width: 480, alt: 'Sales by quarter' }) }} Liquid {{ '' | chart: type: 'line', labels: sales.labels, values: sales.quarters, width: 480, alt: 'Sales by quarter' }} Handlebars {{chart type='line' labels=sales.labels values=sales.quarters width=480 alt='Sales by quarter'}}
image	image(url, { width, height, fit, alt })	Platziert ein Bild mit fester Größe und Zuschnitt (cover, contain, fill); der Render-Worker holt es über seinen Cache und blockt private Hosts. alt sagt, was es zeigt; ohne alt gilt das Bild als Schmuck, und ein Screenreader übergeht es.	Jinja2 {{ image(product.photo, { width: 120, height: 80, fit: 'cover', alt: product.name }) }} Liquid {{ product.photo | image: width: 120, height: 80, fit: 'cover', alt: product.name }} Handlebars {{image product.photo width=120 height=80 fit='cover' alt=product.name}}

Debugging

Helper	Signatur	Beschreibung	Beispiel
json (Aliase: tojson, dump)	json(value, indent = 2)	Serialisiert einen Wert als JSON; praktisch beim Bauen einer Vorlage.	Jinja2 <pre>{{ invoice | json }}</pre> Liquid <pre>{{ invoice | json }}</pre> Handlebars <pre>{{json invoice}}</pre>