Komponenty e-mailů

Všechny e-maily staví MailMessage nad jednou šablonou. Vzhled vychází z playbooku webu: černý text, barvy značky, písma Outfit (nadpisy) a Hanken Grotesk (text). Žádný e-mail si nenese vlastní styly ani ručně psané HTML. Přehled všech e-mailů je v inventuře. Každý e-mail vykreslený s ukázkovými daty najdeš mimo produkci v inventáři e-mailů na stránce /inventar-emailu.

Nový e-mail krok za krokem

1. Notifikaci podděď z třídy podle toho, kdo e-mail čte (tabulka níže).
2. Zprávu začni přes $this->mailMessage(), ne přes new MailMessage.
3. Oslovení ani podpis nepiš, zdědí se. Vlastní nastav jen tehdy, když ho e-mail opravdu potřebuje jiný.
4. Údaje, tlačítka, tabulky a upozornění skládej z komponent níže.
5. Přidej e-mail do App\Support\MailPreview\MailCatalog. Pak se sám objeví v playbooku e-mailů a projde ho test, který vykreslí všechny e-maily katalogu.

Publikum: oslovení, podpis a patička

Kdo e-mail čte, určuje třída, ze které notifikace dědí. Výchozí hodnoty drží výčet App\Enums\MailAudience.

Třída	Pro koho	Oslovení	Podpis	Patička
CustomerNotification	hráči a týmy, tykání	Ahoj,	Tým Chytrého Kvízu	web
EshopNotification	zákazníci e-shopu, tykání	Ahoj,	Tým Chytrého Kvízu	e-shop
FormalNotification	firmy, podniky, uchazeči a účty, vykání	Dobrý den,	S pozdravem / Tým Chytrého Kvízu	web
StaffNotification	moderátoři, kandidáti a provoz, vykání	Dobrý den,	S pozdravem / Tým Chytrého Kvízu	interní

Patička je vždy žlutá s černým logem, liší se obsahem:

• web: odkaz na web a e-mail MAIL_FROM_ADDRESS,
• e-shop: odkaz do obchodu, kontaktní osoba e-shopu z administrace (Systém > E-shop > Kontaktní osoba e-shopu) a odkazy na obchodní podmínky. Odpověď na e-mail (Reply-To) jde také na tuto osobu, takže věta „stačí odpovědět na tento e-mail“ platí,
• interní: bez odkazu na web, jen kontaktní e-mail a věta, že jde o zprávu z provozu.

Mimo produkci je nad hlavičkou červený pruh, že zpráva pochází z testovacího prostředí.

Šablona

Soubor	Co dělá
resources/views/vendor/mail/html/layout.blade.php	kostra e-mailu, písma a pravidla pro mobil a Outlook
resources/views/vendor/mail/html/header.blade.php	logo vlevo jako v hlavičce webu, mimo produkci varovný pruh
resources/views/vendor/mail/html/footer.blade.php	patička podle varianty (web, e-shop, interní): černé logo, odkazy, kontakt, copyright
resources/views/vendor/mail/html/message.blade.php	skládá hlavičku, obsah, podtext a patičku
resources/views/vendor/mail/html/themes/default.css	všechny styly; při odeslání se vloží přímo do prvků
resources/views/vendor/notifications/email.blade.php	oslovení, řádky, tlačítko a podpis z MailMessage

Písma a obrázky se načítají z vlastní domény přes MailComponents::assetUrl(), který adresu složí z APP_URL a doplní https://, když v ní schéma chybí. Klient, který webová písma neumí (Gmail, Outlook), použije Arial.

Komponenty

Komponenty vrací HtmlString, takže se vkládají rovnou do ->line(). PHP rozhraní je App\Support\MailComponents.

Tlačítko

Tlačítko má zkosený tvar jako .btn na webu. Jedno tlačítko přes ->action() je primární. Víc akcí vedle sebe:

->line(MailComponents::buttons([
    ['label' => 'Upravit počet hráčů', 'url' => $url],
    ['label' => 'Přidat se do skupiny', 'url' => $facebookUrl, 'variant' => 'facebook'],
    ['label' => 'Zrušit rezervaci', 'url' => $revokeUrl, 'link' => true],
]))

• primary (červená, výchozí): hlavní akce e-mailu. Nedávej vedle sebe dvě primární.
• secondary (zelená): vedlejší akce vedle primární.
• facebook (modrá): jen odkaz na facebookovou skupinu nebo stránku.
• link: nevratná nebo vedlejší akce (zrušení, odhlášení) jako nenápadný podtržený odkaz pod tlačítky, stejně jako „Zrušit tento termín” na webu.
• ->action() i buttons() kreslí stejná šablona button.blade.php. Outlook zkosení nevykreslí a ukáže obdélník.

Blok údajů

Údaje o události, týmu nebo odeslaném formuláři. Popisek vlevo, hodnota tučně vpravo, na mobilu pod sebou.

->line(MailComponents::details([
    'Datum' => $date,
    'Místo' => $event->pub->display_name,
    'Tým' => $reservation->team_name,
    'Telefon' => $reservation->phone,
]))

• Prázdná hodnota se vypíše jako „nevyplněno”.
• Hodnota delší než 60 znaků nebo s odřádkováním (třeba zpráva z formuláře) se vypíše pod popisek přes celou šířku bloku a normálním řezem písma, aby se dlouhý text nelámal do úzkého sloupce.
• Hodnoty se escapují a zalomení řádků zůstane. HTML jde jen přes HtmlString (například přeškrtnutý původní termín).
• Nepiš údaje jako Markdown **Datum:** … \n, vždy použij blok.

Volba počtu hráčů

Řada čtverců 48 × 48 px s počty hráčů, stejných jako na stránce změny rezervace. Každý čtverec vede rovnou na uložení počtu. U rezervace řadu skládá App\Support\PlayerCountChips, který hlídá kapacitu stolu a vynechá už nahlášený počet:

->line(PlayerCountChips::block($reservation, 'Přijde vás jiný počet? Vyberte rovnou ten správný:'))

Mimo rezervaci jde použít MailComponents::playerCounts([počet => url], 'Výzva').

Upozornění

Rámeček s textem v Markdownu, barva podle tónu jako hláška na webu: info (modrá, výchozí), success (zelená), warning (žlutá), danger (červená).

->line(MailComponents::panel('Odkaz platí **14 dní**.', 'warning'))

Tabulka

Například položky objednávky. Sloupce určují popisek a zarovnání, poslední řádek může být součet.

->line(MailComponents::table(
    [['label' => 'Název'], ['label' => 'Ks', 'align' => 'center'], ['label' => 'Celkem', 'align' => 'right']],
    [['Kvíz do kapsy', 2, '398 Kč']],
    ['Celkem', '', '398 Kč'],
))

Částka

Ceny v e-mailu piš přes MailComponents::money($castka, $mena). Celé částky vyjdou bez haléřů (1 250 Kč), ostatní s desetinnou čárkou (60,50 Kč), vždy s nezlomitelnými mezerami.

Kontrola

php artisan mail:preview --group=RES [email protected]

Pošle všechny e-maily skupiny s ukázkovými daty, lokálně do Mailpitu. Nový vzhled je potřeba zkontrolovat i v Gmailu, Seznamu, Outlooku a na mobilu.