Smart atrybuty HTML

Latte 3.1 przynosi zestaw usprawnień skupionych wokół jednej z najczęstszych czynności w szablonach – wypisywania atrybutów HTML. Dają one więcej wygody, elastyczności i bezpieczeństwa.

Atrybuty logiczne

HTML używa specjalnych atrybutów takich jak checked, disabled, selected czy hidden, w których konkretna wartość nie ma znaczenia – liczy się tylko ich obecność. Działają jak zwykłe flagi.

Latte obsługuje je automatycznie. Do atrybutu możesz przekazać dowolne wyrażenie. Jeśli jest prawdziwe, atrybut zostanie wyrenderowany. Jeśli jest fałszywe (np. false, null, 0 albo pusty łańcuch), atrybut zostanie całkowicie pominięty.

Oznacza to, że możesz pożegnać się z uciążliwymi warunkami w makrach albo z n:attr i po prostu napisać:

<input type="text" disabled={$isDisabled} readonly={$isReadOnly}>

Jeśli $isDisabled jest false, a $isReadOnly jest true, wyrenderuje się:

<input type="text" readonly>

Jeśli potrzebujesz takiego przełączania dla zwykłych atrybutów, które nie mają tej automatycznej obsługi (jak atrybuty data- czy aria-), użyj filtra toggle.

Wartości null

To jedna z najprzyjemniejszych zmian. Wcześniej, jeśli zmienna miała wartość null, wypisywała się jako pusty łańcuch "". Często prowadziło to do pustych atrybutów w HTML, takich jak class="" czy title="".

W Latte 3.1 obowiązuje nowa uniwersalna zasada: wartość null oznacza, że atrybut nie istnieje.

<div title="{$title}"></div>

Jeśli $title jest null, wynikiem jest <div></div>. Jeśli zawiera łańcuch, np. “Cześć”, wynikiem jest <div title="Cześć"></div>. Dzięki temu nie musisz otaczać atrybutów warunkami. Ta zasada obowiązuje, gdy wartością atrybutu jest pojedyncze wyrażenie {...}; przy wartości mieszanej, jak title="foo {$bar}", null wypisze się jako pusty łańcuch.

Jeśli używasz filtrów, pamiętaj, że zwykle konwertują one null na łańcuch (np. pusty). Aby temu zapobiec, użyj filtra nullsafe ?|:

<div title="{$title?|upper}"></div>

Klasy

Do atrybutu class możesz przekazać tablicę. Świetnie sprawdza się to przy klasach warunkowych: jeśli tablica jest asocjacyjna, klucze są używane jako nazwy klas, a wartości jako warunki. Klasa zostanie wyrenderowana tylko wtedy, gdy warunek jest prawdziwy.

<button class={[
	btn,
	btn-primary,
	active => $isActive,
]}>Naciśnij mnie</button>

Jeśli $isActive jest true, wyrenderuje się:

<button class="btn btn-primary active">Naciśnij mnie</button>

To zachowanie nie ogranicza się do class. Działa dla wybranego zestawu atrybutów, które oczekują listy wartości oddzielonych spacją: accesskey, class, headers, itemprop, ping, rel, role, sandbox i wszystkich atrybutów aria-*. Przy jakimkolwiek innym atrybucie przekazanie tablicy wywoła ostrzeżenie, a wartość zostanie odrzucona.

<a rel={[nofollow, noopener, external => $isExternal]}>odnośnik</a>

Style

Atrybut style również obsługuje tablice. Przydaje się zwłaszcza przy stylach warunkowych. Jeśli element tablicy zawiera klucz (właściwość CSS) i wartość, właściwość zostanie pominięta, gdy wartość to null, false, 0 albo pusty łańcuch, więc na przykład opacity => 0 się nie wyrenderuje.

<div style={[
	background => lightblue,
	display => $isVisible ? block : null,
	font-size => '16px',
]}></div>

Jeśli $isVisible jest false, wyrenderuje się:

<div style="background: lightblue; font-size: 16px"></div>

Atrybuty data

Często potrzebujemy przekazać do HTML konfigurację dla JavaScriptu. Wcześniej robiło się to przez json_encode. Teraz wystarczy przekazać do atrybutu data- tablicę albo obiekt stdClass, a Latte zserializuje go do JSON-a:

<div data-config={[ theme: dark, version: 2 ]}></div>

Wypisze:

<div data-config='{"theme":"dark","version":2}'></div>

Ponadto true i false renderują się jako łańcuchy "true" i "false" (czyli poprawny JSON).

Atrybuty aria

Specyfikacja WAI-ARIA wymaga dla wartości logicznych tekstowych wartości "true" i "false". Latte robi to dla atrybutów aria- automatycznie:

<button aria-expanded={=true} aria-checked={=false}></button>

Wypisze:

<button aria-expanded="true" aria-checked="false"></button>

Tak jak class, atrybuty aria- również przyjmują tablicę. Traktowana jest jako lista oddzielona spacjami: zwykłe wartości są używane w takiej postaci, w jakiej są, a klucz trafia do wyniku tylko wtedy, gdy jego wartość to true:

<span aria-labelledby={[title, description => $hasDescription]}></span>

Kontrola typów

Widziałeś kiedyś w wygenerowanym HTML <input value="Array">? To klasyczny błąd, który często umyka uwadze. Latte wprowadza ścisłą kontrolę typów atrybutów HTML, aby Twoje szablony były odporniejsze na takie przeoczenia.

Latte wie, który atrybut jest jakiego rodzaju i jakich wartości oczekuje:

  • Zwykłe atrybuty (jak href, id, value, placeholder…) oczekują wartości, którą da się wypisać jako tekst. Obejmuje to łańcuchy, liczby i obiekty konwertowalne na łańcuch. Akceptowany jest też null (usuwa atrybut). Jeśli jednak przypadkiem przekażesz tablicę, wartość logiczną albo zwykły obiekt, Latte wywoła ostrzeżenie i inteligentnie zignoruje nieprawidłową wartość.
  • Atrybuty logiczne (jak checked, disabled…) przyjmują dowolny typ, bo ich obecność wynika z logiki prawda/fałsz.
  • Smart atrybuty (jak class, style, data-…) traktują tablice jako prawidłowe wejście.

Ta kontrola gwarantuje, że Twoja aplikacja nie wyprodukuje nieoczekiwanego HTML.

Migracja z Latte 3.0

Ponieważ zachowanie null (dawniej wypisywało "", teraz usuwa atrybut) i atrybutów data- (wartości logiczne dawniej wypisywały "1"/"", teraz "true"/"false") się zmieniło, być może będziesz musiał zaktualizować swoje szablony.

Aby przejście było płynne, Latte udostępnia tryb migracyjny, który uwidacznia różnice. Przeczytaj szczegółowy przewodnik Migracja z Latte 3.0 do 3.1.

wersja: 3.x