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.

Transformace
batch výpis lineárních dat do tabulky
breakLines Před konce řádku přidá HTML odřádkování
bytes formátuje velikost v bajtech
clamp ohraničí hodnotu do daného rozsahu
dataStream konverze pro Data URI protokol
date formátuje datum
explode rozdělí řetězec na pole podle oddělovače
first vrací první prvek pole nebo znak řetězce
implode spojí pole do řetězce
indent odsadí text zleva o daný počet tabulátorů
join spojí pole do řetězce
last vrací poslední prvek pole nebo znak řetězce
length vrací délku řetězce ve znacích nebo pole
number formátuje číslo
padLeft doplní řetězec zleva na požadovanou délku
padRight doplní řetězec zprava na požadovanou délku
random vrací náhodný prvek pole nebo znak řetězce
repeat opakování řetězce
replace zamění výskyty hledaného řetězce
replaceRE zamění výskyty dle regulárního výrazu
reverse obrátí UTF‑8 řetězec nebo pole
slice extrahuje část pole nebo řetězce
sort seřadí pole
spaceless odstraní bílé místo, podobně jako značka spaceless tag
split rozdělí řetězec na pole podle oddělovače
strip odstraní bílé místo
stripHtml odstraní HTML značky a HTML entity převede na znaky
substr vrátí část řetězce
trim odstraní počáteční a koncové mezery či jiné znaky
truncate zkrátí délku se zachováním slov
webalize upraví UTF‑8 řetězec do tvaru používaného v URL
Velikost písmen
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
Zaokrouhlování
ceil zaokrouhlí číslo nahoru na danou přesnost
floor zaokrouhlí číslo dolů na danou přesnost
round zaokrouhlí číslo na danou přesnost
Escapování
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.

Bezpečnost
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>

Jako filtr lze do šablony zaregistrovat libovolný callback:

$latte = new Latte\Engine;
$latte->addFilter('shortify', function (string $s, int $len = 10): string {
	return 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>

vygeneruje:

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

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.

{$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 *}

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>

Vygeneruje:

<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}">

Vygeneruje 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' *}

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.

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>

Vygeneruje

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

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>

Vygeneruje:

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

Viz také checkUrl.

noescape

Zakáže automatické escapování.

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>

Vygeneruje:

<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}           {* outputs 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* outputs ['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

Filtr, který seřadí pole. Zachovává asociaci s klíčí.

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

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

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

Jako parametr lze předat vlastní porovnávací funkci:

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

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}

Vygeneruje

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

stripHtml

Odstraní značky HTML a převede entity HTML na text.

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

substr (int offset, int length = null)

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

{$string|substr: 1, 2}

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.