Chytré HTML atributy

Latte 3.1 přichází se sadou vylepšení, která se zaměřuje na jednu z nejčastějších činností v šablonách – vypisování HTML atributů. Přináší více pohodlí, flexibility a bezpečnosti.

Boolean atributy

HTML používá speciální atributy jako checked, disabled, selected nebo readonly, u kterých nezáleží na konkrétní hodnotě – pouze na jejich přítomnosti. Fungují jako jednoduché příznaky.

Latte je zpracovává automaticky. Atributu můžete předat jakýkoliv výraz. Pokud je pravdivý (truthy), atribut se vykreslí. Pokud je nepravdivý (falsey, např. false, null, 0 nebo prázdný řetězec), atribut se zcela vynechá.

To znamená, že se můžete rozloučit se složitými podmínkami nebo n:attr a jednoduše použít:

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

Pokud je $isDisabled false a $isReadOnly je true, vykreslí se:

<input type="text" readonly>

Pokud potřebujete přepínací chování pro standardní atributy, které nemají toto automatické zpracování (tedy např. atributy data- nebo aria-), použijte filtr toggle.

Atributy hidden a popover jsou také příznaky, ale mohou nést i klíčové slovo. hidden={$value} tedy vypíše pro true jen hidden, řetězec ponechá jako hodnotu, např. hidden="until-found", a pro nepravdivou hodnotu atribut vynechá.

Atributy s hodnotami true a false

Některé atributy vypadají jako příznaky, ale nejsou jimi. contenteditable, draggable, spellcheck a writingsuggestions očekávají jako hodnotu slovo true nebo false a vynechaný atribut neznamená ani jedno: prvek pak nastavení zdědí od rodiče, nebo ho nechá na prohlížeči. Pokud chcete, aby odstavec uvnitř editovatelné oblasti editovat nešel, musí mít contenteditable="false"; bez atributu by zůstal editovatelný.

Proto Latte v těchto atributech vypisuje logické hodnoty jako slova "true" a "false", stejně jako u atributů aria-:

<div contenteditable={$canEdit} draggable={=true} spellcheck={=false}>

Pokud je $canEdit false, vykreslí se:

<div contenteditable="false" draggable="true" spellcheck="false">

Jakákoliv jiná hodnota, třeba plaintext-only, se vypíše tak, jak je, a null atribut vynechá, stejně jako všude jinde.

Hodnoty null

Toto je jedna z nejpříjemnějších změn. Dříve, pokud byla proměnná null, vypsala se jako prázdný řetězec "". To často vedlo k prázdným atributům v HTML jako class="" nebo title="".

V Latte 3.1 platí nové univerzální pravidlo: Hodnota null znamená, že atribut neexistuje.

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

Pokud je $title null, výstupem je <div></div>. Pokud obsahuje řetězec, např. „Ahoj“, výstupem je <div title="Ahoj"></div>. Díky tomu nemusíte obalovat atributy do podmínek. Toto pravidlo platí, když je hodnotou atributu jediný výraz {...}; u smíšené hodnoty jako title="foo {$bar}" se null vypíše jako prázdný řetězec.

Pokud používáte filtry, mějte na paměti, že obvykle převádějí null na řetězec (např. prázdný řetězec). Abyste tomu zabránili, použijte nullsafe filtr ?|:

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

Třídy (Classes)

Atributu class můžete předat pole. To je ideální pro podmíněné třídy: pokud je pole asociativní, klíče se použijí jako názvy tříd a hodnoty jako podmínky. Třída se vykreslí pouze v případě, že je podmínka splněna.

<button class={[
	btn,
	btn-primary,
	active => $isActive,
]}>Stiskni mě</button>

Pokud je $isActive true, vykreslí se:

<button class="btn btn-primary active">Stiskni mě</button>

Toto chování není omezeno pouze na class. Funguje pro vybranou sadu atributů, které očekávají seznam hodnot oddělených mezerou: accesskey, class, headers, itemprop, ping, rel, role, sandbox a všechny atributy aria-*. U jakéhokoliv jiného atributu předání pole vyvolá varování a hodnota se zahodí.

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

Styly (Styles)

Atribut style také podporuje pole. Je to obzvláště užitečné pro podmíněné styly. Pokud položka pole obsahuje klíč (CSS vlastnost) a hodnotu, vlastnost se vynechá, když je hodnota null, false, 0 nebo prázdný řetězec, takže třeba opacity => 0 se nevykreslí.

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

Pokud je $isVisible false, vykreslí se:

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

Data atributy

Často potřebujeme do HTML předat konfiguraci pro JavaScript. Dříve se to dělalo přes json_encode. Nyní můžete atributu data- jednoduše předat pole nebo objekt stdClass a Latte jej serializuje do JSONu:

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

Vypíše:

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

Také true a false se vykreslují jako řetězce "true" a "false" (tj. validní JSON).

Aria atributy

Specifikace WAI-ARIA vyžaduje textové hodnoty "true" a "false" pro logické hodnoty. Latte to pro atributy aria- řeší automaticky:

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

Vypíše:

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

Stejně jako class přijímají i atributy aria- pole. To se zpracuje jako seznam hodnot oddělených mezerou: prosté hodnoty se použijí tak, jak jsou, a klíč se zahrne pouze tehdy, když je jeho hodnota true:

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

Typová kontrola

Už jste někdy viděli <input value="Array"> ve svém vygenerovaném HTML? Je to klasická chyba, která často projde bez povšimnutí. Latte zavádí přísnou typovou kontrolu pro HTML atributy, aby byly vaše šablony vůči takovým přehlédnutím odolnější.

Latte ví, které atributy jsou které a jaké hodnoty očekávají:

  • Standardní atributy (jako href, id, value, placeholder…) očekávají hodnotu, kterou lze vykreslit jako text. To zahrnuje řetězce, čísla nebo stringable objekty. Také je akceptováno null (atribut se vynechá). Pokud však omylem předáte pole, boolean nebo obecný objekt, Latte vyvolá varování a neplatnou hodnotu inteligentně ignoruje.
  • Boolean atributy (jako checked, disabled…) akceptují jakýkoliv typ, protože jejich přítomnost je určena logikou pravdivý/nepravdivý.
  • Chytré atributy (jako class, style, data-…) přijímají pole jako platnou hodnotu.

Tato kontrola zajišťuje, že vaše aplikace nebude generovat neočekávané HTML.

Migrace z Latte 3.0

Protože se změnilo chování null (dříve vypisovalo "", nyní atribut vynechá) a atributů data- a také contenteditable, draggable, spellcheck a writingsuggestions (boolean hodnoty vypisovaly "1"/"", nyní "true"/"false"), možná budete muset aktualizovat své šablony.

Pro hladký přechod poskytuje Latte migrační režim, který upozorňuje na rozdíly. Přečtěte si podrobného průvodce Migrace z Latte 3.0 na 3.1.

verze: 3.x