Filtry do latte

Możemy używać funkcji w szablonach, aby pomóc w edycji lub przeformatowaniu danych do ostatecznej postaci. Nazywamy je filtrami.

Istnieją również filtry ucieczki dla HTML (escapeHtml i escapeHtmlComment), XML (escapeXml), JavaScript (escapeJs), CSS (escapeCss) i iCalendar (escapeICal), które Latte używa samodzielnie dzięki ucieczce kontekstowej i nie musisz ich pisać.

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

Wszystkie domyślne filtry są dla ciągów zakodowanych w UTF-8.

Użycie

Filtry zapisywane są po pionowym pasku (mogą być poprzedzone spacją):

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

Filtry (w starszych wersjach pomocnicy) mogą być konkatenowane, a następnie stosowane w kolejności od lewej do prawej:

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

Parametry wprowadzane są po nazwie filtra, oddzielone dwukropkami lub przecinkami:

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

Filtry mogą być również stosowane do wyrażenia:

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

Filtry niestandardowe można zarejestrować w następujący sposób:

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

W szablonie jest on wówczas nazywany 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 wyprowadzenie danych liniowych do tabeli. Zwraca tablicę pól o określonej liczbie elementów. Jeśli określisz drugi parametr, jest on używany do wypeł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>

Wydruki:

<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 tag group i iterateWhile.

breakLines

Wstawia podziały linii HTML przed wszystkimi liniami nowymi.

{var $s = "Text & with \n newline"}
{$s|breakLines}    {* vypíše "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ęczne.

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

ceil (int $precision=0)

Zaokrągla liczbę do określonej precyzji.

{=3.4|ceil}         {* outputs 4      *}
{=135.22|ceil:1}    {* outputs 135.3  *}
{=135.22|ceil:3}    {* outputs 135.22 *}

Patrz także podłoga, okrągła.

capitalize

Zwraca tytułową wersję wartości. Słowa będą zaczynać się od dużych liter, wszystkie pozostałe znaki są małe. Wymaga rozszerzenia PHP mbstring.

{='i like LATTE'|capitalize}  {* outputs 'I Like Latte' *}

Zobacz także firstUpper, lower, upper.

checkUrl

Wymusza sanityzację adresów URL. Sprawdza czy zmienna zawiera adres URL strony internetowej (tj. protokół HTTP/HTTPS) i zapobiega zapisywaniu linków, które mogą stanowić zagrożenie bezpieczeństwa.

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

Wydruki:

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

Zobacz również nocheck.

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

Zwraca wartość zaciśniętą na inkluzywnym zakresie min i max.

{$level|clamp: 0, 255}

Istnieje również jako funkcja.

dataStream (string $mimetype=detect)

Konwertuje zawartość na schemat URI danych. Może być używany do wstawiania obrazów do HTML lub CSS bez potrzeby łączenia plików zewnętrznych.

Załóżmy, że mamy obrazek w zmiennej $img = Image::fromFile('obrazek.gif'), to

<img src={$img|dataStream}>

Drukuje na przykład:

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

Wymaga rozszerzenia PHP fileinfo.

date (string $format)

Formatuje datę i godzinę zgodnie z maską używaną przez funkcję PHP date. Filtr akceptuje datę w formacie znacznika czasu UNIX, jako ciąg znaków lub jako obiekt DateTimeInterface.

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

Zobacz także localDate.

escapeUrl

Ucieka od zmiennej, która ma być użyta jako parametr w URL.

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

Zobacz również zapytanie.

explode (string $separator='')

Rozdziela łańcuch przez podany delimiter i zwraca tablicę łańcuchów. Alias dla split.

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

Jeśli delimiterem jest pusty łańcuch (wartość domyślna), to wejście zostanie podzielone na pojedyncze znaki:

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

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

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

Zobacz również implode.

first

Zwraca pierwszy element tablicy lub znak łańcucha:

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

Zobacz także last, random.

floor (int $precision=0)

Zaokrągla liczbę do określonej dokładności.

{=3.5|floor}        {* outputs 3      *}
{=135.79|floor:1}   {* outputs 135.7  *}
{=135.79|floor:3}   {* outputs 135.79 *}

Zobacz także ceil, round.

firstUpper

Konwertuje pierwszą literę wartości na duże. Wymaga rozszerzenia PHP mbstring.

{='the latte'|firstUpper}  {* outputs '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ą pogrupowane według kolumny categoryId. Wynikiem jest tablica tablic, w której kluczem jest wartość w kolumnie categoryId. Przeczytaj szczegółowe instrukcje.

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

Zobacz także batch, funkcję group i znacznik iterateWhile.

implode (string $glue='')

Zwraca łańcuch będący konkatenacją łańcuchów w tablicy. Alias dla join.

{=[1, 2, 3]|implode}      {* outputs '123' *}
{=[1, 2, 3]|implode:'|'}  {* outputs '1|2|3' *}

Możesz również użyć aliasu join:

{=[1, 2, 3]|join}         {* outputs '123' *}

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

Wcina tekst od lewej strony o określoną liczbę tabulatorów lub innych znaków, które podajemy w drugim opcjonalnym argumencie. Puste linie nie są wcięte.

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

Drukuje:

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

last

Zwraca ostatni element tablicy lub znak łańcucha:

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

Zobacz także first, random.

length

Zwraca długość łańcucha lub tablicy.

• dla łańcuchów, zwróci długość w znakach UTF-8
• dla tablic, zwróci liczbę elementów
• dla obiektów implementujących interfejs Countable, użyje wartości zwracanej przez count()
• dla obiektów implementujących interfejs IteratorAgregate, użyje wartości zwracanej przez iterator_count()

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

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

Formatuje datę i godzinę zgodnie z ustawieniami regionalnymi, zapewniając spójne i zlokalizowane wyświetlanie danych czasu w różnych językach i regionach. Filtr akceptuje datę jako znacznik czasu UNIX, ciąg znaków lub obiekt DateTimeInterface.

{$date|localDate}                  {* 15. dubna 2024 *}
{$date|format: yM}                 {* 4/2024 *}
{$date|localDate: date: medium}    {* 15. 4. 2024 *}

Jeśli użyjesz filtra bez żadnych parametrów, wyświetli on datę w długim formacie, jak wyjaśniono dalej.

a) Użycie formatu

Parametr format opisuje, które składniki czasu powinny być wyświetlane. Używa kodów literowych, gdzie liczba powtórzeń wpływa na szerokość wyjścia:

Kolejność kodów w formacie nie ma znaczenia, ponieważ kolejność komponentów będzie wyświetlana zgodnie z konwencjami regionalnymi. Dlatego format jest niezależny od ustawień regionalnych. Na przykład, format yyyyMMMMd w locale en_US wyświetla April 15, 2024, podczas gdy w locale cs_CZ wyświetla 15. dubna 2024:

b) Korzystanie z gotowych stylów

Parametry date i time określają poziom szczegółowości wyświetlania daty i godziny. Można wybrać jeden z kilku poziomów: full, long, medium, short. Można wyświetlać tylko datę, tylko godzinę lub obie te wartości:

W przypadku daty można również użyć prefiksu relative- (np. relative-short), co w przypadku dat bliskich teraźniejszości spowoduje wyświetlenie yesterday, today lub tomorrow; w przeciwnym razie zostanie wyświetlony w standardowy sposób.

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

Zobacz też data.

lower

Konwertuje wartość na małe litery. Wymaga rozszerzenia PHP mbstring.

{='LATTE'|lower}   {* outputs 'latte' *}

Zobacz także capitalize, firstUpper, upper.

nocheck

Zapobiega automatycznej sanityzacji adresów URL. Latte automatycznie sprawdza, czy zmienna zawiera adres URL strony internetowej (tj. protokół HTTP/HTTPS) i zapobiega zapisywaniu linków, które mogą stanowić zagrożenie dla bezpieczeństwa.

Jeśli link używa innego schematu, takiego jak javascript: lub data:, i jesteś pewien jego zawartości, możesz wyłączyć sprawdzanie poprzez |nocheck.

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

<a href={$link}>checked</a>
<a href={$link|nocheck}>unchecked</a>

Wydruki:

<a href="">checked</a>
<a href="javascript:window.close()">unchecked</a>

Zobacz także checkUrl.

noescape

Wyłącza automatyczne uciekanie.

{var $trustedHtmlString = '<b>hello</b>'}
Escaped: {$trustedHtmlString}
Unescaped: {$trustedHtmlString|noescape}

Drukuje:

Escaped: <b>hello</b>
Unescaped: <b>hello</b>

Niewłaściwe użycie filtra noescape może prowadzić do luki XSS! Nigdy nie używaj go, jeśli nie jesteś absolutnie pewien tego, co robisz i że drukowany 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ęczne.

{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 własnych potrzeb. Wymaga ustawionych ustawień regionalnych. Format składa się z kilku znaków specjalnych, których pełny opis można znaleźć w dokumentacji DecimalFormat:

• <c id=6/> cyfra obowiązkowa, wyświetlana zawsze, nawet jeśli jest zerem
• # cyfra opcjonalna, wyświetlana tylko wtedy, gdy liczba ma cyfrę w tym miejscu
• @ cyfra znacząca, pomaga wyświetlić liczbę z określoną liczbą cyfr znaczących
• . oznacza miejsce, w którym powinien znajdować się separator dziesiętny (przecinek lub kropka, w zależności od ustawień regionalnych)
• , używany do oddzielania grup cyfr, zwykle tysięcy
• % mnoży liczbę przez 100 i dodaje znak procentu

Przyjrzyjmy się kilku przykładom. W pierwszym przykładzie dwa miejsca po przecinku są obowiązkowe; w drugim są opcjonalne. Trzeci przykład pokazuje wypełnianie zerami po obu stronach, a 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 *}

Znaczące cyfry określają, ile cyfr, niezależnie od przecinka dziesiętnego, powinno być wyświetlanych, zaokrąglając liczbę w razie potrzeby:

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

Prosty sposób wyświetlania liczby jako procentu. Liczba jest mnożona przez 100 i dodawany jest znak %:

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

Możemy zdefiniować inny format dla liczb dodatnich i ujemnych, oddzielonych znakiem ;. W ten sposób, na przykład, liczby dodatnie mogą być wyświetlane ze znakiem +:

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

Należy pamiętać, że rzeczywisty wygląd liczb może się różnić w zależności od ustawień regionalnych. Na przykład w niektórych krajach przecinek jest używany zamiast kropki jako separator dziesiętny. Ten filtr automatycznie to uwzględnia, więc nie musisz się tym martwić.

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

Przekłada łańcuch o określonej długości z innym łańcuchem od lewej.

{='hello'|padLeft: 10, '123'}  {* outputs '12312hello' *}

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

Wyrównuje ciąg do pewnej długości z innym ciągiem od prawej.

{='hello'|padRight: 10, '123'}  {* outputs 'hello12312' *}

query

Dynamicznie generuje ciąg zapytania w adresie URL:

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

Drukuje:

<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 również escapeUrl.

random

Zwraca losowy element tablicy lub znak łańcucha:

{=[1, 2, 3, 4]|random}    {* example output: 3 *}
{='abcd'|random}          {* example output: 'b' *}

Zobacz również first, last.

repeat (int $count)

Powtarza łańcuch x razy.

{='hello'|repeat: 3}  {* outputs 'hellohellohello' *}

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

Zastępuje wszystkie wystąpienia szukanego łańcucha łańcuchem zastępczym.

{='hello world'|replace: 'world', 'friend'}  {* outputs 'hello friend' *}

Można dokonać wielu zamian jednocześnie:

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

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

Zastępuje wszystkie wystąpienia zgodnie z wyrażeniem regularnym.

{='hello world'|replaceRE: '/l.*/', 'l'}  {* outputs 'hel' *}

reverse

Odwraca podany łańcuch lub tablicę.

{var $s = 'Nette'}
{$s|reverse}    {* outputs 'etteN' *}
{var $a = ['N', 'e', 't', 't', 'e']}
{$a|reverse}    {* returns ['e', 't', 't', 'e', 'N'] *}

round (int $precision=0)

Zaokrągla liczbę do określonej precyzji.

{=3.4|round}        {* outputs 3      *}
{=3.5|round}        {* outputs 4      *}
{=135.79|round:1}   {* outputs 135.8  *}
{=135.79|round:3}   {* outputs 135.79 *}

Zobacz także ceil, floor.

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

Wyodrębnia fragment tablicy lub ciągu znaków.

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

Filtr plasterkowy działa jak funkcja array_slice PHP dla tablic i mb_substr dla łańcuchów z możliwością powrotu do iconv_substr w trybie UTF-8.

Jeśli początek jest nieujemny, to sekwencja rozpocznie się od tego początku w zmiennej. Jeśli start jest ujemny, sekwencja rozpocznie się tak daleko od końca zmiennej.

Jeśli podana jest długość i jest ona dodatnia, to sekwencja będzie miała do tylu elementów. Jeśli zmienna jest krótsza niż długość, to w sekwencji znajdą się tylko dostępne elementy zmiennej. Jeśli podana jest długość i jest ona ujemna, to sekwencja zatrzyma się o tyle elementów od końca zmiennej. Jeśli jest pominięta, to sekwencja będzie miała wszystko od offsetu aż do końca zmiennej.

Filtr domyślnie zmieni kolejność i wyzeruje klucze tablicy liczb całkowitych. To zachowanie można zmienić ustawiając preserveKeys na true. Klucze łańcuchowe 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, zachowując ich klucze asocjacyjne. Gdy ustawione są ustawienia regionalne, sortowanie odbywa się zgodnie z ich regułami, chyba że określono niestandardową funkcję porównania.

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

Tablica posortowana w odwrotnej kolejności.

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

Można określić niestandardową funkcję porównania 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 umożliwia również sortowanie elementów według klucza:

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

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

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

Można również zdefiniować funkcję zwrotną, która określa wartość do sortowania:

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

Parametr byKey może być używany w ten sam sposób.

spaceless

Usuwa niepotrzebne białe przestrzenie z wyjścia. Możesz również użyć aliasu strip.

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

Drukuje:

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

stripHtml

Konwertuje HTML na zwykły tekst. To znaczy, usuwa znaczniki HTML i konwertuje encje HTML na tekst.

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

Wynikowy zwykły tekst może naturalnie zawierać znaki reprezentujące znaczniki HTML, na przykład '<p>'|stripHtml jest konwertowany na <p>. Nigdy nie wyprowadzaj wynikowego tekstu za pomocą |noescape, ponieważ może to prowadzić do luki w zabezpieczeniach.

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

Wyodrębnia fragment łańcucha. Ten filtr został zastąpiony przez filtr slice.

{$string|substr: 1, 2}

translate (…$args)

Tłumaczy wyrażenia na inne języki. Aby udostępnić ten filtr, musisz skonfigurować translator. Możesz również użyć tagów do tłumaczenia.

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

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

Strip leading and trailing characters, by default whitespace.

{='  I like Latte.  '|trim}    {* outputs 'I like Latte.' *}
{='  I like Latte.'|trim: '.'} {* outputs '  I like Latte' *}

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

Skraca łańcuch do maksymalnej podanej długości, ale stara się zachować całe słowa. Jeśli łańcuch jest obcięty, dodaje na końcu elipsę (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 wartość na duże litery. Wymaga rozszerzenia PHP mbstring.

{='latte'|upper}  {* outputs 'LATTE' *}

Zobacz także capitalize, firstUpper, lower.

webalize

Konwertuje na ASCII.

Zamienia spacje na myślniki. Usuwa znaki, które nie są alfanumeryczne, podkreślenia lub myślniki. Konwertuje na małe litery. Usuwa również wiodącą i końcową białą przestrzeń.

{var $s = 'Our 10. product'}
{$s|webalize}    {* outputs 'our-10-product' *}

Wymaga pakietu nette/utils.