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
implode spojí pole do řetězce
indent odsadí text zleva o daný počet tabulátorů
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
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
sort seřadí pole
strip odstraní bílé místo, podobně jako značka spaceless
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
Escapování
escapeUrl escapuje parametr v URL
noescape vypíše proměnnou bez escapování

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

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:

{=clamp($level, 0, 255)}

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

implode (string glue = '')

Vrátí řetězec, který je zřetězením položek sekvence. Oddělovač mezi prvky je ve výchozím nastavení prázdný řetězec, ale můžete jej definovat pomocí volitelného prvního parametru.

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

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>

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}

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

repeat (int count)

Opakuje řetězec x-krát.

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

replace (string 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' *}

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

sort

Filtr, který třídí pole.

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

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

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

strip

Odstraní zbytečné bílé místo (mezery) z výstupu.

{block |strip}
	<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. Funguje jako funkce PHP mb_substr s fallbackem k iconv_substr v režimu UTF‑8.

{$string|substr: 1, 2}

trim

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

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.

Velikost písmen

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

capitalize

Slova budou začínat velkými písmeny, všechny zbývající znaky budou malá.

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

firstUpper

Převede první písmeno na velká.

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

lower

Převede řetězec na malá písmena.

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

upper

Převede řetězec na velká písmena.

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

Escapování

escapeUrl

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

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

noescape

Zakáže automatické escapování.

Bezpečnost

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>

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>
Vylepšit tuto stránku