Przewodnik po Handlebars

Szablony Frontmail używają składni Handlebars w treści HTML, wersji tekstowej, temacie i polach odbiorców. Frontmail uruchamia Handlebars w odizolowanym, zamkniętym środowisku: istnieją tylko helpery wymienione na tej stronie, partiale nie są dostępne, a każda wartość jest escapowana.

Zmienne

<p>Dzień dobry {{name}},</p>
<p>twoja rezerwacja na {{booking.date}} jest potwierdzona.</p>   {{!-- zagnieżdżony obiekt --}}
<p>{{default company "(bez firmy)"}}</p>                         {{!-- wartość zastępcza --}}

Brakująca wartość renderuje się jako pusty ciąg. Do komentarzy, które nigdy nie trafią do e-maila, używaj {{!-- … --}}.

Warunki

{{#if newsletter}}
  <p>Dziękujemy za zapis!</p>
{{else}}
  <p>Zapisać się możesz w każdej chwili.</p>
{{/if}}

{{#unless paid}}<p>Płatność jeszcze nie dotarła.</p>{{/unless}}

{{#if (eq topic "support")}}<p>Nasz dział wsparcia odpowie w ciągu jednego dnia.</p>{{/if}}
{{#if (and vip (gt total 1000))}}<p>🎁 Darmowa dostawa</p>{{/if}}
{{#if (or (eq country "PL") (eq country "CZ"))}}<p>Darmowa dostawa</p>{{/if}}

{{#if}} traktuje false, 0, "", null, brakujące wartości i puste listy jako fałsz.

Pętle

Użyj parametru typu list z itemFields:

<table>
  {{#each items}}
    <tr>
      <td>{{@index}}</td>
      <td>{{title}}</td>
      <td>{{qty}} × {{formatMoney price ../currency}}</td>
    </tr>
  {{else}}
    <tr><td colspan="3">Brak pozycji.</td></tr>
  {{/each}}
</table>

Wewnątrz {{#each}} this to bieżąca pozycja, dostępne są @index (od 0), @first i @last, a ../ sięga do kontekstu nadrzędnego. {{#with customer}}…{{/with}} zmienia kontekst, a {{lookup map key}} odczytuje dynamiczny klucz.

Helpery

Helper	Przykład	Wynik
`formatDate value [style] [timeZone=…] [locale=…]`	`{{formatDate arrival "long"}}`	`October 1, 2026` / `1 października 2026`
`formatNumber value [decimals=n]`	`{{formatNumber 1234.5 decimals=2}}`	`1,234.50` / `1234,50`
`formatMoney amount currency [minor=true]`	`{{formatMoney 49 "EUR"}}` · `{{formatMoney 4900 "EUR" minor=true}}`	`€49.00` / `49,00 €`
`uppercase value`	`{{uppercase code}}`	`ABC123`
`lowercase value`	`{{lowercase email}}`	`anna@example.com`
`default value fallback…`	`{{default nickname name "przyjacielu"}}`	pierwsza niepusta wartość
`eq a b` · `ne a b`	`{{#if (eq status "paid")}}`	luźna równość (`1` równa się `"1"`)
`gt a b` · `lt a b`	`{{#if (gt qty 10)}}`	porównanie liczbowe
`and a b …` · `or a b …` · `not a`	`{{#if (and a (not b))}}`	operacje logiczne (puste wartości są fałszem)
`json value`	`{{json items}}`	tekst JSON (escapowany) – przydaje się przy debugowaniu
`nl2br value`	`{{nl2br message}}`	escapowany tekst z podziałami wierszy zamienionymi na `<br>`

Style formatDate: date, datetime, time, short, long, full, iso. Język wyniku zależy od języka, w którym e-mail jest wysyłany – języka domyślnego szablonu albo wybranego tłumaczenia; dla pojedynczego wywołania zmienisz go przez locale="pl". Czas jest podawany w strefie czasowej organizacji, chyba że przekażesz timeZone="Europe/Warsaw".

Wywołanie każdego innego helpera to błąd kompilacji, który pokażą kontrole szablonu.

Zmienne systemowe

Zmienna	Wartość
`{{frontmail.message_id}}`	ID wiadomości, np. `msg_01J9Z3K7Q2` – przydaje się jako numer referencyjny.
`{{frontmail.sent_at}}`	Znacznik czasu ISO renderowania, np. `2026-09-24T10:11:05.000Z`. Połącz z `formatDate`.
`{{frontmail.origin}}`	`Origin` żądania z przeglądarki (np. `https://example.com`), pusty przy wysyłkach z serwera.

Nazwa frontmail jest zarezerwowana – nie możesz zdefiniować parametru o tej nazwie.

Escapowanie i typ `html`

Frontmail escapuje HTML w każdym wyniku, także w zapisach {{{triple}}} i {{& ampersand}}. Odwiedzający, który wpisze w formularzu <a href="…">click</a>, zobaczy w e-mailu dokładnie ten tekst, a nie link.

Gdy naprawdę potrzebujesz znaczników z parametrów (na przykład sformatowanego tekstu z własnego CMS), zadeklaruj parametr z typem html. Jego wartość przechodzi sanityzację według listy dozwolonych elementów:

tagi: a, b, strong, i, em, u, s, p, br, div, span, h1–h6, ul, ol, li, blockquote, pre, code, hr, img, table i jej części, small, sub, sup, center, font;
linki: http, https, mailto, tel; obrazy: http, https, cid;
style inline: kolory, grubość/krój/rozmiar czcionki, wysokość wiersza, wyrównanie i dekoracja tekstu, margin, padding, width, height, max-width;
wszystko inne (skrypty, iframe’y, formularze, obsługa zdarzeń, URL-e javascript:) jest usuwane.

Wyrenderuj go zwykłym {{body_html}} – zsanityzowana wartość zostanie wstawiona jako znaczniki.

Wersja tekstowa

Automatycznie generowana wersja tekstowa powstaje z wyrenderowanego HTML (linki zamieniają się na text (url), tabele na wiersze). Jeśli edytujesz wersję tekstową ręcznie, jest renderowana według tych samych zasad Handlebars, ale bez escapowania HTML.