Filtry Latte

W szablonach możemy używać funkcji, które pomagają modyfikować lub przeformatować dane do ostatecznej postaci. Nazywamy je filtrami.

Ponadto istnieją filtry escapujące dla HTML (escapeHtml i escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) i iCalendar (escapeICal), których Latte używa samo dzięki escapowaniu kontekstowemu i nie trzeba ich zapisywać.

Latte sprawdza automatycznie atrybuty src i href, więc filtra checkUrl prawie nie trzeba używać.

Wszystkie domyślne filtry są przeznaczone dla ciągów znaków w kodowaniu UTF‑8.

Użycie

Filtry zapisuje się za pionową kreską (może być przed nią spacja):

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

Filtry (w starszych wersjach helpery) można łączyć w łańcuchy, a następnie są stosowane w kolejności od lewej do prawej:

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

Parametry podaje się za nazwą filtra, oddzielone dwukropkami lub przecinkami:

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

Filtry można stosować również do wyrażeń:

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

Filtry niestandardowe można rejestrować w ten sposób:

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

W szablonie wywołuje się je w następujący sposób:

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

Filtry

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

Filtr, który upraszcza wyświetlanie danych liniowych w postaci tabeli. Zwraca tablicę tablic o podanej liczbie elementów. Jeśli podasz drugi parametr, zostanie on użyty do uzupełnienia brakujących elementów w ostatnim wierszu.

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

Wyświetli:

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

Zobacz także group i znacznik iterateWhile.

breakLines

Dodaje przed każdym znakiem nowego wiersza znacznik HTML <br>.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* wyświetla "Text &amp; with <br>\n newline" *}

bytes (int $precision=2)

Formatuje rozmiar w bajtach do postaci czytelnej dla człowieka. Jeśli ustawione są ustawienia regionalne, używane są odpowiednie separatory dziesiętne i tysięcy.

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

ceil (int $precision=0)

Zaokrągla liczbę w górę do podanej precyzji.

{=3.4|ceil}         {* wyświetla 4      *}
{=135.22|ceil:1}    {* wyświetla 135.3  *}
{=135.22|ceil:3}    {* wyświetla 135.22 *}

Zobacz także floor, round.

capitalize

Słowa będą zaczynać się wielkimi literami, wszystkie pozostałe znaki będą małe. Wymaga rozszerzenia PHP mbstring.

{='i like LATTE'|capitalize}  {* wyświetla 'I Like Latte' *}

Zobacz także firstUpper, lower, upper.

checkUrl

Wymusza oczyszczenie adresu URL. Sprawdza, czy zmienna zawiera adres URL (tj. protokół HTTP/HTTPS) i zapobiega wyświetlaniu linków, które mogą stanowić zagrożenie bezpieczeństwa.

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

Wyświetli:

<a data-href="">kontrolowane</a>
<a data-href="javascript:window.close()">niekontrolowane</a>

Zobacz także nocheck.

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

Ogranicza wartość do podanego zakresu włącznie min i max.

{$level|clamp: 0, 255}

Istnieje również jako funkcja.

dataStream (string $mimetype=detect)

Konwertuje zawartość do schematu data URI. Za jego pomocą można wstawiać obrazy do HTML lub CSS bez konieczności linkowania zewnętrznych plików.

Miejmy w zmiennej obrazek $img = Image::fromFile('obrazek.gif'), wtedy

<img src={$img|dataStream}>

Wyświetli na przykład:

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

Wymaga rozszerzenia PHP fileinfo.

date (string $format)

Formatuje datę i czas zgodnie z maską używaną przez funkcję PHP date. Filtr przyjmuje datę w formacie UNIX timestamp, jako ciąg znaków lub obiekt typu DateTimeInterface.

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

Zobacz także localDate.

escapeUrl

Escapuje zmienną do użycia jako parametr w URL.

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

Zobacz także query.

explode (string $separator='')

Dzieli ciąg znaków na tablicę według separatora. Alias dla split.

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

Jeśli separator jest pustym ciągiem (wartość domyślna), wejście zostanie podzielone na poszczególne znaki:

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

Możesz także użyć aliasu split:

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

Zobacz także implode.

first

Zwraca pierwszy element tablicy lub znak ciągu:

{=[1, 2, 3, 4]|first}    {* wyświetla 1 *}
{='abcd'|first}          {* wyświetla 'a' *}

Zobacz także last, random.

floor (int $precision=0)

Zaokrągla liczbę w dół do podanej precyzji.

{=3.5|floor}        {* wyświetla 3      *}
{=135.79|floor:1}   {* wyświetla 135.7  *}
{=135.79|floor:3}   {* wyświetla 135.79 *}

Zobacz także ceil, round.

firstUpper

Konwertuje pierwszą literę na wielką. Wymaga rozszerzenia PHP mbstring.

{='the latte'|firstUpper}  {* wyświetla 'The latte' *}

Zobacz także capitalize, lower, upper.

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

Filtr grupuje dane według różnych kryteriów.

W tym przykładzie wiersze w tabeli są grupowane według kolumny categoryId. Wyjściem jest tablica tablic, gdzie kluczem jest wartość w kolumnie categoryId. Przeczytaj szczegółowy przewodnik.

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

Zobacz także batch, funkcja group i znacznik iterateWhile.

implode (string $glue='')

Zwraca ciąg znaków, który jest połączeniem elementów sekwencji. Alias dla join.

{=[1, 2, 3]|implode}      {* wyświetla '123' *}
{=[1, 2, 3]|implode:'|'}  {* wyświetla '1|2|3' *}

Możesz także użyć aliasu join:

{=[1, 2, 3]|join}         {* wyświetla '123' *}

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

Wcięcie tekstu od lewej o podaną liczbę tabulatorów lub innych znaków, które można podać w drugim argumencie. Puste wiersze nie są wcięte.

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

Wyświetli:

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

last

Zwraca ostatni element tablicy lub znak ciągu:

{=[1, 2, 3, 4]|last}    {* wyświetla 4 *}
{='abcd'|last}          {* wyświetla 'd' *}

Zobacz także first, random.

length

Zwraca długość ciągu lub tablicy.

• dla ciągów zwraca długość w znakach UTF‑8
• dla tablic zwraca liczbę elementów
• dla obiektów implementujących interfejs Countable, używa wartości zwracanej przez metodę count()
• dla obiektów implementujących interfejs IteratorAggregate, używa wartości zwracanej przez funkcję iterator_count()

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

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

Formatuje datę i czas zgodnie z ustawieniami regionalnymi, co zapewnia spójne i zlokalizowane wyświetlanie danych czasowych w różnych językach i regionach. Filtr przyjmuje datę jako UNIX timestamp, ciąg znaków lub obiekt typu DateTimeInterface.

{$date|localDate}                  {* 15 kwietnia 2024 *}
{$date|localDate: format: yM}      {* 4/2024 *}
{$date|localDate: date: medium}    {* 15.04.2024 *}

Jeśli użyjesz filtra bez parametrów, data zostanie wyświetlona na poziomie long, zobacz dalej.

a) użycie formatu

Parametr format opisuje, które składniki czasu mają być wyświetlone. Używa do tego kodów literowych, których liczba powtórzeń wpływa na szerokość wyjścia:

Kolejność kodów w formacie nie ma znaczenia, ponieważ kolejność składników jest wyświetlana zgodnie ze zwyczajami ustawień regionalnych. Format jest więc od nich niezależny. Na przykład format yyyyMMMMd w środowisku en_US wyświetli April 15, 2024, podczas gdy w środowisku pl_PL wyświetli 15 kwietnia 2024:

b) użycie predefiniowanych stylów

Parametry date i time określają, jak szczegółowo ma być wyświetlana data i czas. Możesz wybrać spośród kilku poziomów: full, long, medium, short. Można wyświetlić tylko datę, tylko czas lub oba:

Dla daty można dodatkowo użyć prefiksu relative- (np. relative-short), który dla dat bliskich teraźniejszości wyświetli wczoraj, dzisiaj lub jutro, w przeciwnym razie zostanie wyświetlony w standardowy sposób.

{$date|localDate: date: relative-short}    {* wczoraj *}

Zobacz także date.

lower

Konwertuje ciąg znaków na małe litery. Wymaga rozszerzenia PHP mbstring.

{='LATTE'|lower}   {* wyświetla 'latte' *}

Zobacz także capitalize, firstUpper, upper.

nocheck

Zapobiega automatycznemu oczyszczaniu adresu URL. Latte automatycznie sprawdza, czy zmienna zawiera adres URL (tj. protokół HTTP/HTTPS) i zapobiega wyświetlaniu linków, które mogą stanowić zagrożenie bezpieczeństwa.

Jeśli link używa innego schematu, np. javascript: lub data:, i jesteś pewien jego zawartości, możesz wyłączyć kontrolę za pomocą |nocheck.

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

<a href={$link}>kontrolowane</a>
<a href={$link|nocheck}>niekontrolowane</a>

Wyświetli:

<a href="">kontrolowane</a>
<a href="javascript:window.close()">niekontrolowane</a>

Zobacz także checkUrl.

noescape

Wyłącza automatyczne escapowanie.

{var $trustedHtmlString = '<b>hello</b>'}
Escapowany: {$trustedHtmlString}
Neescapowany: {$trustedHtmlString|noescape}

Wyświetli:

Escapowany: <b>hello</b>
Neescapowany: <b>hello</b>

Nieprawidłowe użycie filtra noescape może prowadzić do powstania podatności XSS! Nigdy go nie używaj, jeśli nie jesteś całkowicie pewien, co robisz, i że wyświetlany ciąg pochodzi z zaufanego źródła.

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

Formatuje liczbę do określonej liczby miejsc dziesiętnych. Jeśli ustawione są ustawienia regionalne, używane są odpowiednie separatory dziesiętne i tysięcy.

{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 pozwala zdefiniować wygląd liczb dokładnie według Twoich potrzeb. Do tego potrzebne jest ustawienie ustawień regionalnych. Format składa się z kilku specjalnych znaków, których pełny opis znajdziesz w dokumentacji DecimalFormat:

• 0 obowiązkowa cyfra, zawsze się wyświetli, nawet jeśli to zero
• # opcjonalna cyfra, wyświetli się tylko wtedy, gdy na tym miejscu liczba rzeczywiście jest
• @ cyfra znacząca, pomaga wyświetlić liczbę z określoną liczbą cyfr znaczących
• . oznacza, gdzie ma być przecinek dziesiętny (lub kropka, w zależności od kraju)
• , służy do oddzielania grup cyfr, najczęściej tysięcy
• % mnoży liczbę przez 100× i dodaje znak procenta

Spójrzmy na przykłady. W pierwszym przykładzie dwa miejsca dziesiętne są obowiązkowe, w drugim opcjonalne. Trzeci przykład pokazuje uzupełnienie zerami z lewej i prawej strony, czwarty wyświetla tylko istniejące cyfry:

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

Cyfry znaczące określają, ile cyfr, niezależnie od przecinka dziesiętnego, ma być wyświetlonych, przy czym następuje zaokrąglenie:

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

Łatwy sposób na wyświetlenie liczby jako procentów. Liczba jest mnożona przez 100× i dodawany jest znak %:

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

Możemy zdefiniować odrębny format dla liczb dodatnich i ujemnych, oddziela je znak ;. W ten sposób można na przykład ustawić, że liczby dodatnie mają być wyświetlane ze znakiem +:

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

Pamiętaj, że rzeczywisty wygląd liczb może się różnić w zależności od ustawień kraju. Na przykład w niektórych krajach używa się przecinka zamiast kropki jako separatora miejsc dziesiętnych. Ten filtr automatycznie to uwzględni i nie musisz się o nic martwić.

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

Uzupełnia ciąg znaków do określonej długości innym ciągiem z lewej strony.

{='hello'|padLeft: 10, '123'}  {* wyświetla '12312hello' *}

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

Uzupełnia ciąg znaków do określonej długości innym ciągiem z prawej strony.

{='hello'|padRight: 10, '123'}  {* wyświetla 'hello12312' *}

query

Dynamicznie generuje query string w URL:

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

Wyświetli:

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

Klucze o wartości null są pomijane.

Zobacz także escapeUrl.

random

Zwraca losowy element tablicy lub znak ciągu:

{=[1, 2, 3, 4]|random}    {* wyświetla np.: 3 *}
{='abcd'|random}          {* wyświetla np.: 'b' *}

Zobacz także first, last.

repeat (int $count)

Powtarza ciąg znaków x razy.

{='hello'|repeat: 3}  {* wyświetla 'hellohellohello' *}

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

Zastępuje wszystkie wystąpienia szukanego ciągu ciągiem zastępującym.

{='hello world'|replace: 'world', 'friend'}  {* wyświetla 'hello friend' *}

Można wykonać wiele zamian jednocześnie:

{='hello world'|replace: [h => l, l => h]}  {* wyświetla 'lehho worhd' *}

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

Wykonuje wyszukiwanie wyrażeń regularnych z zastępowaniem.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* wyświetla 'hel' *}

reverse

Odwraca podany ciąg znaków lub tablicę.

{var $s = 'Nette'}
{$s|reverse}    {* wyświetla 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* zwraca ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Zaokrągla liczbę do podanej precyzji.

{=3.4|round}        {* wyświetla 3      *}
{=3.5|round}        {* wyświetla 4      *}
{=135.79|round:1}   {* wyświetla 135.8  *}
{=135.79|round:3}   {* wyświetla 135.79 *}

Zobacz także ceil, floor.

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

Wyodrębnia część tablicy lub ciągu.

{='hello'|slice: 1, 2}           {* wyświetla 'el' *}
{=['a', 'b', 'c']|slice: 1, 2}   {* wyświetla ['b', 'c'] *}

Filtr działa jak funkcja PHP array_slice dla tablic lub mb_substr dla ciągów z fallbackiem na funkcję iconv_substr w trybie UTF‑8.

Jeśli start jest dodatni, sekwencja zacznie się przesunięta o tę liczbę od początku tablicy/ciągu. Jeśli jest ujemny, sekwencja zacznie się przesunięta o tyle od końca.

Jeśli podany jest parametr length i jest dodatni, sekwencja będzie zawierać tyle elementów. Jeśli do tej funkcji zostanie przekazany ujemny parametr length, sekwencja będzie zawierać wszystkie elementy oryginalnej tablicy, zaczynając od pozycji start i kończąc na pozycji mniejszej o length elementów od końca tablicy. Jeśli ten parametr nie zostanie podany, sekwencja będzie zawierać wszystkie elementy oryginalnej tablicy, zaczynając od pozycji start.

Domyślnie filtr zmienia kolejność i resetuje klucze całkowite tablicy. To zachowanie można zmienić, ustawiając preserveKeys na true. Klucze ciągów są zawsze zachowywane, niezależnie od tego parametru.

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

Filtr sortuje elementy tablicy lub iteratora i zachowuje ich klucze asocjacyjne. Przy ustawionych ustawieniach regionalnych sortowanie odbywa się zgodnie z ich zasadami, chyba że określono własną funkcję porównującą.

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

Sortowana tablica w odwrotnej kolejności:

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

Możesz określić własną funkcję porównującą do sortowania (przykład pokazuje, jak odwrócić sortowanie od największego do najmniejszego):

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

Filtr |sort pozwala również sortować elementy według kluczy:

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

Jeśli potrzebujesz posortować tabelę według określonej kolumny, możesz użyć parametru by. Wartość 'name' w przykładzie określa, że sortowanie będzie odbywać się według $item->name lub $item['name'], w zależności od tego, czy $item jest tablicą czy obiektem:

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

Możesz również zdefiniować funkcję callback, która określi wartość, według której ma się odbywać sortowanie:

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

W ten sam sposób można wykorzystać parametr byKey.

spaceless

Usuwa zbędne białe znaki (spacje) z wyjścia. Możesz także użyć aliasu strip.

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

Wyświetli:

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

stripHtml

Konwertuje HTML na czysty tekst. Czyli usuwa z niego znaczniki HTML i konwertuje encje HTML na tekst.

{='<p>one &lt; two</p>'|stripHtml}  {* wyświetla 'one < two' *}

Wynikowy czysty tekst może naturalnie zawierać znaki, które reprezentują znaczniki HTML, na przykład '<p>'|stripHtml zostanie przekonwertowane na <p>. W żadnym wypadku nie wyświetlaj tak powstałego tekstu z |noescape, ponieważ może to prowadzić do powstania luki bezpieczeństwa.

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

Wyodrębnia część ciągu. Ten filtr został zastąpiony filtrem slice.

{$string|substr: 1, 2}

translate (…$args)

Tłumaczy wyrażenia na inne języki. Aby filtr był dostępny, należy ustawić translator. Możesz także użyć znaczników do tłumaczenia.

<a href="basket">{='Koszyk'|translate}</a>
<span>{$item|translate}</span>

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

Usuwa białe znaki (lub inne znaki) z początku i końca ciągu.

{='  I like Latte.  '|trim}    {* wyświetla 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* wyświetla '  I like Latte' *}

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

Obcina ciąg znaków do podanej maksymalnej długości, starając się zachować całe słowa. Jeśli ciąg zostanie skrócony, na końcu dodaje wielokropek (można to zmienić drugim 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

Konwertuje ciąg znaków na wielkie litery. Wymaga rozszerzenia PHP mbstring.

{='latte'|upper}  {* wyświetla 'LATTE' *}

Zobacz także capitalize, firstUpper, lower.

webalize

Dostosowuje ciąg UTF‑8 do formatu używanego w adresach URL.

Konwertuje na ASCII. Konwertuje spacje na myślniki. Usuwa znaki, które nie są alfanumeryczne, podkreśleniami ani myślnikami. Konwertuje na małe litery. Usuwa również początkowe i końcowe spacje.

{var $s = 'Nasz 10. produkt'}
{$s|webalize}   {* wyświetla 'nasz-10-produkt' *}

Wymaga biblioteki nette/utils.