Funkcje Latte
*************
.[perex]
Oprócz zwykłych funkcji PHP możesz w szablonach używać także tych funkcji.
.[table-latte-filters]
| `clamp` | [ogranicza wartość do zadanego zakresu |#clamp()]
| `divisibleBy`| [sprawdza, czy zmienna jest podzielna przez liczbę |#divisibleBy()]
| `even` | [sprawdza, czy podana liczba jest parzysta |#even()]
| `first` | [zwraca pierwszy element tablicy lub znak łańcucha |#first()]
| `group` | [grupuje dane według różnych kryteriów |#group()]
| `hasBlock` | [wykrywa istnienie bloku |#hasBlock()]
| `hasTemplate`| [wykrywa istnienie szablonu |#hasTemplate()]
| `last` | [zwraca ostatni element tablicy lub znak łańcucha |#last()]
| `odd` | [sprawdza, czy podana liczba jest nieparzysta |#odd()]
| `slice` | [wycina fragment tablicy lub łańcucha |#slice()]
Użycie
======
Funkcji używa się tak samo jak zwykłych funkcji PHP i można ich używać we wszystkich wyrażeniach:
```latte
<p>{clamp($num, 1, 100)}</p>
{if odd($num)} ... {/if}
```
[Własne funkcje|custom-functions] można rejestrować w ten sposób:
```php
$latte = new Latte\Engine;
$latte->addFunction('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
```
W szablonie wywołuje się je potem tak:
```latte
<p>{shortify($text)}</p>
<p>{shortify($text, 100)}</p>
```
Funkcje
=======
clamp(int|float $value, int|float $min, int|float $max): int|float .[method]
----------------------------------------------------------------------------
Ogranicza wartość do podanego zakresu domkniętego między min a max.
```latte
{=clamp($level, 0, 255)}
```
Zobacz też [filtr clamp |filters#clamp].
divisibleBy(int $value, int $by): bool .[method]
------------------------------------------------
Sprawdza, czy zmienna jest podzielna przez liczbę.
```latte
{if divisibleBy($num, 5)} ... {/if}
```
even(int $value): bool .[method]
--------------------------------
Sprawdza, czy podana liczba jest parzysta.
```latte
{if even($num)} ... {/if}
```
first(string|iterable $value): mixed .[method]
----------------------------------------------
Zwraca pierwszy element tablicy albo pierwszy znak łańcucha:
```latte
{=first([1, 2, 3, 4])} {* wypisze 1 *}
{=first('abcd')} {* wypisze 'a' *}
```
Zobacz też [#last()], [filtr first |filters#first].
group(iterable $data, string|int|\Closure $by): iterable .[method]{data-version:3.0.16}
---------------------------------------------------------------------------------------
Ta funkcja grupuje dane według różnych kryteriów.
W tym przykładzie wiersze tabeli są grupowane według kolumny `categoryId`. Wynikiem jest iterowalna struktura grup, w której kluczem jest wartość z kolumny `categoryId`. [Przeczytaj szczegółowy przewodnik|cookbook/grouping].
```latte
{foreach group($items, categoryId) as $categoryId => $categoryItems}
<ul>
{foreach $categoryItems as $item}
<li>{$item->name}</li>
{/foreach}
</ul>
{/foreach}
```
Zobacz też [filtr group |filters#group].
hasBlock(string $name): bool .[method]{data-version:3.0.10}
-----------------------------------------------------------
Sprawdza, czy istnieje blok o podanej nazwie:
```latte
{if hasBlock(header)} ... {/if}
```
Zobacz też [sprawdzanie istnienia bloku |template-inheritance#Sprawdzanie istnienia bloku].
hasTemplate(string $name): bool .[method]{data-version:3.0.22}
--------------------------------------------------------------
Ustala, czy istnieje szablon o podanej nazwie:
```latte
{if hasTemplate('foo.latte')} ... {/if}
```
last(string|array $value): mixed .[method]
------------------------------------------
Zwraca ostatni element tablicy albo ostatni znak łańcucha:
```latte
{=last([1, 2, 3, 4])} {* wypisze 4 *}
{=last('abcd')} {* wypisze 'd' *}
```
Zobacz też [#first()], [filtr last |filters#last].
odd(int $value): bool .[method]
-------------------------------
Sprawdza, czy podana liczba jest nieparzysta.
```latte
{if odd($num)} ... {/if}
```
slice(string|iterable $value, int $start, ?int $length=null, bool $preserveKeys=false): string|array|\Generator .[method]
-------------------------------------------------------------------------------------------------------------------------
Wycina fragment tablicy, łańcucha albo iteratora.
```latte
{=slice('hello', 1, 2)} {* wypisze 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)} {* wypisze ['b', 'c'] *}
```
Funkcja działa jak funkcja PHP `array_slice` dla tablic albo `mb_substr` dla łańcuchów, z awaryjnym przejściem na funkcję `iconv_substr` w trybie UTF‑8. Jeśli wejściem jest ogólny iterator, zostanie on przekształcony w generator zwracający wycięte elementy.
Jeśli `start` jest nieujemny, sekwencja zacznie się od tego przesunięcia od początku tablicy/łańcucha. Jeśli `start` jest ujemny, sekwencja zacznie się o tyle elementów od końca.
Jeśli podano `length` i jest dodatnie, sekwencja będzie miała co najwyżej tyle elementów. Jeśli wejście jest krótsze niż `length`, znajdą się w niej tylko dostępne elementy. Jeśli podano `length` i jest ujemne, sekwencja zakończy się o tyle elementów przed końcem wejścia. Jeśli zostanie pominięte, sekwencja obejmie wszystko od `start` do końca wejścia.
Domyślnie funkcja przenumerowuje i resetuje całkowitoliczbowe klucze tablicy. To zachowanie można zmienić, ustawiając `preserveKeys` na true. Klucze łańcuchowe są zachowywane zawsze, niezależnie od tego parametru.
Funkcje Latte
Oprócz zwykłych funkcji PHP możesz w szablonach używać także tych funkcji.
Użycie
Funkcji używa się tak samo jak zwykłych funkcji PHP i można ich używać we wszystkich wyrażeniach:
<p>{clamp($num, 1, 100)}</p>
{if odd($num)} ... {/if}
Własne funkcje można rejestrować w ten sposób:
$latte = new Latte\Engine;
$latte->addFunction('shortify', fn(string $s, int $len = 10) => mb_substr($s, 0, $len));
W szablonie wywołuje się je potem tak:
<p>{shortify($text)}</p>
<p>{shortify($text, 100)}</p>
Funkcje
clamp (int|float $value, int|float $min,
int|float $max): int|float
Ogranicza wartość do podanego zakresu domkniętego między min a max.
{=clamp($level, 0, 255)}
Zobacz też filtr clamp.
divisibleBy (int $value, int
$by): bool
Sprawdza, czy zmienna jest podzielna przez liczbę.
{if divisibleBy($num, 5)} ... {/if}
even (int $value):
bool
Sprawdza, czy podana liczba jest parzysta.
{if even($num)} ... {/if}
first (string|iterable $value): mixed
Zwraca pierwszy element tablicy albo pierwszy znak łańcucha:
{=first([1, 2, 3, 4])} {* wypisze 1 *}
{=first('abcd')} {* wypisze 'a' *}
Zobacz też last(), filtr first.
group (iterable $data,
string|int|\Closure $by): iterable
Ta funkcja grupuje dane według różnych kryteriów.
W tym przykładzie wiersze tabeli są grupowane według kolumny categoryId. Wynikiem jest iterowalna struktura
grup, w której kluczem jest wartość z kolumny categoryId. Przeczytaj szczegółowy przewodnik.
{foreach group($items, categoryId) as $categoryId => $categoryItems}
<ul>
{foreach $categoryItems as $item}
<li>{$item->name}</li>
{/foreach}
</ul>
{/foreach}
Zobacz też filtr group.
hasBlock (string
$name): bool
Sprawdza, czy istnieje blok o podanej nazwie:
{if hasBlock(header)} ... {/if}
Zobacz też sprawdzanie istnienia
bloku.
hasTemplate (string
$name): bool
Ustala, czy istnieje szablon o podanej nazwie:
{if hasTemplate('foo.latte')} ... {/if}
last (string|array $value): mixed
Zwraca ostatni element tablicy albo ostatni znak łańcucha:
{=last([1, 2, 3, 4])} {* wypisze 4 *}
{=last('abcd')} {* wypisze 'd' *}
Zobacz też first(), filtr last.
odd (int $value):
bool
Sprawdza, czy podana liczba jest nieparzysta.
{if odd($num)} ... {/if}
slice (string|iterable $value, int $start,
?int $length=null, bool $preserveKeys=false):
string|array|\Generator
Wycina fragment tablicy, łańcucha albo iteratora.
{=slice('hello', 1, 2)} {* wypisze 'el' *}
{=slice(['a', 'b', 'c'], 1, 2)} {* wypisze ['b', 'c'] *}
Funkcja działa jak funkcja PHP array_slice dla tablic albo mb_substr dla łańcuchów, z awaryjnym
przejściem na funkcję iconv_substr w trybie UTF‑8. Jeśli wejściem jest ogólny iterator, zostanie on
przekształcony w generator zwracający wycięte elementy.
Jeśli start jest nieujemny, sekwencja zacznie się od tego przesunięcia od początku tablicy/łańcucha. Jeśli
start jest ujemny, sekwencja zacznie się o tyle elementów od końca.
Jeśli podano length i jest dodatnie, sekwencja będzie miała co najwyżej tyle elementów. Jeśli wejście jest
krótsze niż length, znajdą się w niej tylko dostępne elementy. Jeśli podano length i jest
ujemne, sekwencja zakończy się o tyle elementów przed końcem wejścia. Jeśli zostanie pominięte, sekwencja obejmie wszystko
od start do końca wejścia.
Domyślnie funkcja przenumerowuje i resetuje całkowitoliczbowe klucze tablicy. To zachowanie można zmienić, ustawiając
preserveKeys na true. Klucze łańcuchowe są zachowywane zawsze, niezależnie od tego parametru.