Latte tagy (makra)

Přehled a popis všech tagů (značek či maker) šablonovacího systému Latte, které máte standardně k dispozici.

Vypisování

{$var} {...} {=...}

Latte používá značku {=...} pro výpis jakéhokoliv výrazu. Pro vaše pohodlí Latte nevyžaduje rovnítko, pokud výraz začíná proměnnou nebo voláním funkce. To v praxi znamená, že ho téměř nikdy nemusíte psát:

Jméno: {$name} {$surname}<br>
Věk: {date('Y') - $birth}<br>

Můžete zapsat libovolný výraz, který znáte z PHP. Není třeba se učit nový jazyk. Například:

{='0' . ($num ?? $num * 3) . ', ' . PHP_VERSION}

Prosím, nehledejte v předchozím příkladu žádný smysl, ale kdybyste tam nějaký našli, napište nám :-)

Escapování výstupu

Nejdůležitějším úkolem šablonovacího systému je zabránit bezpečnostním dírám. A přesně to Latte dělá vždy, když něco vypisujete. Automaticky to escapuje:

<p>{='one < two'}</p>   {* vypíše: '<p>one &lt; two</p>' *}

Přesněji řečeno, Latte používá kontextově sensitivní escapování, což je tak důležitá a unikátní vlastnost, že jsme jí věnovali samostatnou kapitolu.

Co když potřebujete vypsat obsah kódovaný v HTML z důvěryhodného zdroje? Jednoduše můžete escapování vypnout:

{$trustedHtmlString|noescape}

Nesprávné použití filtru noescape může vést ke vzniku zranitelnosti XSS! Nikdy jej nepoužívejte, pokud si nejste naprosto jisti, co děláte a že vypisovaný řetězec pochází z důvěryhodného zdroje.

Vypsání v JavaScriptu

Díky kontextově sensitivnímu escapování je neobyčejně snadné vypisovat proměnné uvnitř JavaScriptu a Latte se postará o správné escapování.

Proměnná nemusí být jen řetězec, podporován je kterýkoliv datový typ, který se zakóduje jako JSON:

{var $foo = ['hello', true, 1]}
<script>
	alert({$foo});
</script>

Vygeneruje:

<script>
	alert(["hello", true, 1]);
</script>

To je také důvod, proč se kolem proměnné nepíší uvozovky: Latte je u řetězců doplní samo. Pokud chcete řetězcovou proměnnou vložit do jiného řetězce, jednoduše je spojte:

<script>
	alert('Hello ' + {$name} + '!');  // OK

	alert({="Hello $name!"});         // OK

	alert('Hello {$name} !');         // CHYBA!
</script>

Filtry

Vypsaný výraz může být upraven filtrem. Například takto řetězec převedeme na velká písmena a zkrátíme na maximálně 30 znaků:

{$string|upper|truncate:30}

Filtry můžete používat i na dílčí části výrazu:

{$left . ($middle|upper) . $right}

Podmínky

{if} {elseif} {else}

Podmínky v Latte se chovají stejně jako jejich protějšky v PHP. Můžete v nich používat stejné výrazy, jaké znáte z PHP, takže se nemusíte učit nový jazyk.

{if $product->inStock > Stock::Minimum}
	Skladem
{elseif $product->isOnWay()}
	Na cestě
{else}
	Není dostupné
{/if}

Jako každou párovou značku lze i {if} ... {/if} zapsat v podobě n:attributu:

<p n:if="$count > 0">Skladem {$count} kusů</p>

Můžete k n:atributům připojit prefix tag-. Pak se podmínka bude vztahovat jen na vypsání HTML značek a obsah mezi nimi se vypíše vždy:

<a href="..." n:tag-if="$clickable">Hello</a>

{* vypíše 'Hello' když $clickable je nepravdivá *}
{* vypíše '<a href="...">Hello</a>' když $clickable je pravdivá *}

Praktické, že?

n:else

Pokud podmínku {if} ... {/if} zapíšete v podobě n:attributu, můžete uvést i alternativní větev pomocí n:else:

<strong n:if="$count > 0">Skladem {$count} kusů</strong>

<em n:else>není dostupné</em>

Atribut n:else můžete použít také ve dvojici s n:ifset, n:foreach, n:try, n:ifcontent a n:ifchanged.

{/if $cond}

Výraz v podmínce {if} lze uvést také v ukončovací značce. To se hodí v situacích, kdy při otevírání podmínky ještě jeho hodnotu neznáme. Říkáme tomu odložené rozhodnutí.

Například začneme vypisovat tabulku se záznamy z databáze a teprve po dokončení výpisu si uvědomíme, že v databázi žádný záznam nebyl. Tak dáme podmínku do koncové značky {/if} a pokud žádný záznam nebude, nic se nevypíše:

{if}
	<h1>Výpis řádků z databáze</h1>

	<table>
	{foreach $resultSet as $row}
		...
	{/foreach}
	</table>
{/if isset($row)}

Šikovné, že?

V odložené podmínce lze použít i {else}, ale nikoliv {elseif}.

{ifset} {elseifset}

Viz také {ifset block}

Pomocí podmínky {ifset $var} zjistíme, zda proměnná (nebo více proměnných) existuje a má nenullovou hodnotu. Je to ekvivalent if (isset($var)) v PHP. Jako každou párovou značku ji lze zapsat i v podobě n:attributu:

<meta name="robots" content={$robots} n:ifset="$robots">

{ifchanged}

{ifchanged} kontroluje, zda se hodnota proměnné změnila od poslední iterace ve smyčce (foreach, for nebo while).

Pokud ve značce uvedeme jednu či více proměnných, bude kontrolovat, zda se nějaká z nich změnila, a podle toho vypíše obsah. Například tento kód vypíše první písmenko jména jako nadpis pokaždé, když se při výpisu jmen změní:

{foreach ($names|sort) as $name}
	{ifchanged $name[0]} <h2>{$name[0]}</h2> {/ifchanged}

	<p>{$name}</p>
{/foreach}

Pokud neuvedeme žádný argument, bude se kontrolovat vykreslený obsah oproti jeho předchozímu stavu. V předchozím příkladu tedy můžeme argument ve značce vynechat. Samozřejmě také můžeme použít n:attribut:

{foreach ($names|sort) as $name}
	<h2 n:ifchanged>{$name[0]}</h2>

	<p>{$name}</p>
{/foreach}

Uvnitř {ifchanged} lze také použít klauzuli {else}.

{switch} {case} {default}

Porovnává hodnotu s více možnostmi. Je to obdoba podmíněného příkazu switch z PHP, ale Latte ho vylepšuje:

• používá striktní porovnání (===)
• nepotřebuje break

Je to tedy přesný ekvivalent struktury match, kterou přináší PHP 8.0.

{switch $transport}
	{case train}
		Vlakem
	{case plane}
		Letecky
	{default}
		Jinak
{/switch}

Klauzule {case} může obsahovat více hodnot oddělených čárkami:

{switch $status}
{case $status::New}<b>nová položka</b>
{case $status::Sold, $status::Unknown}<i>není dostupná</i>
{/switch}

Cykly

V Latte najdete všechny cykly, které znáte z PHP: foreach, for a while.

{foreach}

Cyklus zapíšeme stejně jako v PHP:

{foreach $langs as $code => $lang}
	<span>{$lang}</span>
{/foreach}

Navíc má několik šikovných vylepšení, o kterých si nyní povíme.

Latte kontroluje, zda vytvořené proměnné nechtěně nepřepisují globální proměnné téhož jména. To vás ochrání před situací, kdy počítáte s tím, že v $lang je aktuální jazyk stránky, ale foreach $langs as $lang vám tu proměnnou přepíše.

Cyklus foreach lze také elegantně a úsporně zapsat pomocí n:attributu:

<ul>
	<li n:foreach="$items as $item">{$item->name}</li>
</ul>

Víte, že k n:atributům můžete připojit prefix inner-? Pak se bude ve smyčce opakovat pouze vnitřek elementu:

<div n:inner-foreach="$items as $item">
	<h4>{$item->title}</h4>
	<p>{$item->description}</p>
</div>

Takže se vypíše něco jako:

<div>
	<h4>Foo</h4>
	<p>Lorem ipsum.</p>
	<h4>Bar</h4>
	<p>Sit dolor.</p>
</div>

{else}

Uvnitř cyklu foreach můžete použít klauzuli {else}, jejíž obsah se zobrazí, pokud je cyklus prázdný:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Litujeme, v tomto seznamu nejsou žádní uživatelé</em></li>
	{/foreach}
</ul>

$iterator

Uvnitř cyklu foreach vytvoří Latte proměnnou $iterator, která poskytuje užitečné informace o probíhajícím cyklu:

• $iterator->first – je to první průchod?
• $iterator->last – je to poslední průchod?
• $iterator->counter – počítadlo, začíná od 1
• $iterator->counter0 – počítadlo, začíná od 0
• $iterator->odd – je to lichý průchod?
• $iterator->even – je to sudý průchod?
• $iterator->parent – iterator obklopující ten aktuální
• $iterator->nextValue – následující položka
• $iterator->nextKey – klíč následující položky

{foreach $rows as $row}
	{if $iterator->first}<table>{/if}

	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>

	{if $iterator->last}</table>{/if}
{/foreach}

Latte je chytré a $iterator->last funguje nejen u polí, ale i když cyklus probíhá nad obecným iterátorem, kde není dopředu znám počet položek.

{first} {last} {sep}

Tyto značky lze používat uvnitř cyklu {foreach}. Obsah {first} se vykreslí při prvním průchodu. Obsah {last} se vykreslí při posledním průchodu. Jde vlastně o zkratky pro {if $iterator->first} a {if $iterator->last}.

Značky lze také elegantně použít jako n:attributy:

{foreach $rows as $row}
	{first}<h1>Seznam jmen</h1>{/first}

	<p>{$row->name}</p>

	<hr n:last>
{/foreach}

Obsah značky {sep} se vykreslí, pokud průchod není poslední. Hodí se pro vykreslování oddělovačů, například čárek mezi vypisovanými položkami:

{foreach $items as $item} {$item} {sep}, {/sep} {/foreach}

To je docela praktické, že?

{iterateWhile}

Zjednodušuje seskupování lineárních dat během iterování v cyklu foreach tím, že iteraci provádí ve vnořené smyčce, dokud je splněná podmínka. Přečtěte si podrobný návod.

Může také elegantně nahradit {first} a {last} v příkladu výše:

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

Viz také filtry batch a group.

{for}

Cyklus zapisujeme stejně jako v PHP:

{for $i = 0; $i < 10; $i++}
	<span>Položka {$i}</span>
{/for}

Značku lze také použít jako n:attribut:

<h1 n:for="$i = 0; $i < 10; $i++">{$i}</h1>

{while}

Opět zapisujeme cyklus stejně jako v PHP:

{while $row = $result->fetch()}
	<span>{$row->title}</span>
{/while}

Nebo jako n:attribut:

<span n:while="$row = $result->fetch()">
	{$row->title}
</span>

Je možná i varianta s podmínkou v koncové značce, která odpovídá v PHP cyklu do-while:

{while}
	<span>{$item->title}</span>
{/while $item = $item->getNext()}

{continueIf} {skipIf} {breakIf}

Pro řízení jakéhokoliv cyklu můžete použít značky {continueIf ?} a {breakIf ?}, které přejdou na další prvek resp. ukončí cyklus při splnění podmínky:

{foreach $rows as $row}
	{continueIf $row->date < $now}
	{breakIf $row->parent === null}
	...
{/foreach}

Značka {skipIf} je velmi podobná {continueIf}, ale nezvyšuje počítadlo $iterator->counter. Takže pokud vypisujete počítadlo a zároveň přeskočíte některé položky, nebudou v číslování mezery. A také klauzule {else} se vykreslí, když přeskočíte všechny položky.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Litujeme, v tomto seznamu nejsou žádní dospělí</em></li>
	{/foreach}
</ul>

{exitIf}

Ukončí vykreslování šablony nebo bloku při splnění podmínky (tzv. „early exit“).

{exitIf !$messages}

<h1>Zprávy</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

Vložení šablony

{include 'file.latte'}

Viz také {include block}

Značka {include} načte a vykreslí uvedenou šablonu. V PHP bychom to přirovnali k:

<?php include 'header.phtml'; ?>

Vložené šablony nemají přístup k proměnným aktivního kontextu, mají přístup jen ke globálním proměnným.

Proměnné do vložené šablony můžete předávat takto:

{include 'template.latte', foo: 'bar', id: 123}

Název šablony může být jakýkoliv výraz v PHP:

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

Vložený obsah lze upravit pomocí filtrů. Následující příklad odstraní veškeré HTML a upraví velikost písmen:

<title>{include 'heading.latte' |stripHtml|capitalize}</title>

Ve výchozím nastavení dědičnost šablon v tomto případě nehraje roli. I když v inkludované šabloně můžeme používat bloky, nedojde k nahrazení odpovídajících bloků v šabloně, do které se inkluduje. Inkludované šablony považujte za samostatné odstíněné části stránek nebo modulů. Toto chování můžete změnit pomocí modifikátoru with blocks:

{include 'template.latte' with blocks}

Vztah mezi názvem souboru uvedeným ve značce a souborem na disku je záležitostí loaderu.

{sandbox}

Při vkládání šablony vytvořené koncovým uživatelem byste měli zvážit sandbox režim (více informací v dokumentaci sandboxu):

{sandbox 'untrusted.latte', level: 3, data: $menu}

{block}

Viz také {block name}

Anonymní bloky slouží jako způsob, jak aplikovat filtry na část šablony. Například takto můžete použít filtr strip, který odstraní zbytečné mezery:

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

Řízení výjimek

{try}

Díky této značce je extrémně snadné vytvářet robustní šablony.

Pokud při vykreslování bloku {try} dojde k výjimce, celý blok se zahodí a vykreslování bude pokračovat za ním:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

Volitelná klauzule {else} se vykreslí jen když nastane výjimka:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Je nám líto, nepodařilo se načíst tweety.</p>
{/try}

Značku lze také použít jako n:attribut:

<ul n:try>
	...
</ul>

Je také možné definovat vlastní obslužný handler pro výjimky, například kvůli logování.

{rollback}

Blok {try} lze zastavit a přeskočit také ručně pomocí {rollback}. Díky tomu nemusíte předem kontrolovat všechna vstupní data a až během vykreslování se můžete rozhodnout, že objekt nechcete vůbec vykreslit:

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

Proměnné

{var} {default}

Nové proměnné vytvoříme v šabloně značkou {var}:

{var $name = 'John Smith'}
{var $age = 27}

{* Vícenásobná deklarace *}
{var $name = 'John Smith', $age = 27}

Značka {default} funguje podobně, ale vytváří proměnné jen tehdy, pokud neexistují. Pokud proměnná již existuje a obsahuje hodnotu null, nebude přepsána:

{default $lang = 'cs'}

Můžete uvádět i typy proměnných. Zatím jsou informativní a Latte je nekontroluje.

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

Podobně jako funkce deklaruje své parametry, může i šablona na začátku deklarovat své proměnné:

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

Proměnné $a a $b bez uvedené výchozí hodnoty mají automaticky výchozí hodnotu null. Deklarované typy jsou zatím informativní a Latte je nekontroluje.

Jiné proměnné než deklarované se do šablony nepřenášejí. Tím se liší od značky {default}.

{capture}

Zachytí výstup do proměnné:

{capture $var}
<ul>
	<li>Hello World</li>
</ul>
{/capture}

<p>Captured: {$var}</p>

Značku lze, podobně jako každou párovou značku, zapsat také jako n:attribut:

<ul n:capture="$var">
	<li>Hello World</li>
</ul>

HTML výstup se do proměnné $var uloží v podobě objektu Latte\Runtime\Html, aby nedošlo k nežádoucímu escapování při vypsání.

Ostatní

{contentType}

Značka určuje, jaký typ obsahu šablona představuje. Možnosti jsou:

• html (výchozí typ)
• xml
• javascript
• css
• calendar (iCal)
• text

Její použití je důležité, protože nastaví kontextově sensitivní escapování a jen tak může escapovat správně. Například {contentType xml} přepne do režimu XML, {contentType text} escapování zcela vypne.

Pokud je parametrem plnohodnotný MIME type, jako například application/xml, tak navíc odešle HTTP hlavičku Content-Type do prohlížeče:

{contentType application/xml}
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
		<title>RSS feed</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

Označuje místo, kde dojde k pozastavení běhu programu a spuštění debuggeru, aby mohl programátor provést inspekci běhového prostředí a zjistit, zda program funguje podle očekávání. Podporuje Xdebug. Lze doplnit podmínku, která určuje, kdy má být program pozastaven.

{debugbreak}                {* pozastaví program *}

{debugbreak $counter == 1}  {* pozastaví program při splnění podmínky *}

{do}

Vykoná PHP kód a nic nevypisuje. Stejně jako u všech dalších značek se PHP kódem rozumí jeden výraz, viz omezení PHP.

{do $num++}

{dump}

Vypíše proměnnou nebo aktuální kontext.

{dump $name} {* Vypíše proměnnou $name *}

{dump}       {* Vypíše všechny aktuálně definované proměnné *}

Vyžaduje knihovnu Tracy.

{php}

Umožňuje vykonat jakýkoliv PHP kód. Značku je nutné aktivovat pomocí rozšíření RawPhpExtension.

{spaceless}

Odstraní zbytečné bílé místo z výstupu. Funguje podobně jako filtr spaceless.

{spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/spaceless}

Vygeneruje:

<ul> <li>Hello</li> </ul>

Značku lze také zapsat jako n:attribut.

{syntax}

Latte značky nemusejí být ohraničeny pouze jednoduchými složenými závorkami. Můžete si zvolit i jiný oddělovač a to dokonce za běhu. Slouží k tomu {syntax …}, kde jako parametr lze uvést:

• double: {{...}}
• off: zcela vypne zpracování Latte značek

S využitím n:atributů lze vypnout Latte třeba jen jednomu bloku JavaScriptu:

<script n:syntax="off">
	var obj = {var: 123}; // tohle už není tag
</script>

Latte lze velmi pohodlně používat i uvnitř JavaScriptu, jen se stačí vyhnout konstrukcím jako v tomto příkladě, kdy následuje písmeno hned za {, viz Latte uvnitř JavaScriptu nebo CSS.

Pokud Latte vypnete pomocí {syntax off} (tj. značkou, nikoliv n:atributem), bude důsledně ignorovat všechny značky až do {/syntax}.

{trace}

Vyhodí výjimku Latte\RuntimeException, jejíž stack trace se nese v duchu šablon. Tedy místo volání funkcí a metod obsahuje volání bloků a vkládání šablon. Pokud používáte nástroj pro přehledné zobrazení vyhozených výjimek, jako je například Tracy, přehledně se vám zobrazí call stack včetně všech předávaných argumentů.

Pomocníci HTML kodéra

n:class

Díky n:class velice snadno vygenerujete HTML atribut class přesně podle představ.

Příklad: potřebujeme, aby aktivní prvek měl třídu active:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

A dále, aby první prvek měl třídy first a main:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main'">...</a>
{/foreach}

A všechny prvky mají mít třídu list-item:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main', list-item">...</a>
{/foreach}

Úžasně jednoduché, že?

n:attr

Atribut n:attr umí se stejnou elegancí jako n:class generovat libovolné HTML atributy.

{foreach $data as $item}
	<input type="checkbox" n:attr="value: $item->getValue(), checked: $item->isActive()">
{/foreach}

V závislosti na vrácených hodnotách vypíše např.:

<input type="checkbox">

<input type="checkbox" value="Hello">

<input type="checkbox" value="Hello" checked>

n:tag

Atribut n:tag umí dynamicky měnit název HTML elementu.

<h1 n:tag="$heading" class="main">{$title}</h1>

Pokud je $heading === null, vypíše se beze změny tag <h1>. Jinak se změní název elementu na hodnotu proměnné, takže pro $heading === 'h3' se vypíše:

<h3 class="main">...</h3>

Protože Latte je bezpečný šablonovací systém, kontroluje, zda je nový název značky platný a neobsahuje žádné nežádoucí nebo škodlivé hodnoty.

n:ifcontent

Předchází tomu, aby se vypsal prázdný HTML element, tj. element neobsahující nic než mezery.

<div>
	<div class="error" n:ifcontent>{$error}</div>
</div>

Vypíše v závislosti na hodnotě proměnné $error:

{* $error = '' *}
<div>
</div>

{* $error = 'Required' *}
<div>
	<div class="error">Required</div>
</div>

Překlady

Aby značky pro překlad fungovaly, je potřeba aktivovat překladač. Pro překlad můžete také použít filtr translate.

{_...}

Překládá hodnoty do jiných jazyků.

<a href="basket">{_'Košík'}</a>
<span>{_$item}</span>

Překladači lze předávat i další parametry:

<a href="basket">{_'Košík', domain: order}</a>

{translate}

Překládá části šablony:

<h1>{translate}Objednávka{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

Značku lze také zapsat jako n:attribut, pro překlad vnitřku elementu:

<h1 n:translate>Objednávka</h1>