Nunjucks (templating for HTML mail)

Nunjucks to silnik szablonów dla JavaScriptu, wykorzystywany m.in. do generowania treści wiadomości HTML.

Nunjucks jako silnik generowania treści HTML

Nunjucks jest silnikiem szablonów przeznaczonym dla środowiska JavaScript. Pozwala oddzielić strukturę dokumentu HTML od danych, które mają zostać wstawione do gotowej wiadomości. Szablon zawiera znaczniki HTML oraz wyrażenia Nunjucks, a aplikacja JavaScript przekazuje do niego kontekst, czyli obiekt z wartościami używanymi podczas renderowania. Wynikiem działania jest zwykły tekst, najczęściej kompletny dokument HTML wiadomości e-mail.

Składnia Nunjucks przypomina rozwiązania znane z Jinja2. Zmienną można umieścić w szablonie za pomocą zapisu {{ userName }}, instrukcje sterujące zapisuje się między znacznikami {% ... %}, a komentarze szablonu między {# ... #}. Przykładowy fragment <p>Witaj, {{ userName }}!</p> po renderowaniu może stać się elementem HTML zawierającym konkretną nazwę odbiorcy. Sam Nunjucks nie wysyła wiadomości i nie jest serwerem pocztowym; odpowiada za przygotowanie tekstu wynikowego.

Zmienne, warunki i pętle w szablonie wiadomości

Wiadomość HTML może być budowana na podstawie danych przekazanych do funkcji renderującej. Nunjucks obsługuje odczyt właściwości obiektów, indeksowanie tablic, operatory logiczne oraz instrukcje warunkowe. Konstrukcja {% if invoice.paid %}Opłacono{% else %}Oczekuje na płatność{% endif %} pozwala zmienić treść zależnie od wartości pola paid. Warunek jest wykonywany podczas renderowania, więc klient pocztowy otrzymuje już gotowy tekst, a nie kod Nunjucks.

Do powtarzania elementów służy instrukcja {% for item in items %}. Można w ten sposób wygenerować wiersze tabeli z listą produktów, usług albo pozycji dokumentu. Nunjucks udostępnia również filtry, między innymi do zmiany wielkości liter, formatowania wartości tekstowych oraz łączenia danych. Dostępne filtry zależą od wersji i konfiguracji środowiska, dlatego aplikacja powinna używać nazw sprawdzonych w dokumentacji oraz testach projektu. Własne filtry można rejestrować w środowisku Nunjucks, aby ujednolicić formatowanie danych przed wstawieniem ich do HTML.

Większe szablony można dzielić na makra, pliki dołączane oraz szablony bazowe. Mechanizm dziedziczenia umożliwia zdefiniowanie wspólnego układu, na przykład nagłówka i stopki, a następnie uzupełnienie bloku treścią konkretnej wiadomości. Instrukcje {% extends "base.njk" %}, {% block content %} i {% include "fragment.njk" %} służą do organizowania takich zależności. Loader, czyli obiekt odpowiedzialny za wyszukiwanie plików, musi mieć dostęp do właściwego katalogu szablonów.

Bezpieczne renderowanie i zgodność z formatem poczty

W przypadku wiadomości HTML szczególne znaczenie ma kodowanie danych pochodzących od użytkownika lub z zewnętrznych rekordów. Nunjucks pozwala włączyć automatyczne escapowanie HTML, ale w typowej konfiguracji nie należy zakładać, że każda wartość zostanie automatycznie zabezpieczona bez sprawdzenia ustawień środowiska. Escapowanie zamienia znaki takie jak <, >, & i cudzysłowy na bezpieczne reprezentacje tekstowe. Dzięki temu nazwa zawierająca znaczniki HTML nie zostanie przypadkowo potraktowana jako element dokumentu.

Znacznik | safe wyłącza escapowanie konkretnej wartości. Powinien być stosowany tylko wtedy, gdy aplikacja ma pewność, że przekazywany fragment jest kontrolowanym, poprawnie przygotowanym HTML-em. Nie jest właściwe używanie tego filtra do dowolnych danych z formularza, nazw klientów lub opisów pobranych z bazy. Nunjucks nie zastępuje walidacji danych ani filtrów dostosowanych do kontekstu użycia. Osobno należy traktować tekst umieszczany w treści HTML, a osobno wartości używane w atrybutach, adresach URL lub stylach.

Silnik generuje tekst, lecz nie zapewnia automatycznie zgodności ze wszystkimi ograniczeniami klientów pocztowych. Układ wiadomości często opiera się na tabelach HTML i stylach osadzonych bezpośrednio w atrybucie style, ponieważ różne programy pocztowe różnie obsługują CSS. Nunjucks może wstawić takie elementy do szablonu, ale sam nie wykonuje inliningu CSS, nie sprawdza renderowania w Outlooku ani nie testuje wiadomości w Gmailu. Weryfikacja powinna obejmować wynikową wiadomość, obecność wymaganych zamkniętych znaczników, kodowanie UTF-8 oraz poprawne przekazanie treści do biblioteki wysyłającej pocztę.

Kontrola zależności między danymi a wynikiem renderowania

Typowy przepływ pracy wygląda następująco: aplikacja tworzy środowisko Nunjucks, konfiguruje loader, odczytuje plik szablonu, przekazuje kontekst i wywołuje renderowanie. Do renderowania tekstu znajdującego się bezpośrednio w pamięci można użyć funkcji środowiska odpowiadającej renderowaniu łańcucha, natomiast przy plikach wykorzystywany jest skonfigurowany loader. W projekcie warto rozdzielić przygotowanie danych od samego renderowania, aby można było niezależnie sprawdzić, czy kontekst zawiera wszystkie wymagane pola.

Błąd w nazwie zmiennej, brak pliku dołączanego przez include albo niepoprawna składnia instrukcji może przerwać renderowanie i uniemożliwić przygotowanie wiadomości. Dlatego test powinien sprawdzać nie tylko brak wyjątku, lecz także zawartość wyniku: tytuł, dane odbiorcy, listę pozycji, linki oraz warunkowe fragmenty. Przydatne jest renderowanie tego samego szablonu z kompletnym kontekstem, pustą tablicą i wartościami granicznymi. Pozwala to wykryć sytuację, w której poprawny jest wariant zwykły, ale brakuje komunikatu dla pustej listy.

Należy również pamiętać o różnicy między kodem wykonywanym podczas renderowania a kodem wynikowym. Instrukcje Nunjucks, takie jak {% if %} i {% for %}, znikają po wygenerowaniu wiadomości. Odbiorca dostaje HTML z konkretnymi wartościami, dlatego zmiana danych po wysłaniu nie zmieni już treści wiadomości. W razie problemów diagnostycznych warto zapisać bezpieczny podgląd wyniku renderowania, nazwę użytego szablonu i informację o brakujących polach, bez rejestrowania całej treści zawierającej dane odbiorców.

W środowisku użytkownika końcowego problemy z Nunjucks zwykle wynikają z aplikacji przygotowującej wiadomość, jej zależności albo konfiguracji ścieżki do szablonów, a nie z awarii samego laptopa. Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, natomiast diagnoza błędu renderowania wymaga sprawdzenia programu, logów oraz konfiguracji środowiska, w którym działa kod JavaScript.