Nette Documentation Preview

syntax 
Składnia
********

.[perex]
Składnia Latte wywodzi się z praktycznych wymagań webdesignerów. Szukaliśmy najbardziej przyjaznej składni, za pomocą której elegancko zapiszesz nawet konstrukcje, które w innym przypadku stanowią prawdziwe wyzwanie. Jednocześnie wszystkie wyrażenia pisze się dokładnie tak samo jak w PHP, więc nie musisz uczyć się nowego języka. Po prostu wykorzystujesz to, co już dawno umiesz.

Poniżej znajduje się minimalny szablon, który ilustruje kilka podstawowych elementów: znaczniki, n:atrybuty, komentarze i filtry.

```latte
{* to jest komentarz *}
<ul n:if=$items>                  {* n:if to n:atrybut *}
{foreach $items as $item}         {* znacznik reprezentujący pętlę foreach *}
	<li>{$item|capitalize}</li>   {* znacznik wyświetlający zmienną z filtrem *}
{/foreach}                        {* koniec pętli *}
</ul>
```

Przyjrzyjmy się bliżej tym ważnym elementom i temu, jak mogą pomóc Ci stworzyć niesamowity szablon.


Znaczniki
=========

Szablon zawiera znaczniki, które sterują logiką szablonu (na przykład pętle *foreach*) lub wyświetlają wyrażenia. Do obu celów używa się jednego ogranicznika `{ ... }`, więc nie musisz myśleć, jakiego ogranicznika użyć w jakiej sytuacji, jak ma to miejsce w innych systemach. Jeśli po znaku `{` następuje cudzysłów lub spacja, Latte nie uważa go za początek znacznika, dzięki czemu możesz w szablonach bez problemu używać również konstrukcji JavaScriptowych, JSON lub reguł w CSS.

Zobacz [przegląd wszystkich znaczników|tags]. Oprócz tego możesz tworzyć również [niestandardowe znaczniki|custom tags].


Latte rozumie PHP
=================

Wewnątrz znaczników możesz używać wyrażeń PHP, które dobrze znasz:

- zmienne
- ciągi znaków (w tym HEREDOC i NOWDOC), tablice, liczby itp.
- [operatory |https://www.php.net/manual/en/language.operators.php]
- wywołania funkcji i metod (które można ograniczyć [sandboxem|sandbox])
- [match |https://www.php.net/manual/en/control-structures.match.php]
- [funkcje anonimowe |https://www.php.net/manual/en/functions.arrow.php]
- [callbacki |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- komentarze wieloliniowe `/* ... */`
- itd…

Latte dodatkowo uzupełnia składnię PHP o kilka [przyjemnych rozszerzeń |#Cukier syntaktyczny].


n:atrybuty
==========

Wszystkie znaczniki parzyste, na przykład `{if} … {/if}`, operujące na jednym elemencie HTML, można przepisać w postaci n:atrybutów. W ten sposób można by zapisać na przykład również `{foreach}` we wstępnym przykładzie:

```latte
<ul n:if=$items>
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>
```

Funkcjonalność odnosi się wtedy do elementu HTML, w którym jest umieszczona:

```latte
{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>
```

wyświetli:

```latte
<p>I</p>
<p>♥</p>
<p>Latte</p>
```

Za pomocą prefiksu `inner-` możemy zmodyfikować zachowanie tak, aby odnosiło się tylko do wewnętrznej części elementu:

```latte
<div n:inner-foreach="$items as $item">
	<p>{$item}</p>
	<hr>
</div>
```

Wyświetli się:

```latte
<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>
```

Lub za pomocą prefiksu `tag-` zastosujemy funkcjonalność tylko do samych znaczników HTML:

```latte
<p><a href={$url} n:tag-if="$url">Title</a></p>
```

Co wyświetli w zależności od zmiennej `$url`:

```latte
{* gdy $url jest puste *}
<p>Title</p>

{* gdy $url zawiera 'https://nette.org' *}
<p><a href="https://nette.org">Title</a></p>
```

Jednak n:atrybuty to nie tylko skrót dla znaczników parzystych. Istnieją również czyste n:atrybuty, takie jak [n:href |application:creating-links#W szablonie presentera] lub bardzo przydatny pomocnik kodera [n:class |tags#n:class].


Filtry
======

Zobacz przegląd [standardowych filtrów |filters].

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

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

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

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

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

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

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

```latte
{var $name = ($title|upper) . ($subtitle|lower)}
```

Na blok:

```latte
<h1>{block |lower}{$heading}{/block}</h1>
```

Lub bezpośrednio na wartość (w połączeniu ze znacznikiem [`{=expr}` |tags#Wyświetlanie]):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Dynamiczne znaczniki HTML .{data-version:3.0.9}
===============================================

Latte obsługuje dynamiczne znaczniki HTML, które są przydatne, gdy potrzebujesz elastyczności w nazwach znaczników:

```latte
<h{$level}>Heading</h{$level}>
```

Powyższy kod może na przykład generować `<h1>Heading</h1>` lub `<h2>Heading</h2>` w zależności od wartości zmiennej `$level`. Dynamiczne znaczniki HTML w Latte muszą być zawsze parzyste. Ich alternatywą jest [n:tag |tags#n:tag].

Ponieważ Latte jest bezpiecznym systemem szablonów, sprawdza, czy wynikowa nazwa znacznika jest prawidłowa i nie zawiera żadnych niepożądanych lub szkodliwych wartości. Ponadto zapewnia, że nazwa znacznika końcowego będzie zawsze taka sama jak nazwa znacznika otwierającego.


Komentarze
==========

Komentarze zapisuje się w ten sposób i nie trafiają one do wyjścia:

```latte
{* to jest komentarz w Latte *}
```

Wewnątrz znaczników działają komentarze PHP:

```latte
{include 'file.info', /* value: 123 */}
```


Cukier syntaktyczny
===================


Ciągi znaków bez cudzysłowów
----------------------------

W przypadku prostych ciągów znaków można pominąć cudzysłowy:

```latte
jak w PHP:  {var $arr = ['hello', 'btn--default', '€']}

w skrócie:    {var $arr = [hello, btn--default, €]}
```

Proste ciągi znaków to te, które składają się wyłącznie z liter, cyfr, podkreśleń, myślników i kropek. Nie mogą zaczynać się cyfrą i nie mogą zaczynać się ani kończyć myślnikiem. Nie mogą składać się tylko z wielkich liter i podkreśleń, ponieważ wtedy są uważane za stałą (np. `PHP_VERSION`). I nie mogą kolidować ze słowami kluczowymi: `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Stałe
-----

Ponieważ w przypadku prostych ciągów znaków można pomijać cudzysłowy, zalecamy dla odróżnienia zapisywanie stałych globalnych z ukośnikiem na początku:

```latte
{if \PROJECT_ID === 1} ... {/if}
```

Ten zapis jest całkowicie prawidłowy w samym PHP, ukośnik mówi, że stała znajduje się w globalnej przestrzeni nazw.


Skrócony operator trójargumentowy
---------------------------------

Jeśli trzecia wartość operatora trójargumentowego jest pusta, można ją pominąć:

```latte
jak w PHP:  {$stock ? 'W magazynie' : ''}

w skrócie:    {$stock ? 'W magazynie'}
```


Nowoczesny zapis kluczy w tablicy
---------------------------------

Klucze w tablicy można zapisywać podobnie jak nazwane parametry przy wywoływaniu funkcji:

```latte
jak w PHP:  {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

nowocześnie:     {var $arr = [one: 'item 1', two: 'item 2']}
```


Filtry
------

Filtry można stosować do dowolnych wyrażeń, wystarczy całość ująć w nawiasy:

```latte
{var $content = ($text|truncate: 30|upper)}
```


Operator `in`
-------------

Operatorem `in` można zastąpić funkcję `in_array()`. Porównanie jest zawsze ścisłe:

```latte
{* odpowiednik in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}
```


Okno historyczne
----------------

Latte wprowadziło w trakcie swojej historii całą gamę cukierków syntaktycznych, które po kilku latach pojawiły się w samym PHP. Na przykład w Latte można było pisać tablice jako `[1, 2, 3]` zamiast `array(1, 2, 3)` lub używać operatora nullsafe `$obj?->foo` na długo przed tym, zanim stało się to możliwe w samym PHP. Latte wprowadziło również operator do rozpakowywania tablicy `(expand) $arr`, który jest odpowiednikiem dzisiejszego operatora `...$arr` z PHP.

Operator undefined-safe `??->`, który jest odpowiednikiem operatora nullsafe `?->`, ale nie wywołuje błędu, jeśli zmienna nie istnieje, powstał z powodów historycznych i dzisiaj zalecamy używanie standardowego operatora PHP `?->`.


Ograniczenia PHP w Latte
========================

W Latte można zapisywać tylko wyrażenia PHP. Zatem nie można używać instrukcji zakończonych średnikiem. Nie można deklarować klas ani używać [struktur sterujących |https://www.php.net/manual/en/language.control-structures.php], np. `if`, `foreach`, `switch`, `return`, `try`, `throw` i innych, zamiast których Latte oferuje swoje [znaczniki|tags]. Nie można również używać [atrybutów |https://www.php.net/manual/en/language.attributes.php], [backticks |https://www.php.net/manual/en/language.operators.execution.php] czy niektórych [stałych magicznych |https://www.php.net/manual/en/language.constants.magic.php]. Nie można używać również `unset`, `echo`, `include`, `require`, `exit`, `eval`, ponieważ nie są to funkcje, ale specjalne konstrukcje językowe PHP, i nie są to więc wyrażenia. Komentarze są obsługiwane tylko wieloliniowe `/* ... */`.

Te ograniczenia można jednak obejść, aktywując rozszerzenie [RawPhpExtension |develop#RawPhpExtension], dzięki któremu można następnie używać w znaczniku `{php ...}` dowolnego kodu PHP na odpowiedzialność autora szablonu.

Składnia

Składnia Latte wywodzi się z praktycznych wymagań webdesignerów. Szukaliśmy najbardziej przyjaznej składni, za pomocą której elegancko zapiszesz nawet konstrukcje, które w innym przypadku stanowią prawdziwe wyzwanie. Jednocześnie wszystkie wyrażenia pisze się dokładnie tak samo jak w PHP, więc nie musisz uczyć się nowego języka. Po prostu wykorzystujesz to, co już dawno umiesz.

Poniżej znajduje się minimalny szablon, który ilustruje kilka podstawowych elementów: znaczniki, n:atrybuty, komentarze i filtry.

{* to jest komentarz *}
<ul n:if=$items>                  {* n:if to n:atrybut *}
{foreach $items as $item}         {* znacznik reprezentujący pętlę foreach *}
	<li>{$item|capitalize}</li>   {* znacznik wyświetlający zmienną z filtrem *}
{/foreach}                        {* koniec pętli *}
</ul>

Przyjrzyjmy się bliżej tym ważnym elementom i temu, jak mogą pomóc Ci stworzyć niesamowity szablon.

Znaczniki

Szablon zawiera znaczniki, które sterują logiką szablonu (na przykład pętle foreach) lub wyświetlają wyrażenia. Do obu celów używa się jednego ogranicznika { ... }, więc nie musisz myśleć, jakiego ogranicznika użyć w jakiej sytuacji, jak ma to miejsce w innych systemach. Jeśli po znaku { następuje cudzysłów lub spacja, Latte nie uważa go za początek znacznika, dzięki czemu możesz w szablonach bez problemu używać również konstrukcji JavaScriptowych, JSON lub reguł w CSS.

Zobacz przegląd wszystkich znaczników. Oprócz tego możesz tworzyć również niestandardowe znaczniki.

Latte rozumie PHP

Wewnątrz znaczników możesz używać wyrażeń PHP, które dobrze znasz:

Latte dodatkowo uzupełnia składnię PHP o kilka przyjemnych rozszerzeń.

n:atrybuty

Wszystkie znaczniki parzyste, na przykład {if} … {/if}, operujące na jednym elemencie HTML, można przepisać w postaci n:atrybutów. W ten sposób można by zapisać na przykład również {foreach} we wstępnym przykładzie:

<ul n:if=$items>
	<li n:foreach="$items as $item">{$item|capitalize}</li>
</ul>

Funkcjonalność odnosi się wtedy do elementu HTML, w którym jest umieszczona:

{var $items = ['I', '♥', 'Latte']}

<p n:foreach="$items as $item">{$item}</p>

wyświetli:

<p>I</p>
<p>♥</p>
<p>Latte</p>

Za pomocą prefiksu inner- możemy zmodyfikować zachowanie tak, aby odnosiło się tylko do wewnętrznej części elementu:

<div n:inner-foreach="$items as $item">
	<p>{$item}</p>
	<hr>
</div>

Wyświetli się:

<div>
	<p>I</p>
	<hr>
	<p>♥</p>
	<hr>
	<p>Latte</p>
	<hr>
</div>

Lub za pomocą prefiksu tag- zastosujemy funkcjonalność tylko do samych znaczników HTML:

<p><a href={$url} n:tag-if="$url">Title</a></p>

Co wyświetli w zależności od zmiennej $url:

{* gdy $url jest puste *}
<p>Title</p>

{* gdy $url zawiera 'https://nette.org' *}
<p><a href="https://nette.org">Title</a></p>

Jednak n:atrybuty to nie tylko skrót dla znaczników parzystych. Istnieją również czyste n:atrybuty, takie jak n:href lub bardzo przydatny pomocnik kodera n:class.

Filtry

Zobacz przegląd standardowych filtrów.

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

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

Filtry 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)}

Na blok:

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

Lub bezpośrednio na wartość (w połączeniu ze znacznikiem {=expr}):

<h1>{='  Hello world  '|trim}<h1>

Dynamiczne znaczniki HTML

Latte obsługuje dynamiczne znaczniki HTML, które są przydatne, gdy potrzebujesz elastyczności w nazwach znaczników:

<h{$level}>Heading</h{$level}>

Powyższy kod może na przykład generować <h1>Heading</h1> lub <h2>Heading</h2> w zależności od wartości zmiennej $level. Dynamiczne znaczniki HTML w Latte muszą być zawsze parzyste. Ich alternatywą jest n:tag.

Ponieważ Latte jest bezpiecznym systemem szablonów, sprawdza, czy wynikowa nazwa znacznika jest prawidłowa i nie zawiera żadnych niepożądanych lub szkodliwych wartości. Ponadto zapewnia, że nazwa znacznika końcowego będzie zawsze taka sama jak nazwa znacznika otwierającego.

Komentarze

Komentarze zapisuje się w ten sposób i nie trafiają one do wyjścia:

{* to jest komentarz w Latte *}

Wewnątrz znaczników działają komentarze PHP:

{include 'file.info', /* value: 123 */}

Cukier syntaktyczny

Ciągi znaków bez cudzysłowów

W przypadku prostych ciągów znaków można pominąć cudzysłowy:

jak w PHP:  {var $arr = ['hello', 'btn--default', '€']}

w skrócie:    {var $arr = [hello, btn--default, €]}

Proste ciągi znaków to te, które składają się wyłącznie z liter, cyfr, podkreśleń, myślników i kropek. Nie mogą zaczynać się cyfrą i nie mogą zaczynać się ani kończyć myślnikiem. Nie mogą składać się tylko z wielkich liter i podkreśleń, ponieważ wtedy są uważane za stałą (np. PHP_VERSION). I nie mogą kolidować ze słowami kluczowymi: and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Stałe

Ponieważ w przypadku prostych ciągów znaków można pomijać cudzysłowy, zalecamy dla odróżnienia zapisywanie stałych globalnych z ukośnikiem na początku:

{if \PROJECT_ID === 1} ... {/if}

Ten zapis jest całkowicie prawidłowy w samym PHP, ukośnik mówi, że stała znajduje się w globalnej przestrzeni nazw.

Skrócony operator trójargumentowy

Jeśli trzecia wartość operatora trójargumentowego jest pusta, można ją pominąć:

jak w PHP:  {$stock ? 'W magazynie' : ''}

w skrócie:    {$stock ? 'W magazynie'}

Nowoczesny zapis kluczy w tablicy

Klucze w tablicy można zapisywać podobnie jak nazwane parametry przy wywoływaniu funkcji:

jak w PHP:  {var $arr = ['one' => 'item 1', 'two' => 'item 2']}

nowocześnie:     {var $arr = [one: 'item 1', two: 'item 2']}

Filtry

Filtry można stosować do dowolnych wyrażeń, wystarczy całość ująć w nawiasy:

{var $content = ($text|truncate: 30|upper)}

Operator in

Operatorem in można zastąpić funkcję in_array(). Porównanie jest zawsze ścisłe:

{* odpowiednik in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}

Okno historyczne

Latte wprowadziło w trakcie swojej historii całą gamę cukierków syntaktycznych, które po kilku latach pojawiły się w samym PHP. Na przykład w Latte można było pisać tablice jako [1, 2, 3] zamiast array(1, 2, 3) lub używać operatora nullsafe $obj?->foo na długo przed tym, zanim stało się to możliwe w samym PHP. Latte wprowadziło również operator do rozpakowywania tablicy (expand) $arr, który jest odpowiednikiem dzisiejszego operatora ...$arr z PHP.

Operator undefined-safe ??->, który jest odpowiednikiem operatora nullsafe ?->, ale nie wywołuje błędu, jeśli zmienna nie istnieje, powstał z powodów historycznych i dzisiaj zalecamy używanie standardowego operatora PHP ?->.

Ograniczenia PHP w Latte

W Latte można zapisywać tylko wyrażenia PHP. Zatem nie można używać instrukcji zakończonych średnikiem. Nie można deklarować klas ani używać struktur sterujących, np. if, foreach, switch, return, try, throw i innych, zamiast których Latte oferuje swoje znaczniki. Nie można również używać atrybutów, backticks czy niektórych stałych magicznych. Nie można używać również unset, echo, include, require, exit, eval, ponieważ nie są to funkcje, ale specjalne konstrukcje językowe PHP, i nie są to więc wyrażenia. Komentarze są obsługiwane tylko wieloliniowe /* ... */.

Te ograniczenia można jednak obejść, aktywując rozszerzenie RawPhpExtension, dzięki któremu można następnie używać w znaczniku {php ...} dowolnego kodu PHP na odpowiedzialność autora szablonu.