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.
capitalize |
malá písmena, první písmeno ve slovech velké |
firstUpper |
převede první písmeno na velké |
lower |
převede na malá písmena |
upper |
převede na velká písmena |
ceil |
zaokrouhlí číslo nahoru na danou přesnost |
floor |
zaokrouhlí číslo dolů na danou přesnost |
round |
zaokrouhlí číslo na danou přesnost |
escapeUrl |
escapuje parametr v URL |
noescape |
vypíše proměnnou bez escapování |
query |
generuje query string v URL |
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.
checkUrl |
ošetří URL adresu od nebezpečných vstupů |
nocheck |
předejde automatickému ošetření URL adresy |
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 & with <br>\n newline" *}
bytes (int precision = 2)
Formátuje velikost v bajtech do lidsky čitelné podoby.
{$size|bytes} 0 B, 10 B, …
{$size|bytes:2} 1.25 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 *}
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 podle masky buď ve tvaru používaném PHP funkcí strftime nebo date. Filtr přijímá datum buď ve formátu UNIX timestamp, v podobě řetězce nebo jako
objekt DateTime
.
{$today|date:'%d.%m.%Y'}
{$today|date:'j. n. Y'}
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' *}
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 *}
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' *}
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}
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. Lze určit znak pro desetinnou čárku a oddělovač 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
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&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' *}
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 *}
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 slouží k seřazení prvků v poli nebo iterátoru, přičemž zachovává asociační klíče:
{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 < 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 (string message, …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.