Latte filtry

Filtry v šablonách Latte pomáhají upravit nebo přeformátovat data do požadované podoby

Latte automaticky používá escapovací filtry pro HTML (escapeHtml a escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) a iCalendar (escapeICal) díky kontextově sensitivnímu escapování. Tyto filtry není třeba explicitně zapisovat.

Všechny výchozí filtry jsou navrženy pro práci s řetězci v kódování UTF-8.

Použití

Filtry se aplikují pomocí svislítka za proměnnou nebo výrazem:

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

Filtry lze řetězit, v takovém případě se aplikují zleva doprava:

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

Parametry filtrů se zadávají za dvojtečkou:

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

Filtry lze použít i na výrazy:

{var $name = ($title|upper) . ($subtitle|lower)}

Vlastní filtry se registrují následovně:

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

V šabloně se pak volají stejně jako vestavěné filtry:

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

Filtry

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

Filtr batch usnadňuje výpis lineárních dat do tabulkové struktury. Vrací pole polí s požadovaným počtem položek. Pokud zadáte druhý parametr, použije se k doplnění chybějících položek v 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>

Výstup:

<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

Filtr breakLines vkládá HTML značku <br> před každý znak nového řádku.

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

bytes (int $precision=2)

Filtr bytes formátuje velikost v bajtech do lidsky čitelné podoby. Pokud je nastaveno 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, …

Viz také number.

ceil (int $precision=0)

Filtr ceil 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

Filtr capitalize upraví text tak, že první písmeno každého slova bude velké a zbývající malá. Vyžaduje PHP rozšíření mbstring.

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

Viz také firstUpper, lower, upper.

checkUrl

Filtr checkUrl zajistí kontrolu a případné ošetření URL adresy. Ověří, zda proměnná obsahuje webovou URL (tj. protokol HTTP/HTTPS) a zabrání vypsání odkazů, které by mohly představovat bezpečnostní riziko.

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

Výstup:

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

Latte automaticky kontroluje atributy src a href, takže filtr checkUrl většinou není nutné explicitně uvádět.

Viz také nocheck.

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

Filtr clamp omezí hodnotu do zadaného inkluzivního rozsahu min a max.

{$level|clamp: 0, 255}

K dispozici je také jako funkce.

dataStream (string $mimetype=detect)

Filtr dataStream konvertuje obsah do schématu data URI. To umožňuje vkládat obrázky přímo do HTML nebo CSS bez nutnosti odkazovat na externí soubory.

Pokud máme v proměnné obrázek $img = Image::fromFile('obrazek.gif'), potom

<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)

Filtr date formátuje datum a čas podle zadané masky, kterou používá PHP funkce date. Filtr akceptuje datum ve formátu UNIX timestamp, jako řetězec nebo objekt typu DateTimeInterface.

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

Viz také localDate.

escapeUrl

Filtr escapeUrl escapuje proměnnou pro bezpečné použití jako parametr v URL.

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

Viz také query.

explode (string $separator='')

Filtr explode rozdělí řetězec na pole podle zadaného oddělovače. Je to alias pro split.

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

Pokud je oddělovač prázdný řetězec (výchozí hodnota), vstup se rozdělí 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

Filtr first vrací první prvek pole nebo první znak řetězce:

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

Viz také last, random.

floor (int $precision=0)

Filtr floor 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

Filtr 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 group umožňuje seskupit 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='')

Filtr implode spojí prvky pole do řetězce. Je to 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")

Filtr indent odsadí text zleva o zadaný počet tabulátorů nebo jiných znaků. Prázdné řádky nejsou odsazeny.

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

Výstup:

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

last

Filtr last vrací poslední prvek pole nebo poslední znak řetězce:

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

Viz také first, random.

length

Filtr length vrátí délku řetězce nebo počet prvků v poli.

• pro řetězce vrátí počet unicode znaků
• pro pole vrátí počet prvků
• pro objekty implementující rozhraní Countable použije návratovou hodnotu metody count()
• pro objekty implementující 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)

Filtr localDate formátuje datum a čas podle národního prostředí. To 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 *}

Bez parametrů se datum vypíše v úrovni long (viz dále).

a) použití formátu

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

Pořadí kódů ve formátu nemá vliv na pořadí složek ve výstupu, protože to se řídí zvyklostmi národního prostředí. Formát je tedy na něm nezávislý. Například formát yyyyMMMMd v prostř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í úroveň podrobnosti pro výpis data a času. K dispozici jsou úrovně: full, long, medium, short. Můžete nechat vypsat jen datum, jen čas, nebo obojí:

Pro datum lze 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

Filtr 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

Filtr nocheck vypne automatickou kontrolu URL adresy. Latte standardně kontroluje, zda proměnná obsahuje webovou URL (tj. protokol HTTP/HTTPS) a brání vypsání potenciálně nebezpečných odkazů.

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

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

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

Výstup:

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

Viz také checkUrl.

noescape

Filtr noescape vypne automatické escapování.

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

Výstup:

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

Nesprávné použití filtru noescape může vést ke zranitelnosti XSS! Používejte jej pouze tehdy, když si jste naprosto jisti, že vypisovaný řetězec pochází z důvěryhodného zdroje.

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

Filtr number formátuje číslo na zadaný počet desetinných míst. Pokud je nastaveno 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 přesně definovat vzhled čísel podle vašich potřeb. K tomu je nutné 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 pozici desetinné čárky (nebo tečky, podle země)
• , slouží k oddělení skupin číslic, nejčastěji tisíců
• % číslo vynásobí 100× a přidá znak procenta

Podívejme se 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 desetinnou čárku má být zobrazeno, přičemž dochází k zaokrouhlování:

{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ělené znakem ;. 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 *}

Nezapomeňte, ž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í, takže se o to nemusíte starat.

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

Filtr padLeft doplní řetězec zleva na požadovanou délku jiným řetězcem.

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

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

Filtr padRight doplní řetězec zprava na požadovanou délku jiným řetězcem.

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

query

Filtr query dynamicky generuje query string v URL:

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

Výstup:

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

Klíče s hodnotou null se vynechají.

Viz také escapeUrl.

random

Filtr random vrací náhodný prvek pole nebo náhodný 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)

Filtr repeat opakuje řetězec zadaný počet krát.

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

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

Filtr replace nahradí všechny výskyty hledané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='')

Filtr replaceRE provádí nahrazování podle regulárních výrazů.

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

reverse

Filtr reverse obrátí pořadí znaků v řetězci nebo prvků v poli.

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

round (int $precision=0)

Filtr round zaokrouhlí číslo na zadanou 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)

Filtr slice extrahuje část pole nebo řetězce.

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

Tento 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/řetězce. Pokud je záporný, posloupnost začíná posunutá o tolik od konce.

Pokud je zadán 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čící na pozici menší o length prvků od konce pole. Pokud tento parametr nezadáte, posloupnost bude obsahovat všechny prvky původního pole, začínající pozicí start.

Ve výchozím nastavení filtr změní pořadí a resetuje celočíselné 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 sort 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}

Pro ř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 objekt nebo pole:

{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($item) => $item->category->name) as $item}
	{$item->name}
{/foreach}

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

spaceless

Filtr spaceless odstraní nadbytečné bílé znaky z výstupu. Můžete také použít alias strip.

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

Výstup:

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

stripHtml

Filtr stripHtml převádí HTML na čistý text. Odstraní HTML značky a převede HTML entity na jejich textovou reprezentaci.

{='<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)

Filtr substr extrahuje část řetězce. Tento filtr byl nahrazen filtrem slice.

{$string|substr: 1, 2}

translate (string $message, …$args)

Filtr translate 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}")

Filtr trim odstraní bílé znaky (nebo jiné zadané 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='…')

Filtr truncate zkrátí ř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

Filtr 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

Filtr webalize upraví UTF-8 řetězec do tvaru používaného v URL.

Převádí znaky na ASCII ekvivalenty. Převádí mezery na pomlčky. Odstraní znaky, které nejsou alfanumerické, podtržítka ani pomlčky. Převádí text na malá písmena. Také odstraní úvodní a koncové bílé znaky.

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

Vyžaduje knihovnu nette/utils.