Latte filtry

V šablonách můžeme používat funkce, které pomáhají upravit nebo přeformátovat data do výsledné podoby. Říkáme jim filtry.

Dále existují escapovací filtry pro HTML (escapeHtml a escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) a iCalendar (escapeICal), které Latte používá samo díky kontextově sensitivnímu escapování a nemusíte je zapisovat.

Latte atributy src a href kontroluje automaticky, takže filtr checkUrl téměř nemusíte používat.

Všechny výchozí filtry jsou určeny pro řetězce v kódování UTF‑8.

Použití

Filtry se zapisují za svislítko (může být před ním mezera):

<h1>{$heading|upper}</h1>

Filtry (ve starších verzích helpery) lze zřetězit a poté se aplikují v pořadí od levého k pravému:

<h1>{$heading|lower|capitalize}</h1>

Parametry se zadávají za jménem filtru oddělené dvojtečkami nebo čárkami:

<h1>{$heading|truncate:20,''}</h1>

Filtry lze aplikovat i na výraz:

{var $name = ($title|upper) . ($subtitle|lower)}</h1>

Vlastní filtry lze registrovat tímto způsobem:

$latte = new Latte\Engine;
$latte->addFilter('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));

V šabloně se potom volá takto:

<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>

Filtry

batch (int $length, mixed $item): array

Filtr, který zjednodušuje výpis lineárních dat do podoby tabulky. Vrací pole polí se zadaným počtem položek. Pokud zadáte druhý parametr, použije se k doplnění chybějících položek na posledním řádku.

{var $items = ['a', 'b', 'c', 'd', 'e']}
<table>
{foreach ($items|batch: 3, 'No item') as $row}
	<tr>
		{foreach $row as $column}
			<td>{$column}</td>
		{/foreach}
	</tr>
{/foreach}
</table>

Vypíše:

<table>
	<tr>
		<td>a</td>
		<td>b</td>
		<td>c</td>
	</tr>
	<tr>
		<td>d</td>
		<td>e</td>
		<td>No item</td>
	</tr>
</table>

Viz také group a značka iterateWhile.

breakLines

Přidává před každý znak nového řádku HTML značku <br>

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* vypíše "Text &amp; with <br>\n newline" *}

bytes (int $precision=2)

Formátuje velikost v bajtech do lidsky čitelné podoby. Pokud je nastavené národní prostředí, použijí se odpovídající oddělovače desetinných míst a tisíců.

{$size|bytes}     0 B, 1.25 GB, …
{$size|bytes:0}   10 B, 1 GB, …

ceil (int $precision=0)

Zaokrouhlí číslo nahoru na danou přesnost.

{=3.4|ceil}         {* vypíše 4      *}
{=135.22|ceil:1}    {* vypíše 135.3  *}
{=135.22|ceil:3}    {* vypíše 135.22 *}

Viz také floor, round.

capitalize

Slova budou začínat velkými písmeny, všechny zbývající znaky budou malá. Vyžaduje PHP rozšíření mbstring.

{='i like LATTE'|capitalize}  {* vypíše 'I Like Latte' *}

Viz také firstUpper, lower, upper.

checkUrl

Vynutí ošetření URL adresy. Kontroluje, zda proměnná obsahuje webovou URL (tj. protokol HTTP/HTTPS) a předchází vypsání odkazů, které mohou představovat bezpečnostní riziko.

{var $link = 'javascript:window.close()'}
<a data-href={$link|checkUrl}>kontrolované</a>
<a data-href={$link}>nekontrolované</a>

Vypíše:

<a data-href="">kontrolované</a>
<a data-href="javascript:window.close()">nekontrolované</a>

Viz také nocheck.

clamp (int|float $min, int|float $max)

Ohraničí hodnotu do daného inkluzivního rozsahu min a max.

{$level|clamp: 0, 255}

Existuje také jako funkce.

dataStream (string $mimetype=detect)

Konvertuje obsah do data URI scheme. Pomocí něj lze do HTML nebo CSS vkládat obrázky bez nutnosti linkovat externí soubory.

Mějme v proměnné obrázek $img = Image::fromFile('obrazek.gif'), poté

<img src={$img|dataStream}>

Vypíše například:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA
AAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO
9TXL0Y4OHwAAAABJRU5ErkJggg==">

Vyžaduje PHP rozšíření fileinfo.

date (string $format)

Formátuje datum a čas podle masky používané PHP funkcí date. Filtr přijímá datum ve formátu UNIX timestamp, jako řetězec nebo objekt typu DateTimeInterface.

{$today|date:'j. n. Y'}

Viz také localDate.

escapeUrl

Escapuje proměnnou pro použití jakožto parametru v URL.

<a href="http://example.com/{$name|escapeUrl}">{$name}</a>

Viz také query.

explode (string $separator='')

Rozdělí řetězec na pole podle oddělovače. Alias pro split.

{='one,two,three'|explode:','}    {* vrací ['one', 'two', 'three'] *}

Pokud je oddělovač prázdný řetězec (výchozí hodnota), bude vstup rozdělen na jednotlivé znaky:

{='123'|explode}                  {* vrací ['1', '2', '3'] *}

Můžete také použít alias split:

{='1,2,3'|split:','}              {* vrací ['1', '2', '3'] *}

Viz také implode.

first

Vrací první prvek pole nebo znak řetězce:

{=[1, 2, 3, 4]|first}    {* vypíše 1 *}
{='abcd'|first}          {* vypíše 'a' *}

Viz také last, random.

floor (int $precision=0)

Zaokrouhlí číslo dolů na danou přesnost.

{=3.5|floor}        {* vypíše 3      *}
{=135.79|floor:1}   {* vypíše 135.7  *}
{=135.79|floor:3}   {* vypíše 135.79 *}

Viz také ceil, round.

firstUpper

Převede první písmeno na velká. Vyžaduje PHP rozšíření mbstring.

{='the latte'|firstUpper}  {* vypíše 'The latte' *}

Viz také capitalize, lower, upper.

group (string|int|\Closure $by): array

Filtr seskupí data podle různých kritérií.

V tomto příkladu se řádky v tabulce seskupují podle sloupce categoryId. Výstupem je pole polí, kde klíčem je hodnota ve sloupci categoryId. Přečtěte si podrobný návod.

{foreach ($items|group: categoryId) as $categoryId => $categoryItems}
    <ul>
        {foreach $categoryItems as $item}
            <li>{$item->name}</li>
        {/foreach}
    </ul>
{/foreach}

Viz také batch, funkce group a značka iterateWhile.

implode (string $glue='')

Vrátí řetězec, který je zřetězením položek sekvence. Alias pro join.

{=[1, 2, 3]|implode}      {* vypíše '123' *}
{=[1, 2, 3]|implode:'|'}  {* vypíše '1|2|3' *}

Můžete také použít alias join:

{=[1, 2, 3]|join}         {* vypíše '123' *}

indent (int $level=1, string $char="\t")

Odsadí text zleva o daný počet tabulátorů nebo jiných znaků, které můžeme uvést ve druhém argumentu. Prázdné řádky nejsou odsazeny.

<div>
{block |indent}
<p>Hello</p>
{/block}
</div>

Vypíše:

<div>
	<p>Hello</p>
</div>

last

Vrací poslední prvek pole nebo znak řetězce:

{=[1, 2, 3, 4]|last}    {* vypíše 4 *}
{='abcd'|last}          {* vypíše 'd' *}

Viz také first, random.

length

Vrátí délku řetězce nebo pole.

• pro řetězce vrátí délku v UTF‑8 znacích
• pro pole vrátí počet položek
• pro objekty, které implementují rozhraní Countable, použije návratovou hodnotu metody count()
• pro objekty, které implementují rozhraní IteratorAggregate, použije návratovou hodnotu funkce iterator_count()

{if ($users|length) > 10}
	...
{/if}

localDate (?string $format=null, ?string $date=null, ?string $time=null)

Formátuje datum a čas podle národního prostředí, což zajišťuje konzistentní a lokalizované zobrazení časových údajů napříč různými jazyky a regiony. Filtr přijímá datum jako UNIX timestamp, řetězec nebo objekt typu DateTimeInterface.

{$date|localDate}                  {* 15. dubna 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

Pokud použijete filtr bez parametrů, vypíše se datum v úrovní long, viz dále.

a) použití formátu

Parametr format popisuje, které časové složky se mají zobrazit. Používá pro ně písmenné kódy, jejichž počet opakování ovlivňuje šířku výstupu:

Na pořadí kódů ve formátu nezáleží, protože pořadí složek se vypíše podle zvyklostí národního prostředí. Formát je tedy na něm nezávislý. Například formát yyyyMMMMd v postředí en_US vypíše April 15, 2024, zatímco v prostředí cs_CZ vypíše 15. dubna 2024:

b) použití přednastavených stylů

Parametry date a time určují, jak podrobně se má datum a čas vypsat. Můžete si vybrat z několika úrovní: full, long, medium, short. Lze nechat vypsat jen datum, jen čas, nebo obojí:

U data lze navíc použít prefix relative- (např. relative-short), který pro data blízká současnosti zobrazí včera, dnes nebo zítra, jinak se vypíše standardním způsobem.

{$date|localDate: date: relative-short}    {* včera *}

Viz také date.

lower

Převede řetězec na malá písmena. Vyžaduje PHP rozšíření mbstring.

{='LATTE'|lower}   {* vypíše 'latte' *}

Viz také capitalize, firstUpper, upper.

nocheck

Předejde automatickému ošetření URL adresy. Latte automaticky kontroluje, zda proměnná obsahuje webovou URL (tj. protokol HTTP/HTTPS) a předchází vypsání odkazů, které mohou představovat bezpečnostní riziko.

Pokud odkaz používá jiné schéma, např. javascript: nebo data:, a jste si jistí jeho obsahem, můžete kontrolu vypnout pomoci |nocheck.

{var $link = 'javascript:window.close()'}

<a href={$link}>kontrolované</a>
<a href={$link|nocheck}>nekontrolované</a>

Vypíše:

<a href="">kontrolované</a>
<a href="javascript:window.close()">nekontrolované</a>

Viz také checkUrl.

noescape

Zakáže automatické escapování.

{var $trustedHtmlString = '<b>hello</b>'}
Escapovaný: {$trustedHtmlString}
Neescapovaný: {$trustedHtmlString|noescape}

Vypíše:

Escapovaný: <b>hello</b>
Neescapovaný: <b>hello</b>

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

number (int $decimals=0, string $decPoint='.', string $thousandsSep=',')

Formátuje číslo na určitý počet desetinných míst. Pokud je nastavené národní prostředí, použijí se odpovídající oddělovače desetinných míst a tisíců.

{1234.20|number}              1,234
{1234.20|number:1}            1,234.2
{1234.20|number:2}            1,234.20
{1234.20|number:2, ',', ' '}  1 234,20

number (string $format)

Parametr format umožňuje definovat vzhled čísel přesně podle vašich potřeb. K tomu je potřeba mít nastavené národní prostředí. Formát se skládá z několika speciálních znaků, jejichž kompletní popis najdete v dokumentaci DecimalFormat:

• 0 povinná číslice, vždy se zobrazí, i kdyby to byla nula
• # volitelná číslice, zobrazí se jen tehdy, pokud na tomto místě číslo skutečně je
• @ významná číslice, pomáhá zobrazit číslo s určitým počtem platných číslic
• . označuje, kde má být desetinná čárka (nebo tečka, podle země)
• , slouží k oddělení skupin číslic, nejčastěji tisíců
• % číslo vynásobí 100× a přidá znak procenta

Pojďme se podívat na příklady. V prvním příkladu jsou dvě desetinná místa povinná, ve druhém volitelná. Třetí příklad ukazuje doplnění nulami zleva i zprava, čtvrtý zobrazuje jen existující číslice:

{1234.5|number: '#,##0.00'}     {* 1,234.50 *}
{1234.5|number: '#,##0.##'}     {* 1,234.5 *}
{1.23  |number: '000.000'}      {* 001.230 *}
{1.2   |number: '##.##'}        {* 1.2 *}

Významné číslice určují, kolik číslic bez ohledu na desetinou čárku má být zobrazeno, přičemž se zaokrouhluje:

{1234|number: '@@'}             {* 1200 *}
{1234|number: '@@@'}            {* 1230 *}
{1234|number: '@@@#'}           {* 1234 *}
{1.2345|number: '@@@'}          {* 1.23 *}
{0.00123|number: '@@'}          {* 0.0012 *}

Snadný způsob, jak zobrazit číslo jako procenta. Číslo se vynásobí 100× a přidá se znak %:

{0.1234|number: '#.##%'}        {* 12.34% *}

Můžeme definovat odlišný formát pro kladná a záporná čísla, odděluje je znak ;. Tímto způsobem lze například nastavit, že kladná čísla se mají zobrazovat se znaménkem +:

{42|number: '#.##;(#.##)'}      {* 42 *}
{-42|number: '#.##;(#.##)'}     {* (42) *}
{42|number: '+#.##;-#.##'}      {* +42 *}
{-42|number: '+#.##;-#.##'}     {* -42 *}

Pamatujte, že skutečný vzhled čísel se může lišit podle nastavení země. Například v některých zemích se používá čárka místo tečky jako oddělovač desetinných míst. Tento filtr to automaticky zohlední a nemusíte se o nic starat.

padLeft (int $length, string $pad=' ')

Doplní řetězec do určité délky jiným řetězcem zleva.

{='hello'|padLeft: 10, '123'}  {* vypíše '12312hello' *}

padRight (int $length, string $pad=' ')

Doplní řetězec do určité délky jiným řetězcem zprava.

{='hello'|padRight: 10, '123'}  {* vypíše 'hello12312' *}

query

Dynamicky generuje query string v URL:

<a href="http://example.com/?{[name: 'John Doe', age: 43]|query}">click</a>
<a href="http://example.com/?search={$search|query}">search</a>

Vypíše:

<a href="http://example.com/?name=John+Doe&amp;age=43">click</a>
<a href="http://example.com/?search=Foo+Bar">search</a>

Klíče s hodnotou null se vynechají.

Viz také escapeUrl.

random

Vrací náhodný prvek pole nebo znak řetězce:

{=[1, 2, 3, 4]|random}    {* vypíše např.: 3 *}
{='abcd'|random}          {* vypíše např.: 'b' *}

Viz také first, last.

repeat (int $count)

Opakuje řetězec x-krát.

{='hello'|repeat: 3}  {* vypíše 'hellohellohello' *}

replace (string|array $search, string $replace='')

Nahradí všechny výskyty vyhledávacího řetězce náhradním řetězcem.

{='hello world'|replace: 'world', 'friend'}  {* vypíše 'hello friend' *}

Lze provést i více záměn najednou:

{='hello world'|replace: [h => l, l => h]}  {* vypíše 'lehho worhd' *}

replaceRE (string $pattern, string $replace='')

Provede vyhledávání regulárních výrazů s nahrazením.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* vypíše 'hel' *}

reverse

Obrátí daný řetězec nebo pole.

{var $s = 'Nette'}
{$s|reverse}    {* vypíše 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* returns ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Zaokrouhlí číslo na danou přesnost.

{=3.4|round}        {* vypíše 3      *}
{=3.5|round}        {* vypíše 4      *}
{=135.79|round:1}   {* vypíše 135.8  *}
{=135.79|round:3}   {* vypíše 135.79 *}

Viz také ceil, floor.

slice (int $start, ?int $length=null, bool $preserveKeys=false)

Extrahuje část pole nebo řetězce.

{='hello'|slice: 1, 2}           {* vypíše 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* vypíše ['b', 'c'] *}

Filtr funguje jako funkce PHP array_slice pro pole nebo mb_substr pro řetězce s fallbackem na funkci iconv_substr v režimu UTF‑8.

Pokud je start kladný, posloupnost začné posunutá o tento počet od začátku pole/řetezce. Pokud je záporný posloupnost začné posunutá o tolik od konce.

Pokud je zadaný parametr length a je kladný, posloupnost bude obsahovat tolik prvků. Pokud je do této funkce předán záporný parametr length, posloupnost bude obsahovat všechny prvky původního pole, začínající na pozici start a končicí na pozici menší na length prvků od konce pole. Pokud tento parametr nezadáte, posloupnost bude obsahovat všechny prvky původního pole, začínající pozici start.

Ve výchozím nastavení filtr změní pořadí a resetuje celočíselného klíče pole. Toto chování lze změnit nastavením preserveKeys na true. Řetězcové klíče jsou vždy zachovány, bez ohledu na tento parametr.

sort (?Closure $comparison, string|int|\Closure|null $by=null, string|int|\Closure|bool $byKey=false)

Filtr seřadí prvky pole nebo iterátoru a zachová jejich asociační klíče. Při nastaveném národním prostředí se řazení řídí jeho pravidly, pokud není specifikována vlastní porovnávací funkce.

{foreach ($names|sort) as $name}
	...
{/foreach}

Řazené pole v opačném pořadí:

{foreach ($names|sort|reverse) as $name}
	...
{/foreach}

Můžete specifikovat vlastní porovnávací funkci pro řazení (příklad ukazuje, jak obrátit řazení od největší po nejmenší):

{var $reverted = ($names|sort: fn($a, $b) => $b <=> $a)}

Filtr |sort také umožňuje řadit prvky podle klíčů:

{foreach ($names|sort: byKey: true) as $name}
	...
{/foreach}

Pokud potřebujete seřadit tabulku podle konkrétního sloupce, můžete použít parametr by. Hodnota 'name' v ukázce určuje, že se bude řadit podle $item->name nebo $item['name'], v závislosti na tom, zda je $item pole nebo objekt:

{foreach ($items|sort: by: 'name') as $item}
	{$item->name}
{/foreach}

Můžete také definovat callback funkci, která určí hodnotu, podle které se má řadit:

{foreach ($items|sort: by: fn($items) => $items->category->name) as $item}
	{$item->name}
{/foreach}

Stejným způsobem lze využít i parametr byKey.

spaceless

Odstraní zbytečné bílé místo (mezery) z výstupu. Můžete také použít alias strip.

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

Vypíše:

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

stripHtml

Převádí HTML na čistý text. Tedy odstraní z něj HTML značky a HTML entity převede na text.

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

Výsledný čistý text může přirozeně obsahovat znaky, které představují HTML značky, například '<p>'|stripHtml se převede na <p>. V žádném případě nevypisujte takto vzniklý text s |noescape, protože to může vést ke vzniku bezpečnostní díry.

substr (int $offset, ?int $length=null)

Extrahuje část řetězce. Tento filtr byl nahrazen filtrem slice.

{$string|substr: 1, 2}

translate (…$args)

Překládá výrazy do jiných jazyků. Aby byl filtr k dispozici, je potřeba nastavit překladač. Můžete také použít tagy pro překlad.

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

trim (string $charlist=" \t\n\r\0\x0B\u{A0}")

Odstraní prázdné znaky (nebo jiné znaky) od začátku a konce řetězce.

{='  I like Latte.  '|trim}    {* vypíše 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* vypíše '  I like Latte' *}

truncate (int $length, string $append='…')

Ořízne řetězec na uvedenou maximální délku, přičemž se snaží zachovávat celá slova. Pokud dojde ke zkrácení řetězce, přidá nakonec trojtečku (lze změnit druhým parametrem).

{var $title = 'Hello, how are you?'}
{$title|truncate:5}  {* Hell…                *}
{$title|truncate:17} {* Hello, how are…      *}
{$title|truncate:30} {* Hello, how are you?  *}

upper

Převede řetězec na velká písmena. Vyžaduje PHP rozšíření mbstring.

{='latte'|upper}  {* vypíše 'LATTE' *}

Viz také capitalize, firstUpper, lower.

webalize

Upraví UTF‑8 řetězec do tvaru používaného v URL.

Převádí se na ASCII. Převede mezery na pomlčky. Odstraní znaky, které nejsou alfanumerické, podtržítka ani pomlčky. Převede na malá písmena. Také odstraní přední a koncové mezery.

{var $s = 'Náš 10. produkt'}
{$s|webalize}   {* vypíše 'nas-10-produkt' *}

Vyžaduje knihovnu nette/utils.