Szablony
********
.[perex]
Nette używa systemu szablonów [Latte |latte:]. Latte jest używane, bo to najbezpieczniejszy system szablonów dla PHP, a zarazem najbardziej intuicyjny. Nie musisz uczyć się wiele nowego; wystarczy znajomość PHP i kilku tagów.
Powszechnie strona składa się z szablonu layoutu i szablonu konkretnej akcji. Tak może wyglądać szablon layoutu; zwróć uwagę na bloki `{block}` i tag `{include}`:
```latte
<!DOCTYPE html>
<html>
<head>
<title>{block title}Moja aplikacja{/block}</title>
</head>
<body>
<header>...</header>
{include content}
<footer>...</footer>
</body>
</html>
```
A tak wyglądałby szablon akcji:
```latte
{block title}Strona główna{/block}
{block content}
<h1>Strona główna</h1>
...
{/block}
```
Definiuje on blok `content`, który wstawiany jest w layoucie w miejsce `{include content}`, a także na nowo definiuje blok `title`, który nadpisuje `{block title}` w layoucie. Spróbuj wyobrazić sobie wynik.
Wyszukiwanie szablonów
----------------------
W presenterach nie musisz podawać, który szablon ma zostać wyrenderowany; framework sam wywnioskuje ścieżkę, oszczędzając Ci pisania.
Jeśli używasz struktury katalogów, w której każdy presenter ma własny katalog, po prostu umieść szablon w tym katalogu pod nazwą akcji (czyli widoku). Na przykład dla akcji `default` użyj szablonu `default.latte`:
/--pre
app/
└── Presentation/
└── Home/
├── HomePresenter.php
└── <b>default.latte</b>
\--
Jeśli używasz struktury, w której presentery leżą razem w jednym katalogu, a szablony w folderze `templates`, zapisz go albo w pliku `<Presenter>.<widok>.latte`, albo `<Presenter>/<widok>.latte`:
/--pre
app/
└── Presenters/
├── HomePresenter.php
└── templates/
├── <b>Home/</b>
│ └── <b>default.latte</b> ← 1. wariant
└── <b>Home.default.latte</b> ← 2. wariant
\--
Katalog `templates` może leżeć też o poziom wyżej, czyli na tym samym poziomie co katalog z klasami presenterów.
Jeśli szablon się nie znajdzie, presenter odpowiada [błędem 404 - strona nie znaleziona |presenters#Błąd 404 itd.].
Widok możesz zmienić przez `$this->setView('otherView')`. Można też bezpośrednio wskazać plik szablonu przez `$this->template->setFile('/path/to/template.latte')`.
.[note]
Pliki, w których wyszukiwane są szablony, można zmienić, nadpisując metodę [formatTemplateFiles() |api:Nette\Application\UI\Presenter::formatTemplateFiles()], która zwraca tablicę możliwych nazw plików.
Wyszukiwanie szablonu layoutu
-----------------------------
Nette automatycznie wyszukuje również plik layoutu.
Jeśli używasz struktury katalogów, w której każdy presenter ma własny katalog, umieść layout albo w folderze z presenterem, jeśli jest przeznaczony tylko dla niego, albo o poziom wyżej, jeśli jest wspólny dla kilku presenterów:
/--pre
app/
└── Presentation/
├── <b>@layout.latte</b> ← wspólny layout
└── Home/
├── <b>@layout.latte</b> ← tylko dla presentera Home
├── HomePresenter.php
└── default.latte
\--
Jeśli używasz struktury, w której presentery zgrupowane są w jednym katalogu, a szablony w folderze `templates`, layout będzie oczekiwany w tych miejscach:
/--pre
app/
└── Presenters/
├── HomePresenter.php
└── templates/
├── <b>@layout.latte</b> ← wspólny layout
├── <b>Home/</b>
│ └── <b>@layout.latte</b> ← tylko dla Home, 1. wariant
└── <b>Home.@layout.latte</b> ← tylko dla Home, 2. wariant
\--
Jeśli presenter leży w module, wyszukiwanie postępuje też wyżej po poziomach katalogów, zgodnie z zagnieżdżeniem modułów.
Nazwę layoutu można zmienić przez `$this->setLayout('layoutAdmin')`, a wtedy będzie oczekiwany w pliku `@layoutAdmin.latte`. Możesz też bezpośrednio wskazać plik szablonu layoutu przez `$this->setLayout('/path/to/template.latte')`.
Użycie `$this->setLayout(false)` albo tagu `{layout none}` wewnątrz szablonu wyłącza wyszukiwanie layoutu.
.[note]
Pliki, w których wyszukiwane są szablony layoutu, można zmienić, nadpisując metodę [formatLayoutTemplateFiles() |api:Nette\Application\UI\Presenter::formatLayoutTemplateFiles()], która zwraca tablicę możliwych nazw plików.
Zmienne szablonu
----------------
Zmienne przekazuje się do szablonów, zapisując je do `$this->template`. Stają się wtedy dostępne w szablonie jako zmienne lokalne:
```php
$this->template->article = $this->articles->getById($id);
```
Aby wartość właściwości była automatycznie przekazywana do szablonu jako zmienna, oznacz ją atrybutem `#[TemplateVariable]` i widocznością public: .{data-version:3.2.9}
```php
use Nette\Application\Attributes\TemplateVariable;
class ArticlePresenter extends Nette\Application\UI\Presenter
{
#[TemplateVariable]
public string $siteName = 'Mój blog';
}
```
Jeśli przekażesz do szablonu zmienną o tej samej nazwie, `#[TemplateVariable]` jej nie nadpisze.
Zmienne domyślne
----------------
Presentery i komponenty automatycznie przekazują do szablonów kilka przydatnych zmiennych:
- `$basePath` to bezwzględna ścieżka URL do katalogu głównego (np. `/eshop`)
- `$baseUrl` to bezwzględny URL katalogu głównego (np. `http://localhost/eshop`)
- `$user` to obiekt [reprezentujący użytkownika |security:authentication]
- `$presenter` to bieżący presenter
- `$control` to bieżący komponent albo presenter
- `$flashes` to tablica [wiadomości |presenters#Wiadomości flash] wysłanych funkcją `flashMessage()`
Jeśli używasz własnej klasy szablonu, zmienne te są przekazywane, o ile utworzysz dla nich właściwość.
Szablony bezpieczne typowo
--------------------------
Przy tworzeniu solidnych aplikacji przydaje się jawne określenie, jakich zmiennych oczekuje szablon i jakich są typów. Daje to kontrolę typów w PHP, inteligentne podpowiedzi w IDE i pozwala analizie statycznej wyłapywać błędy.
Jak zdefiniować taką listę? Po prostu jako klasę z właściwościami reprezentującymi zmienne szablonu. Nazwij ją podobnie jak presenter, tylko z `Template` na końcu:
```php
/**
* @property-read ArticleTemplate $template
*/
class ArticlePresenter extends Nette\Application\UI\Presenter
{
}
class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
{
public Model\Article $article;
public Nette\Security\User $user;
// i inne zmienne
}
```
Obiekt `$this->template` w presenterze będzie teraz instancją klasy `ArticleTemplate`. PHP będzie więc przy zapisie sprawdzać zadeklarowane typy.
Nette wybiera klasę szablonu automatycznie. Najpierw szuka klasy o nazwie `<Presenter><Akcja>Template`, np. `ArticleEditTemplate` dla akcji `edit`, i dopiero gdy jej nie ma, sięga po `<Presenter>Template`.
Adnotacja `@property-read` przeznaczona jest dla IDE i analizy statycznej, umożliwia uzupełnianie kodu, zobacz "PhpStorm i uzupełnianie kodu dla $this->template":https://blog.nette.org/en/phpstorm-and-code-completion-for-this-template.
[* phpstorm-completion.webp *]
Uzupełniania kodu możesz używać również bezpośrednio w szablonach. Wystarczy zainstalować plugin Latte do PhpStorm i podać na początku szablonu nazwę klasy parametrów szablonu, więcej w rozdziale [Latte: system typów |latte:type-system]:
```latte
{templateType App\Presentation\Article\ArticleTemplate}
...
```
To samo dotyczy komponentów. Wystarczy trzymać się konwencji nazewniczej i dla komponentu w rodzaju `FifteenControl` utworzyć klasę parametrów `FifteenTemplate`.
Jeśli potrzebujesz użyć innej klasy parametrów, skorzystaj z metody `createTemplate()`:
```php
public function renderDefault(): void
{
$template = $this->createTemplate(SpecialTemplate::class);
$template->foo = 123;
// ...
$this->sendTemplate($template);
}
```
.{data-version:3.3.0}
Jeśli potrzebujesz wpłynąć na to, jak szablon jest finalizowany przed renderowaniem, na przykład aby dodać zmienne wspólne dla wszystkich akcji, możesz nadpisać w presenterze metodę `completeTemplate()`. Wywoływana jest tuż przed wyrenderowaniem szablonu:
```php
protected function completeTemplate(Nette\Application\UI\Template $template): void
{
parent::completeTemplate($template);
$template->siteName = 'Mój blog';
}
```
Tworzenie odnośników
--------------------
W szablonie odnośniki do innych presenterów i akcji tworzy się tak:
```latte
<a n:href="Product:show">szczegóły produktu</a>
```
Atrybut `n:href` jest bardzo poręczny dla tagów HTML `<a>`. Jeśli chcemy wypisać odnośnik gdzie indziej, na przykład w tekście, użyjemy `{link}`:
```latte
URL to: {link Home:default}
```
Więcej informacji znajdziesz w rozdziale [Tworzenie odnośników URL|creating-links].
Własne filtry, tagi itd.
------------------------
System szablonów Latte można rozszerzać o własne filtry, funkcje, tagi i inne elementy. Dostępne są trzy podejścia, od szybkich rozwiązań doraźnych po wzorce architektoniczne dla całych aplikacji.
**Doraźnie w metodach presentera**
Najszybszym podejściem jest dodawanie filtrów albo funkcji bezpośrednio w kodzie presentera lub komponentu. W presenterach dobrze nadają się do tego metody `beforeRender()` albo `render<Widok>()`:
```php
protected function beforeRender(): void
{
// dodanie filtra
$this->template->addFilter('money', fn($val) => '$' . number_format($val, 2));
// dodanie funkcji
$this->template->addFunction('isWeekend', fn($date) => $date->format('N') >= 6);
}
```
W szablonie:
```latte
<p>Cena: {$price|money}</p>
{if isWeekend($now)} ... {/if}
```
Przy bardziej złożonej logice możesz skonfigurować bezpośrednio obiekt `Latte\Engine`:
```php
protected function beforeRender(): void
{
$latte = $this->template->getLatte();
$latte->setFeature(Latte\Feature::MigrationWarnings);
}
```
**Za pomocą atrybutów**
Eleganckim podejściem jest zdefiniowanie filtrów i funkcji jako metod bezpośrednio w [klasie parametrów szablonu|#Szablony bezpieczne typowo] presentera albo komponentu, oznaczonych atrybutami:
```php
class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
{
#[Latte\Attributes\TemplateFilter]
public function money(float $val): string
{
return '$' . number_format($val, 2);
}
#[Latte\Attributes\TemplateFunction]
public function isWeekend(DateTimeInterface $date): bool
{
return $date->format('N') >= 6;
}
}
```
Latte automatycznie odnajduje i rejestruje metody oznaczone tymi atrybutami. Nazwa filtra albo funkcji w szablonach odpowiada nazwie metody. Metody te muszą być publiczne.
**Globalnie za pomocą rozszerzeń**
Poprzednie podejścia nadają się do filtrów i funkcji potrzebnych tylko w konkretnych presenterach albo komponentach, a nie w całej aplikacji. Dla całej aplikacji najlepiej sprawdza się utworzenie [rozszerzenia |latte:extending-latte#Latte Extension]. Klasa ta centralizuje wszystkie rozszerzenia Latte w Twoim projekcie. Krótki przykład:
```php
namespace App\Presentation\Accessory;
final class LatteExtension extends Latte\Extension
{
public function __construct(
private App\Model\Facade $facade,
private Nette\Security\User $user,
// ...
) {
}
public function getFilters(): array
{
return [
'timeAgoInWords' => $this->filterTimeAgoInWords(...),
'money' => $this->filterMoney(...),
// ...
];
}
public function getFunctions(): array
{
return [
'canEditArticle' =>
fn($article) => $this->facade->canEditArticle($article, $this->user->getId()),
// ...
];
}
private function filterTimeAgoInWords(DateTimeInterface $time): string
{
// ...
}
// ...
}
```
Rozszerzenie zarejestrujesz przez [konfigurację |configuration#Szablony Latte]:
```neon
latte:
extensions:
- App\Presentation\Accessory\LatteExtension
```
Rozszerzenia dają kilka korzyści: wsparcie dla wstrzykiwania zależności, dostęp do warstwy modelu Twojej aplikacji i centralne zarządzanie wszystkimi rozszerzeniami. Obsługują też własne tagi, providery, compiler passy i inne rzeczy.
Ustawienie wszystkich szablonów
-------------------------------
Usługa `TemplateFactory`, która tworzy wszystkie szablony, oferuje publiczną tablicę callbacków `$onCreate`. Wywoływane są one przy każdym utworzeniu dowolnego szablonu, dzięki czemu z jednego miejsca ustawisz filtry, funkcje albo zmienne dla wszystkich szablonów w aplikacji. Każdy callback otrzymuje nowo utworzony szablon. Każ sobie [wstrzyknąć |dependency-injection:passing-dependencies] usługę `TemplateFactory` i zarejestruj callbacki, np. przy starcie aplikacji:
```php
$templateFactory->onCreate[] = function (Nette\Bridges\ApplicationLatte\Template $template): void {
$template->addFilter('money', fn($val) => '$' . number_format($val, 2));
};
```
Tłumaczenie
-----------
Jeśli programujesz aplikację wielojęzyczną, prawdopodobnie będziesz potrzebować wypisywać w szablonie niektóre teksty w różnych językach. Nette Framework definiuje w tym celu interfejs tłumaczenia [api:Nette\Localization\Translator], który ma jedną metodę `translate()`. Przyjmuje ona komunikat `$message`, którym zwykle jest string, oraz dowolne inne parametry. Zadaniem jest zwrócenie przetłumaczonego stringa. Nette nie ma domyślnej implementacji; możesz wybrać z kilku gotowych rozwiązań dostępnych na [Componette |https://componette.org/search/localization] według swoich potrzeb. Ich dokumentacja wyjaśnia, jak skonfigurować translator.
Szablonom można ustawić translator, który [otrzymamy wstrzyknięty |dependency-injection:passing-dependencies], metodą `setTranslator()`:
```php
protected function beforeRender(): void
{
// ...
$this->template->setTranslator($translator);
}
```
Alternatywnie translator można ustawić przez [konfigurację |configuration#Szablony Latte]:
```neon
latte:
extensions:
- Latte\Essential\TranslatorExtension(@Nette\Localization\Translator)
```
Translatora można potem używać na przykład jako filtra `|translate`, wraz z dodatkowymi parametrami przekazywanymi do metody `translate()` (zobacz `foo, bar`):
```latte
<a href="basket">{='Koszyk'|translate}</a>
<span>{$item|translate}</span>
<span>{$item|translate, foo, bar}</span>
```
Albo jako tagu z podkreśleniem:
```latte
<a href="basket">{_'Koszyk'}</a>
<span>{_$item}</span>
<span>{_$item, foo, bar}</span>
```
Do przetłumaczenia fragmentu szablonu służy tag parzysty `{translate}` (od Latte 2.11, wcześniej używano tagu `{_}`):
```latte
<a href="order">{translate}Zamów{/translate}</a>
<a href="order">{translate foo, bar}Zamów{/translate}</a>
```
Translator wywoływany jest normalnie w czasie działania, przy renderowaniu szablonu. Latte w wersji 3 potrafi jednak przetłumaczyć wszystkie teksty statyczne już podczas kompilacji szablonu. Oszczędza to wydajność, bo każdy string tłumaczony jest tylko raz, a powstałe tłumaczenie zapisywane jest do skompilowanej postaci. W katalogu cache powstaje wtedy kilka skompilowanych wersji szablonu, po jednej na język. Wystarczy do tego podać język jako drugi parametr:
```php
protected function beforeRender(): void
{
// ...
$this->template->setTranslator($translator, $lang);
}
```
Przez tekst statyczny rozumiemy na przykład `{_'hello'}` albo `{translate}hello{/translate}`. Teksty niestatyczne, jak `{_$foo}`, nadal będą tłumaczone w czasie działania.
Szablony
Nette używa systemu szablonów Latte. Latte jest używane, bo to
najbezpieczniejszy system szablonów dla PHP, a zarazem najbardziej intuicyjny. Nie musisz uczyć się wiele nowego; wystarczy
znajomość PHP i kilku tagów.
Powszechnie strona składa się z szablonu layoutu i szablonu konkretnej akcji. Tak może wyglądać szablon layoutu; zwróć
uwagę na bloki {block} i tag {include}:
Definiuje on blok content, który wstawiany jest w layoucie w miejsce {include content}, a także
na nowo definiuje blok title, który nadpisuje {block title} w layoucie. Spróbuj wyobrazić
sobie wynik.
Wyszukiwanie szablonów
W presenterach nie musisz podawać, który szablon ma zostać wyrenderowany; framework sam wywnioskuje ścieżkę,
oszczędzając Ci pisania.
Jeśli używasz struktury katalogów, w której każdy presenter ma własny katalog, po prostu umieść szablon w tym
katalogu pod nazwą akcji (czyli widoku). Na przykład dla akcji default użyj szablonu
default.latte:
Jeśli używasz struktury, w której presentery leżą razem w jednym katalogu, a szablony w folderze
templates, zapisz go albo w pliku <Presenter>.<widok>.latte, albo
<Presenter>/<widok>.latte:
Widok możesz zmienić przez $this->setView('otherView'). Można też bezpośrednio wskazać plik szablonu
przez $this->template->setFile('/path/to/template.latte').
Pliki, w których wyszukiwane są szablony, można zmienić, nadpisując metodę formatTemplateFiles(),
która zwraca tablicę możliwych nazw plików.
Wyszukiwanie szablonu layoutu
Nette automatycznie wyszukuje również plik layoutu.
Jeśli używasz struktury katalogów, w której każdy presenter ma własny katalog, umieść layout albo w folderze
z presenterem, jeśli jest przeznaczony tylko dla niego, albo o poziom wyżej, jeśli jest wspólny dla kilku presenterów:
app/
└── Presentation/
├── @layout.latte ← wspólny layout
└── Home/
├── @layout.latte ← tylko dla presentera Home
├── HomePresenter.php
└── default.latte
Jeśli używasz struktury, w której presentery zgrupowane są w jednym katalogu, a szablony w folderze
templates, layout będzie oczekiwany w tych miejscach:
app/
└── Presenters/
├── HomePresenter.php
└── templates/
├── @layout.latte ← wspólny layout
├── Home/
│ └── @layout.latte ← tylko dla Home, 1. wariant
└── Home.@layout.latte ← tylko dla Home, 2. wariant
Jeśli presenter leży w module, wyszukiwanie postępuje też wyżej po poziomach katalogów, zgodnie z zagnieżdżeniem
modułów.
Nazwę layoutu można zmienić przez $this->setLayout('layoutAdmin'), a wtedy będzie oczekiwany w pliku
@layoutAdmin.latte. Możesz też bezpośrednio wskazać plik szablonu layoutu przez
$this->setLayout('/path/to/template.latte').
Użycie $this->setLayout(false) albo tagu {layout none} wewnątrz szablonu wyłącza wyszukiwanie
layoutu.
Pliki, w których wyszukiwane są szablony layoutu, można zmienić, nadpisując metodę formatLayoutTemplateFiles(),
która zwraca tablicę możliwych nazw plików.
Zmienne szablonu
Zmienne przekazuje się do szablonów, zapisując je do $this->template. Stają się wtedy dostępne
w szablonie jako zmienne lokalne:
Aby wartość właściwości była automatycznie przekazywana do szablonu jako zmienna, oznacz ją
atrybutem #[TemplateVariable] i widocznością public:
use Nette\Application\Attributes\TemplateVariable;
class ArticlePresenter extends Nette\Application\UI\Presenter
{
#[TemplateVariable]
public string $siteName = 'Mój blog';
}
Jeśli przekażesz do szablonu zmienną o tej samej nazwie, #[TemplateVariable] jej nie nadpisze.
Zmienne domyślne
Presentery i komponenty automatycznie przekazują do szablonów kilka przydatnych zmiennych:
$basePath to bezwzględna ścieżka URL do katalogu głównego (np. /eshop)
$baseUrl to bezwzględny URL katalogu głównego (np. http://localhost/eshop)
$flashes to tablica wiadomości wysłanych funkcją
flashMessage()
Jeśli używasz własnej klasy szablonu, zmienne te są przekazywane, o ile utworzysz dla nich właściwość.
Szablony bezpieczne typowo
Przy tworzeniu solidnych aplikacji przydaje się jawne określenie, jakich zmiennych oczekuje szablon i jakich są typów.
Daje to kontrolę typów w PHP, inteligentne podpowiedzi w IDE i pozwala analizie statycznej wyłapywać błędy.
Jak zdefiniować taką listę? Po prostu jako klasę z właściwościami reprezentującymi zmienne szablonu. Nazwij ją
podobnie jak presenter, tylko z Template na końcu:
/**
* @property-read ArticleTemplate $template
*/
class ArticlePresenter extends Nette\Application\UI\Presenter
{
}
class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
{
public Model\Article $article;
public Nette\Security\User $user;
// i inne zmienne
}
Obiekt $this->template w presenterze będzie teraz instancją klasy ArticleTemplate. PHP będzie
więc przy zapisie sprawdzać zadeklarowane typy.
Nette wybiera klasę szablonu automatycznie. Najpierw szuka klasy o nazwie
<Presenter><Akcja>Template, np. ArticleEditTemplate dla akcji edit, i dopiero
gdy jej nie ma, sięga po <Presenter>Template.
Uzupełniania kodu możesz używać również bezpośrednio w szablonach. Wystarczy zainstalować plugin Latte do PhpStorm
i podać na początku szablonu nazwę klasy parametrów szablonu, więcej w rozdziale Latte: system typów:
To samo dotyczy komponentów. Wystarczy trzymać się konwencji nazewniczej i dla komponentu w rodzaju
FifteenControl utworzyć klasę parametrów FifteenTemplate.
Jeśli potrzebujesz użyć innej klasy parametrów, skorzystaj z metody createTemplate():
public function renderDefault(): void
{
$template = $this->createTemplate(SpecialTemplate::class);
$template->foo = 123;
// ...
$this->sendTemplate($template);
}
Jeśli potrzebujesz wpłynąć na to, jak szablon jest finalizowany przed renderowaniem, na przykład aby
dodać zmienne wspólne dla wszystkich akcji, możesz nadpisać w presenterze metodę completeTemplate().
Wywoływana jest tuż przed wyrenderowaniem szablonu:
System szablonów Latte można rozszerzać o własne filtry, funkcje, tagi i inne elementy. Dostępne są trzy podejścia, od
szybkich rozwiązań doraźnych po wzorce architektoniczne dla całych aplikacji.
Doraźnie w metodach presentera
Najszybszym podejściem jest dodawanie filtrów albo funkcji bezpośrednio w kodzie presentera lub komponentu. W presenterach
dobrze nadają się do tego metody beforeRender() albo render<Widok>():
Przy bardziej złożonej logice możesz skonfigurować bezpośrednio obiekt Latte\Engine:
protected function beforeRender(): void
{
$latte = $this->template->getLatte();
$latte->setFeature(Latte\Feature::MigrationWarnings);
}
Za pomocą atrybutów
Eleganckim podejściem jest zdefiniowanie filtrów i funkcji jako metod bezpośrednio w klasie parametrów szablonu presentera albo komponentu, oznaczonych atrybutami:
class ArticleTemplate extends Nette\Bridges\ApplicationLatte\Template
{
#[Latte\Attributes\TemplateFilter]
public function money(float $val): string
{
return '$' . number_format($val, 2);
}
#[Latte\Attributes\TemplateFunction]
public function isWeekend(DateTimeInterface $date): bool
{
return $date->format('N') >= 6;
}
}
Latte automatycznie odnajduje i rejestruje metody oznaczone tymi atrybutami. Nazwa filtra albo funkcji w szablonach odpowiada
nazwie metody. Metody te muszą być publiczne.
Globalnie za pomocą rozszerzeń
Poprzednie podejścia nadają się do filtrów i funkcji potrzebnych tylko w konkretnych presenterach albo komponentach,
a nie w całej aplikacji. Dla całej aplikacji najlepiej sprawdza się utworzenie rozszerzenia. Klasa ta centralizuje wszystkie
rozszerzenia Latte w Twoim projekcie. Krótki przykład:
namespace App\Presentation\Accessory;
final class LatteExtension extends Latte\Extension
{
public function __construct(
private App\Model\Facade $facade,
private Nette\Security\User $user,
// ...
) {
}
public function getFilters(): array
{
return [
'timeAgoInWords' => $this->filterTimeAgoInWords(...),
'money' => $this->filterMoney(...),
// ...
];
}
public function getFunctions(): array
{
return [
'canEditArticle' =>
fn($article) => $this->facade->canEditArticle($article, $this->user->getId()),
// ...
];
}
private function filterTimeAgoInWords(DateTimeInterface $time): string
{
// ...
}
// ...
}
Rozszerzenia dają kilka korzyści: wsparcie dla wstrzykiwania zależności, dostęp do warstwy modelu Twojej aplikacji
i centralne zarządzanie wszystkimi rozszerzeniami. Obsługują też własne tagi, providery, compiler passy i inne rzeczy.
Ustawienie wszystkich szablonów
Usługa TemplateFactory, która tworzy wszystkie szablony, oferuje publiczną tablicę callbacków
$onCreate. Wywoływane są one przy każdym utworzeniu dowolnego szablonu, dzięki czemu z jednego miejsca ustawisz
filtry, funkcje albo zmienne dla wszystkich szablonów w aplikacji. Każdy callback otrzymuje nowo utworzony szablon. Każ sobie
wstrzyknąć usługę
TemplateFactory i zarejestruj callbacki, np. przy starcie aplikacji:
Jeśli programujesz aplikację wielojęzyczną, prawdopodobnie będziesz potrzebować wypisywać w szablonie niektóre teksty
w różnych językach. Nette Framework definiuje w tym celu interfejs tłumaczenia Nette\Localization\Translator, który ma jedną
metodę translate(). Przyjmuje ona komunikat $message, którym zwykle jest string, oraz dowolne inne
parametry. Zadaniem jest zwrócenie przetłumaczonego stringa. Nette nie ma domyślnej implementacji; możesz wybrać z kilku
gotowych rozwiązań dostępnych na Componette według swoich potrzeb.
Ich dokumentacja wyjaśnia, jak skonfigurować translator.
Szablonom można ustawić translator, który otrzymamy wstrzyknięty, metodą
setTranslator():
protected function beforeRender(): void
{
// ...
$this->template->setTranslator($translator);
}
Alternatywnie translator można ustawić przez konfigurację:
Translatora można potem używać na przykład jako filtra |translate, wraz z dodatkowymi parametrami
przekazywanymi do metody translate() (zobacz foo, bar):
Translator wywoływany jest normalnie w czasie działania, przy renderowaniu szablonu. Latte w wersji 3 potrafi jednak
przetłumaczyć wszystkie teksty statyczne już podczas kompilacji szablonu. Oszczędza to wydajność, bo każdy string
tłumaczony jest tylko raz, a powstałe tłumaczenie zapisywane jest do skompilowanej postaci. W katalogu cache powstaje wtedy
kilka skompilowanych wersji szablonu, po jednej na język. Wystarczy do tego podać język jako drugi parametr:
protected function beforeRender(): void
{
// ...
$this->template->setTranslator($translator, $lang);
}
Przez tekst statyczny rozumiemy na przykład {_'hello'} albo {translate}hello{/translate}. Teksty
niestatyczne, jak {_$foo}, nadal będą tłumaczone w czasie działania.