Pug + MJML

Pug w połączeniu z MJML pozwala generować responsywne szablony wiadomości HTML z poziomu składni szablonów.

Pug jako warstwa składniowa dla szablonu MJML

Pug i MJML pełnią w takim rozwiązaniu różne funkcje. Pug jest silnikiem szablonów, który pozwala zapisywać strukturę dokumentu w postaci wcięć zamiast znaczników zamykających HTML. Obsługuje między innymi zmienne, interpolację wartości, instrukcje warunkowe, pętle, dziedziczenie szablonów oraz dołączanie fragmentów przez mechanizmy include i extends. MJML jest natomiast językiem znaczników przeznaczonym do opisywania układu wiadomości e-mail. Jego elementy, takie jak <mjml>, <mj-head>, <mj-body>, <mj-section>, <mj-column> i <mj-text>, są przetwarzane przez kompilator MJML do kodu HTML dostosowanego do ograniczeń klientów pocztowych.

Połączenie tych technologii polega zwykle na umieszczeniu składni MJML wewnątrz pliku Pug albo na wygenerowaniu przez Pug tekstu zawierającego dokument MJML. Przykładowo Pug może wstawić do nagłówka wiadomości nazwę użytkownika, adres odsyłacza lub listę pozycji zamówienia, a następnie wynik zostaje przekazany do kompilatora MJML. Kolejność etapów ma znaczenie: najpierw Pug musi otrzymać dane i wykonać interpolację, a później MJML powinien przekształcić kompletną strukturę komponentów do HTML. Sam Pug nie zapewnia responsywności wiadomości, a sam MJML nie jest silnikiem przeznaczonym do wykonywania logiki aplikacyjnej.

Przepływ kompilacji od danych do wiadomości HTML

Typowy przepływ obejmuje przygotowanie danych, renderowanie szablonu Pug, kompilację MJML oraz przekazanie końcowego HTML do biblioteki wysyłającej pocztę. Dane mogą zawierać na przykład tytuł wiadomości, imię odbiorcy, adres przycisku i kolekcję elementów wyświetlanych w treści. W Pug pętla może wygenerować kilka komponentów mj-text lub mj-button, lecz wartości umieszczane w atrybutach i treści powinny być poprawnie kodowane. Wstawienie niezweryfikowanego tekstu bez escapowania może zmienić strukturę wynikowego dokumentu albo wprowadzić niepożądany kod HTML.

W środowisku Node.js kompilację MJML można wykonywać programowo za pomocą pakietu mjml, który przyjmuje tekst MJML i zwraca wynik HTML oraz informacje o błędach lub ostrzeżeniach. Pug może być używany przez pakiet pug, metodę pug.renderFile albo wcześniej przygotowany mechanizm renderowania szablonów w aplikacji. Ważne jest rozdzielenie szablonu od danych: kod Pug powinien opisywać strukturę i reguły prezentacji, natomiast dane wiadomości powinny pochodzić z kontrolowanego obiektu wejściowego. Błąd w pierwszym etapie może spowodować, że MJML otrzyma niepełny dokument, dlatego aplikacja powinna sprawdzać wynik obu kompilacji przed wysyłką.

Responsywny układ i ograniczenia klientów pocztowych

MJML generuje HTML z tabelami, stylami inline oraz regułami CSS stosowanymi zależnie od możliwości klienta pocztowego. Komponenty mj-section i mj-column opisują układ sekcji oraz kolumn, a atrybuty takie jak width, padding, background-color i font-size określają wygląd. Dla widoku mobilnego MJML może wygenerować reguły oparte na media queries, ale ich działanie zależy od programu pocztowego. Nie każdy klient interpretuje CSS w wiadomościach w jednakowy sposób, dlatego wynik trzeba sprawdzać w kilku popularnych aplikacjach, a nie tylko w przeglądarce.

Połączenie Pug z MJML nie oznacza, że dowolny kod HTML lub CSS wpisany do szablonu będzie zachowywał się identycznie w każdej skrzynce. Komponenty MJML mają określone zastosowanie i zestaw obsługiwanych atrybutów, a niestandardowy kod można dodawać przez mechanizmy takie jak mj-style lub mj-raw, jednak wtedy odpowiedzialność za zgodność spada w większym stopniu na autora szablonu. Warto również kontrolować temat kodowania znaków, kompletność adresów URL oraz obecność tekstowej wersji wiadomości. Testowanie powinno obejmować wynik po kompilacji, ponieważ dopiero wygenerowany HTML pokazuje faktyczną strukturę tabel, stylów i odsyłaczy wysyłanych odbiorcy.

Praktyczne utrzymanie szablonów Pug i MJML

Przy większej liczbie wiadomości pomocny jest podział na części wspólne: nagłówek, stopkę, przyciski, moduły informacyjne i sekcje z danymi. Pug pozwala wydzielać takie fragmenty do osobnych plików oraz przekazywać im parametry, a MJML zachowuje jednolity model układu dla poszczególnych komponentów. Należy jednak sprawdzić, czy używane nazwy zmiennych, wartości domyślne i warunki są spójne między wszystkimi szablonami. Błąd typograficzny w nazwie pola może skutkować pustym tekstem albo pustym odsyłaczem, mimo że sama kompilacja zakończy się bez błędu składni.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i podzespołów, a przy diagnostyce problemów z lokalnym środowiskiem programistycznym można sprawdzić między innymi wersję Node.js, poprawność instalacji pakietów Pug i MJML, komunikaty kompilatora oraz sposób przekazywania danych do szablonu. Istotne jest odtworzenie błędu na konkretnym pliku i zestawie danych, ponieważ problem może wynikać zarówno z nieprawidłowej składni Pug, jak i z błędnej struktury MJML lub brakującej wartości wejściowej. Taka weryfikacja pozwala oddzielić usterkę konfiguracji narzędzi od błędu w samej logice generowania wiadomości.