Rozszerzanie Latte
******************
.[perex]
Latte zostało zaprojektowane z myślą o rozszerzalności. Choć jego standardowy zestaw tagów, filtrów i funkcji pokrywa wiele zastosowań, często trzeba dodać własną logikę lub pomocniki. Ta strona daje przegląd tego, jak rozszerzyć Latte, aby idealnie pasowało do wymagań Twojego projektu, od prostych pomocników po złożoną nową składnię.
Sposoby rozszerzania Latte
==========================
Oto szybki przegląd głównych sposobów dostosowywania i rozszerzania Latte:
- **[Własne filtry|custom-filters]:** do formatowania lub przekształcania danych bezpośrednio w wyniku szablonu (np. `{$var|myFilter}`). Idealne do zadań takich jak formatowanie dat, operacje na tekście czy zastosowanie konkretnego escapowania. Możesz ich użyć również do modyfikowania większych bloków treści HTML, opakowując treść w anonimowy [`{block}` |tags#{block}] i stosując własny filtr.
- **[Własne funkcje|custom-functions]:** do dodawania logiki wielokrotnego użytku, którą można wywoływać w wyrażeniach szablonu (np. `{myFunction($arg1, $arg2)}`). Przydatne do obliczeń, sięgania po pomocniki aplikacji albo generowania niewielkich fragmentów treści.
- **[Własne tagi|custom-tags]:** do tworzenia zupełnie nowych konstrukcji językowych (`{mytag}...{/mytag}` albo `n:mytag`). Tagi dają największe możliwości: pozwalają definiować własne struktury, sterować parsowaniem szablonu i implementować złożoną logikę renderowania.
- **[Compiler passy|compiler-passes]:** funkcje modyfikujące drzewo składniowe (AST) szablonu po parsowaniu, ale przed wygenerowaniem kodu PHP. Używane do zaawansowanych optymalizacji, kontroli bezpieczeństwa (jak Sandbox) czy automatycznych modyfikacji kodu.
- **[Własne loadery|loaders]:** do zmiany sposobu, w jaki Latte znajduje i wczytuje pliki szablonów (np. wczytywanie z bazy danych, z zaszyfrowanego magazynu itd.).
Wybór właściwego sposobu rozszerzenia jest kluczowy. Zanim stworzysz złożony tag, zastanów się, czy nie wystarczy prostszy filtr albo funkcja. Zilustrujmy to przykładem: implementacją generatora *Lorem ipsum*, który jako argument przyjmuje liczbę słów do wygenerowania.
- **Jako tag?** `{lipsum 40}` - możliwe, ale tagi lepiej nadają się do struktur sterujących albo generowania złożonego markupu. Tagów nie da się użyć bezpośrednio w wyrażeniach.
- **Jako filtr?** `{=40|lipsum}` - technicznie działa, ale filtry mają *przekształcać* wejście. Tutaj `40` to *argument*, a nie przekształcana wartość. Semantycznie to nie brzmi dobrze.
- **Jako funkcja?** `{lipsum(40)}` - to najbardziej naturalne rozwiązanie! Funkcje przyjmują argumenty i zwracają wartości, więc doskonale nadają się do użycia w dowolnym wyrażeniu: `{var $text = lipsum(40)}`.
**Ogólna wskazówka:** funkcji używaj do obliczeń i generowania, filtrów do przekształcania, a tagów do nowych struktur językowych albo złożonego markupu. Passów używaj do manipulacji AST, a loaderów do pobierania szablonów.
Bezpośrednia rejestracja
========================
Do pomocników specyficznych dla projektu albo szybkich dodatków Latte pozwala rejestrować filtry i funkcje bezpośrednio na obiekcie `Latte\Engine`.
Do zarejestrowania filtra użyj `addFilter()`. Pierwszym argumentem funkcji filtra będzie wartość przed potokiem `|`, a kolejnymi te podane po dwukropku `:`.
```php
$latte = new Latte\Engine;
// definicja filtra (callable: funkcja, metoda statyczna itd.)
$myTruncate = fn(string $s, int $length = 50) => mb_substr($s, 0, $length);
// rejestracja
$latte->addFilter('truncate', $myTruncate);
// użycie w szablonie: {$text|truncate} albo {$text|truncate:100}
```
Do zarejestrowania funkcji używalnej w wyrażeniach szablonu użyj `addFunction()`.
```php
$latte = new Latte\Engine;
// definicja funkcji
$isWeekend = fn(DateTimeInterface $date) => $date->format('N') >= 6;
// rejestracja
$latte->addFunction('isWeekend', $isWeekend);
// użycie w szablonie: {if isWeekend($myDate)}Weekend!{/if}
```
Więcej szczegółów znajdziesz w [Tworzenie własnych filtrów|custom-filters] i [Funkcje|custom-functions].
Robustny sposób: Latte Extension .{toc: Latte Extension}
========================================================
Bezpośrednia rejestracja jest prosta, ale standardowym i zalecanym sposobem grupowania i dystrybucji rozszerzeń Latte są **klasy rozszerzeń**. Rozszerzenie działa jak centralny punkt konfiguracji do rejestrowania wielu tagów, filtrów, funkcji, compiler passów i innych rzeczy.
Po co używać rozszerzeń?
- **Organizacja:** trzyma powiązane rozszerzenia (tagi, filtry itd. dla konkretnej funkcjonalności) razem w jednej klasie.
- **Ponowne użycie i udostępnianie:** łatwo spakujesz swoje rozszerzenia do użytku w innych projektach albo do udostępnienia społeczności (np. przez Composera).
- **Pełne możliwości:** własne tagi i compiler passy *można* zarejestrować wyłącznie przez rozszerzenia.
Rejestracja rozszerzenia
------------------------
Rozszerzenie rejestruje się w Latte metodą `addExtension()` (albo przez [plik konfiguracyjny |application:configuration#Szablony Latte]):
```php
$latte = new Latte\Engine;
$latte->addExtension(new MyProjectExtension);
```
Jeśli zarejestrujesz kilka rozszerzeń, a definiują one tagi, filtry albo funkcje o tych samych nazwach, wygrywa rozszerzenie dodane jako ostatnie. Wynika z tego również, że Twoje rozszerzenia mogą nadpisywać natywne tagi, filtry i funkcje.
Za każdym razem, gdy zmienisz klasę, a automatyczne odświeżanie nie jest wyłączone, Latte samo przekompiluje Twoje szablony.
Tworzenie rozszerzenia
----------------------
Aby utworzyć własne rozszerzenie, musisz stworzyć klasę dziedziczącą po [api:Latte\Extension]. Aby wyrobić sobie pogląd, jak takie rozszerzenie wygląda, zajrzyj do wbudowanego [CoreExtension |https://github.com/nette/latte/blob/master/src/Latte/Essential/CoreExtension.php].
Zobaczmy, jakie metody możesz zaimplementować:
beforeCompile(Latte\Engine $engine): void .[method]
---------------------------------------------------
Wywoływana przed skompilowaniem szablonu. Metody można użyć na przykład do inicjalizacji związanych z kompilacją.
getTags(): array .[method]
--------------------------
Wywoływana przy kompilacji szablonu. Zwraca tablicę asocjacyjną *nazwa tagu => callable*, czyli funkcje parsujące tagi. [Dowiedz się więcej|custom-tags].
```php
public function getTags(): array
{
return [
'foo' => FooNode::create(...),
'bar' => BarNode::create(...),
'n:baz' => NBazNode::create(...),
// ...
];
}
```
Tag `n:baz` reprezentuje czysty [n:atrybut |syntax#n:atrybuty], czyli tag, który można zapisać wyłącznie jako atrybut.
W przypadku tagów `foo` i `bar` Latte automatycznie rozpozna, czy są parzyste, a jeśli tak, można je automatycznie zapisywać za pomocą n:atrybutów, łącznie z wariantami z prefiksami `n:inner-foo` i `n:tag-foo`.
Kolejność wykonywania takich n:atrybutów wynika z ich kolejności w tablicy zwracanej przez `getTags()`. Dlatego `n:foo` jest zawsze wykonywany przed `n:bar`, nawet jeśli atrybuty są podane w tagu HTML w odwrotnej kolejności jako `<div n:bar="..." n:foo="...">`.
Jeśli potrzebujesz ustalić kolejność n:atrybutów pochodzących z różnych rozszerzeń, użyj metody pomocniczej `order()`, w której parametr `before` i/lub `after` określa, które tagi mają być uporządkowane przed danym tagiem lub po nim.
```php
public function getTags(): array
{
return [
'foo' => self::order(FooNode::create(...), before: 'bar'),
'bar' => self::order(BarNode::create(...), after: ['block', 'snippet']),
];
}
```
getPasses(): array .[method]
----------------------------
Wywoływana przy kompilacji szablonu. Zwraca tablicę asocjacyjną *nazwa passu => callable*, czyli funkcje reprezentujące tzw. [compiler passy|compiler-passes], które przechodzą przez AST i je modyfikują.
Także tutaj można użyć metody pomocniczej `order()`. Wartością parametrów `before` albo `after` może być `*` w znaczeniu przed wszystkimi / po wszystkich.
```php
public function getPasses(): array
{
return [
'optimize' => Passes::optimizePass(...),
'sandbox' => self::order($this->sandboxPass(...), before: '*'),
// ...
];
}
```
beforeRender(Latte\Runtime\Template $template): void .[method]
--------------------------------------------------------------
Wywoływana przed każdym renderowaniem szablonu. Metody można użyć na przykład do zainicjowania zmiennych używanych podczas renderowania.
afterRender(Latte\Runtime\Template $template): void .[method]{data-version:3.1.6}
---------------------------------------------------------------------------------
Wywoływana po każdym renderowaniu szablonu. Uruchamia się nawet wtedy, gdy renderowanie zakończy się wcześniej przez `{exitIf}` albo zostanie przerwane wyjątkiem, więc to właściwe miejsce na sprzątanie lub pomiary.
getFilters(): array .[method]
-----------------------------
Wywoływana przy rejestracji rozszerzenia metodą `addExtension()`. Zwraca filtry jako tablicę asocjacyjną *nazwa filtra => callable*. [Dowiedz się więcej|custom-filters].
```php
public function getFilters(): array
{
return [
'batch' => $this->batchFilter(...),
'trim' => $this->trimFilter(...),
// ...
];
}
```
getFunctions(): array .[method]
-------------------------------
Wywoływana przy rejestracji rozszerzenia metodą `addExtension()`. Zwraca funkcje jako tablicę asocjacyjną *nazwa funkcji => callable*. [Dowiedz się więcej|custom-functions].
```php
public function getFunctions(): array
{
return [
'clamp' => $this->clampFunction(...),
'divisibleBy' => $this->divisibleByFunction(...),
// ...
];
}
```
getProviders(): array .[method]
-------------------------------
Wywoływana przy rejestracji rozszerzenia metodą `addExtension()`. Zwraca tablicę providerów, czyli zwykle obiektów, których tagi używają w czasie działania. Sięga się po nie przez `$this->global->...`. [Dowiedz się więcej |custom-tags#Poznaj providery].
```php
public function getProviders(): array
{
return [
'myFoo' => $this->foo,
'myBar' => $this->bar,
// ...
];
}
```
getCacheKey(Latte\Engine $engine): mixed .[method]
--------------------------------------------------
Wywoływana przed wyrenderowaniem szablonu. Wartość zwracana staje się częścią klucza, którego hash zawiera się w nazwie pliku skompilowanego szablonu. Dla różnych wartości zwracanych Latte wygeneruje więc różne pliki cache.
Rozszerzanie Latte
Latte zostało zaprojektowane z myślą o rozszerzalności. Choć jego standardowy zestaw tagów, filtrów
i funkcji pokrywa wiele zastosowań, często trzeba dodać własną logikę lub pomocniki. Ta strona daje przegląd tego, jak
rozszerzyć Latte, aby idealnie pasowało do wymagań Twojego projektu, od prostych pomocników po złożoną nową
składnię.
Sposoby rozszerzania Latte
Oto szybki przegląd głównych sposobów dostosowywania i rozszerzania Latte:
- Własne filtry: do formatowania lub przekształcania danych
bezpośrednio w wyniku szablonu (np.
{$var|myFilter}). Idealne do zadań takich jak formatowanie dat, operacje na
tekście czy zastosowanie konkretnego escapowania. Możesz ich użyć również do modyfikowania większych bloków treści HTML,
opakowując treść w anonimowy {block} i stosując
własny filtr.
- Własne funkcje: do dodawania logiki wielokrotnego użytku,
którą można wywoływać w wyrażeniach szablonu (np.
{myFunction($arg1, $arg2)}). Przydatne do obliczeń,
sięgania po pomocniki aplikacji albo generowania niewielkich fragmentów treści.
- Własne tagi: do tworzenia zupełnie nowych konstrukcji
językowych (
{mytag}...{/mytag} albo n:mytag). Tagi dają największe możliwości: pozwalają
definiować własne struktury, sterować parsowaniem szablonu i implementować złożoną logikę renderowania.
- Compiler passy: funkcje modyfikujące drzewo składniowe (AST)
szablonu po parsowaniu, ale przed wygenerowaniem kodu PHP. Używane do zaawansowanych optymalizacji, kontroli bezpieczeństwa (jak
Sandbox) czy automatycznych modyfikacji kodu.
- Własne loadery: do zmiany sposobu, w jaki Latte znajduje i wczytuje
pliki szablonów (np. wczytywanie z bazy danych, z zaszyfrowanego magazynu itd.).
Wybór właściwego sposobu rozszerzenia jest kluczowy. Zanim stworzysz złożony tag, zastanów się, czy nie wystarczy
prostszy filtr albo funkcja. Zilustrujmy to przykładem: implementacją generatora Lorem ipsum, który jako argument
przyjmuje liczbę słów do wygenerowania.
- Jako tag?
{lipsum 40} – możliwe, ale tagi lepiej nadają się do struktur sterujących albo
generowania złożonego markupu. Tagów nie da się użyć bezpośrednio w wyrażeniach.
- Jako filtr?
{=40|lipsum} – technicznie działa, ale filtry mają przekształcać wejście. Tutaj
40 to argument, a nie przekształcana wartość. Semantycznie to nie brzmi dobrze.
- Jako funkcja?
{lipsum(40)} – to najbardziej naturalne rozwiązanie! Funkcje przyjmują argumenty
i zwracają wartości, więc doskonale nadają się do użycia w dowolnym wyrażeniu:
{var $text = lipsum(40)}.
Ogólna wskazówka: funkcji używaj do obliczeń i generowania, filtrów do przekształcania, a tagów do nowych
struktur językowych albo złożonego markupu. Passów używaj do manipulacji AST, a loaderów do pobierania szablonów.
Bezpośrednia rejestracja
Do pomocników specyficznych dla projektu albo szybkich dodatków Latte pozwala rejestrować filtry i funkcje bezpośrednio na
obiekcie Latte\Engine.
Do zarejestrowania filtra użyj addFilter(). Pierwszym argumentem funkcji filtra będzie wartość przed potokiem
|, a kolejnymi te podane po dwukropku :.
$latte = new Latte\Engine;
// definicja filtra (callable: funkcja, metoda statyczna itd.)
$myTruncate = fn(string $s, int $length = 50) => mb_substr($s, 0, $length);
// rejestracja
$latte->addFilter('truncate', $myTruncate);
// użycie w szablonie: {$text|truncate} albo {$text|truncate:100}
Do zarejestrowania funkcji używalnej w wyrażeniach szablonu użyj addFunction().
$latte = new Latte\Engine;
// definicja funkcji
$isWeekend = fn(DateTimeInterface $date) => $date->format('N') >= 6;
// rejestracja
$latte->addFunction('isWeekend', $isWeekend);
// użycie w szablonie: {if isWeekend($myDate)}Weekend!{/if}
Więcej szczegółów znajdziesz w Tworzenie własnych filtrów i Funkcje.
Robustny sposób: Latte Extension
Bezpośrednia rejestracja jest prosta, ale standardowym i zalecanym sposobem grupowania i dystrybucji rozszerzeń Latte są
klasy rozszerzeń. Rozszerzenie działa jak centralny punkt konfiguracji do rejestrowania wielu tagów, filtrów, funkcji,
compiler passów i innych rzeczy.
Po co używać rozszerzeń?
- Organizacja: trzyma powiązane rozszerzenia (tagi, filtry itd. dla konkretnej funkcjonalności) razem w jednej
klasie.
- Ponowne użycie i udostępnianie: łatwo spakujesz swoje rozszerzenia do użytku w innych projektach albo do
udostępnienia społeczności (np. przez Composera).
- Pełne możliwości: własne tagi i compiler passy można zarejestrować wyłącznie przez rozszerzenia.
Rejestracja rozszerzenia
Rozszerzenie rejestruje się w Latte metodą addExtension() (albo przez plik konfiguracyjny):
$latte = new Latte\Engine;
$latte->addExtension(new MyProjectExtension);
Jeśli zarejestrujesz kilka rozszerzeń, a definiują one tagi, filtry albo funkcje o tych samych nazwach, wygrywa
rozszerzenie dodane jako ostatnie. Wynika z tego również, że Twoje rozszerzenia mogą nadpisywać natywne tagi, filtry
i funkcje.
Za każdym razem, gdy zmienisz klasę, a automatyczne odświeżanie nie jest wyłączone, Latte samo przekompiluje Twoje
szablony.
Tworzenie rozszerzenia
Aby utworzyć własne rozszerzenie, musisz stworzyć klasę dziedziczącą po Latte\Extension. Aby wyrobić sobie pogląd, jak takie
rozszerzenie wygląda, zajrzyj do wbudowanego CoreExtension.
Zobaczmy, jakie metody możesz zaimplementować:
beforeCompile (Latte\Engine
$engine): void
Wywoływana przed skompilowaniem szablonu. Metody można użyć na przykład do inicjalizacji związanych z kompilacją.
Wywoływana przy kompilacji szablonu. Zwraca tablicę asocjacyjną nazwa tagu ⇒ callable, czyli funkcje parsujące
tagi. Dowiedz się więcej.
public function getTags(): array
{
return [
'foo' => FooNode::create(...),
'bar' => BarNode::create(...),
'n:baz' => NBazNode::create(...),
// ...
];
}
Tag n:baz reprezentuje czysty n:atrybut, czyli tag,
który można zapisać wyłącznie jako atrybut.
W przypadku tagów foo i bar Latte automatycznie rozpozna, czy są parzyste, a jeśli tak, można
je automatycznie zapisywać za pomocą n:atrybutów, łącznie z wariantami z prefiksami n:inner-foo i
n:tag-foo.
Kolejność wykonywania takich n:atrybutów wynika z ich kolejności w tablicy zwracanej przez getTags().
Dlatego n:foo jest zawsze wykonywany przed n:bar, nawet jeśli atrybuty są podane w tagu HTML
w odwrotnej kolejności jako <div n:bar="..." n:foo="...">.
Jeśli potrzebujesz ustalić kolejność n:atrybutów pochodzących z różnych rozszerzeń, użyj metody pomocniczej
order(), w której parametr before i/lub after określa, które tagi mają być
uporządkowane przed danym tagiem lub po nim.
public function getTags(): array
{
return [
'foo' => self::order(FooNode::create(...), before: 'bar'),
'bar' => self::order(BarNode::create(...), after: ['block', 'snippet']),
];
}
getPasses(): array
Wywoływana przy kompilacji szablonu. Zwraca tablicę asocjacyjną nazwa passu ⇒ callable, czyli funkcje
reprezentujące tzw. compiler passy, które przechodzą przez AST i je
modyfikują.
Także tutaj można użyć metody pomocniczej order(). Wartością parametrów before albo
after może być * w znaczeniu przed wszystkimi / po wszystkich.
public function getPasses(): array
{
return [
'optimize' => Passes::optimizePass(...),
'sandbox' => self::order($this->sandboxPass(...), before: '*'),
// ...
];
}
beforeRender (Latte\Runtime\Template
$template): void
Wywoływana przed każdym renderowaniem szablonu. Metody można użyć na przykład do zainicjowania zmiennych używanych
podczas renderowania.
afterRender (Latte\Runtime\Template $template): void
Wywoływana po każdym renderowaniu szablonu. Uruchamia się nawet wtedy, gdy renderowanie zakończy się wcześniej przez
{exitIf} albo zostanie przerwane wyjątkiem, więc to właściwe miejsce na sprzątanie lub pomiary.
getFilters(): array
Wywoływana przy rejestracji rozszerzenia metodą addExtension(). Zwraca filtry jako tablicę asocjacyjną
nazwa filtra ⇒ callable. Dowiedz się więcej.
public function getFilters(): array
{
return [
'batch' => $this->batchFilter(...),
'trim' => $this->trimFilter(...),
// ...
];
}
getFunctions(): array
Wywoływana przy rejestracji rozszerzenia metodą addExtension(). Zwraca funkcje jako tablicę asocjacyjną
nazwa funkcji ⇒ callable. Dowiedz się więcej.
public function getFunctions(): array
{
return [
'clamp' => $this->clampFunction(...),
'divisibleBy' => $this->divisibleByFunction(...),
// ...
];
}
getProviders(): array
Wywoływana przy rejestracji rozszerzenia metodą addExtension(). Zwraca tablicę providerów, czyli zwykle
obiektów, których tagi używają w czasie działania. Sięga się po nie przez $this->global->.... Dowiedz się więcej.
public function getProviders(): array
{
return [
'myFoo' => $this->foo,
'myBar' => $this->bar,
// ...
];
}
getCacheKey (Latte\Engine $engine): mixed
Wywoływana przed wyrenderowaniem szablonu. Wartość zwracana staje się częścią klucza, którego hash zawiera się
w nazwie pliku skompilowanego szablonu. Dla różnych wartości zwracanych Latte wygeneruje więc różne pliki cache.