Nette Documentation Preview

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

.[perex]
Syntax Latte powstał z praktycznych wymagań projektantów stron internetowych. Szukaliśmy najbardziej przyjaznej dla użytkownika składni, z którą można elegancko napisać konstrukcje, które w przeciwnym razie są prawdziwym wyzwaniem.
Jednocześnie wszystkie wyrażenia są napisane dokładnie tak samo jak w PHP, więc nie musisz uczyć się nowego języka. Po prostu wykorzystujesz w pełni to, co już wiesz.

Poniżej znajduje się minimalny szablon, który ilustruje kilka podstawowych elementów: tagi, n:attributes, 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>  {* tag wyprowadzający zmienną filtrującą *}
{/foreach}                       {* koniec pętli *}
</ul>
```

Przyjrzyjmy się bliżej tym ważnym elementom i temu, jak mogą one pomóc w stworzeniu rewelacyjnego szablonu.


Tagi .[#toc-tags]
=================

Szablon zawiera znaczniki, które kontrolują logikę szablonu (na przykład pętle *foreach*) lub wyrażenia wyjściowe. Pojedynczy delimiter jest używany dla obu `{ ... }`, więc nie trzeba się zastanawiać, którego delimitera użyć w danej sytuacji, jak to ma miejsce w innych systemach.
Jeśli po znaku `{` następuje cytat lub spacja, Latte nie uważa go za początek znacznika, więc możesz bez problemu używać konstrukcji JavaScript, JSON lub reguł CSS w szablonach.

Zobacz [przegląd wszystkich tagów |tags]. Dodatkowo można też tworzyć [własne tagi |extending-latte#Tags].


Latte rozumie PHP .[#toc-latte-understands-php]
===============================================

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

- zmienne
- ciągi (w tym HEREDOC i NOWDOC), tablice, liczby itp.
- [operatorzy |https://www.php.net/manual/en/language.operators.php]
- wywołania funkcji i metod (które mogą być [sandboxowane |sandbox])
- [mecz |https://www.php.net/manual/en/control-structures.match.php]
- [anonimowe funkcje |https://www.php.net/manual/en/functions.arrow.php]
- [callbacks |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- komentarze wieloliniowe `/* ... */`
- itp...

Latte dodaje również kilka [miłych rozszerzeń |#Syntactic-Sugar] do składni PHP.


n:atrybuty .[#toc-n-attributes]
===============================

Wszystkie sparowane znaczniki, na przykład `{if} … {/if}`, działające na pojedynczym elemencie HTML, można przepisać jako n:attributes. Na przykład `{foreach}` w przykładzie otwierającym można by napisać w ten sposób:

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

Następnie funkcjonalność jest stosowana do elementu HTML, w którym jest umieszczona:

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

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

wydruki:

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

Używając przedrostka `inner-` możemy zmodyfikować zachowanie, aby dotyczyło tylko wewnętrznej części elementu:

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

Zostanie wydrukowany:

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

Możesz też użyć przedrostka `tag-`, aby zastosować tę funkcjonalność do samych znaczników HTML:

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

Która wychodzi w zależności od zmiennej `$url`:

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

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

Jednak n:attributes nie jest tylko skrótem dla znaczników parami. Istnieją również czyste n:atrybuty, takie jak [n:href |application:creating-links#In-the-Presenter-Template] lub podręczny pomocnik kodera [n:class |tags#n-class].


Filtry .[#toc-filters]
======================

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

Filtry wpisujemy po pionowym pasku (przed nim może być spacja):

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

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

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

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

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

Filtry można również zastosować do wyrażenia:

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

Do zablokowania:

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

Lub bezpośrednio na wartość (w połączeniu z tagiem [`{=expr}` | https://latte.nette.org/pl/tags#Vypisování]):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Uwagi .[#toc-comments]
======================

Komentarze są napisane w ten sposób i nie dostają się do wyjścia:

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

Komentarze PHP działają wewnątrz znaczników:

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


Cukier syntaktyczny .[#toc-syntactic-sugar]
===========================================


Nienotowane ciągi znaków .[#toc-strings-without-quotation-marks]
----------------------------------------------------------------

Możesz pominąć cudzysłowy dla prostych ciągów znaków:

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

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

Proste ciągi znaków to takie, które składają się wyłącznie z liter, cyfr, podkreśleń, myślników i kropek. Nie mogą zaczynać się od cyfry i nie mogą zaczynać się ani kończyć myślnikiem.
Nie może składać się tylko z wielkich liter i podkreślników, bo wtedy jest traktowany jako stała (np. `PHP_VERSION`).
I nie może być sprzeczny z następującymi słowami kluczowymi: `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Skrócony operator trójskładnikowy .[#toc-short-ternary-operator]
----------------------------------------------------------------

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

```latte
jako v PHP:  {$stock ? 'Skladem' : ''}

zkráceně:    {$stock ? 'Skladem'}
```


Nowoczesna notacja klucza tablicowego .[#toc-modern-key-notation-in-the-array]
------------------------------------------------------------------------------

Klucze tablicowe mogą być zapisywane podobnie jak nazwane parametry podczas wywoływania funkcji:

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

moderně:     {var $arr = [one: 'item 1', two: 'item 2']}
```


Filtry .[#toc-filters]
----------------------

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

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


Operator `in` .[#toc-operator-in]
---------------------------------

Operator `in` może być użyty do zastąpienia funkcji `in_array()` Porównanie jest zawsze ścisłe:

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


.{data-version:2.9}
Opcjonalne łączenie łańcuchów z operatorem undefined-safe .[#toc-optional-chaining-with-undefined-safe-operator]
----------------------------------------------------------------------------------------------------------------

Operator undefined-safe `??->` jest podobny do operatora nullsafe `?->`, ale nie spowoduje błędu, jeśli zmienna, właściwość lub indeks w ogóle nie istnieje w tablicy.

```latte
{$order??->id}
```

Mówimy, że jeśli `$order` istnieje i nie jest null, `$order->id` będzie wyjściem, ale jeśli `$order` jest null lub nie istnieje, przestanie oceniać i po prostu zwróci null.

```latte
{$user??->address??->street}
// znamená cca isset($user) && isset($user->address) ? $user->address->street : null
```


Okno historyczne .[#toc-a-window-into-history]
----------------------------------------------

Latte w ciągu swojej historii wymyśliło kilka syntaktycznych sugar daddies, które kilka lat później pojawiły się w samym PHP. Na przykład w Latte można było napisać pola typu `[1, 2, 3]` zamiast `array(1, 2, 3)` lub używać operatora nullsafe `$obj?->foo` na długo przed tym, jak było to możliwe w samym PHP. Latte wprowadził również operator rozszerzenia tablicy `(expand) $arr`, który jest odpowiednikiem dzisiejszego operatora `...$arr` z PHP.


Ograniczenia PHP w Latte .[#toc-php-limitations-in-latte]
=========================================================

W Latte można pisać tylko wyrażenia PHP. To znaczy, nie można deklarować klas ani używać [struktur kontrolnych |https://www.php.net/manual/en/language.control-structures.php], takich jak `if`, `foreach`, `switch`, `return`, `try`, `throw` i innych, zamiast których Latte oferuje własne [znaczniki |tags].
Nie można też używać [atrybutów |https://www.php.net/manual/en/language.attributes.php], [backticków |https://www.php.net/manual/en/language.operators.execution.php] czy [magicznych stałych |https://www.php.net/manual/en/language.constants.magic.php], bo to nie miałoby sensu.
Nie możesz też użyć `unset`, `echo`, `include`, `require`, `exit`, `eval`, ponieważ nie są to funkcje, lecz specjalne konstrukcje języka PHP, a więc nie są wyrażeniami.

Można jednak obejść te ograniczenia aktywując [RawPhpExtension |develop#RawPhpExtension], które pozwala wtedy na użycie dowolnego kodu PHP w tagu `{php ...}` na ryzyko autora szablonu.

Składnia

Syntax Latte powstał z praktycznych wymagań projektantów stron internetowych. Szukaliśmy najbardziej przyjaznej dla użytkownika składni, z którą można elegancko napisać konstrukcje, które w przeciwnym razie są prawdziwym wyzwaniem. Jednocześnie wszystkie wyrażenia są napisane dokładnie tak samo jak w PHP, więc nie musisz uczyć się nowego języka. Po prostu wykorzystujesz w pełni to, co już wiesz.

Poniżej znajduje się minimalny szablon, który ilustruje kilka podstawowych elementów: tagi, n:attributes, 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>  {* tag wyprowadzający zmienną filtrującą *}
{/foreach}                       {* koniec pętli *}
</ul>

Przyjrzyjmy się bliżej tym ważnym elementom i temu, jak mogą one pomóc w stworzeniu rewelacyjnego szablonu.

Tagi

Szablon zawiera znaczniki, które kontrolują logikę szablonu (na przykład pętle foreach) lub wyrażenia wyjściowe. Pojedynczy delimiter jest używany dla obu { ... }, więc nie trzeba się zastanawiać, którego delimitera użyć w danej sytuacji, jak to ma miejsce w innych systemach. Jeśli po znaku { następuje cytat lub spacja, Latte nie uważa go za początek znacznika, więc możesz bez problemu używać konstrukcji JavaScript, JSON lub reguł CSS w szablonach.

Zobacz przegląd wszystkich tagów. Dodatkowo można też tworzyć własne tagi.

Latte rozumie PHP

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

Latte dodaje również kilka miłych rozszerzeń do składni PHP.

n:atrybuty

Wszystkie sparowane znaczniki, na przykład {if} … {/if}, działające na pojedynczym elemencie HTML, można przepisać jako n:attributes. Na przykład {foreach} w przykładzie otwierającym można by napisać w ten sposób:

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

Następnie funkcjonalność jest stosowana do elementu HTML, w którym jest umieszczona:

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

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

wydruki:

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

Używając przedrostka inner- możemy zmodyfikować zachowanie, aby dotyczyło tylko wewnętrznej części elementu:

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

Zostanie wydrukowany:

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

Możesz też użyć przedrostka tag-, aby zastosować tę funkcjonalność do samych znaczników HTML:

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

Która wychodzi w zależności od zmiennej $url:

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

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

Jednak n:attributes nie jest tylko skrótem dla znaczników parami. Istnieją również czyste n:atrybuty, takie jak n:href lub podręczny pomocnik kodera n:class.

Filtry

Zobacz przegląd standardowych filtrów.

Filtry wpisujemy po pionowym pasku (przed nim może być spacja):

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

Filtry 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 można również zastosować do wyrażenia:

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

Do zablokowania:

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

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

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

Uwagi

Komentarze są napisane w ten sposób i nie dostają się do wyjścia:

{* to jest komentarz w Latte *}

Komentarze PHP działają wewnątrz znaczników:

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

Cukier syntaktyczny

Nienotowane ciągi znaków

Możesz pominąć cudzysłowy dla prostych ciągów znaków:

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

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

Proste ciągi znaków to takie, które składają się wyłącznie z liter, cyfr, podkreśleń, myślników i kropek. Nie mogą zaczynać się od cyfry i nie mogą zaczynać się ani kończyć myślnikiem. Nie może składać się tylko z wielkich liter i podkreślników, bo wtedy jest traktowany jako stała (np. PHP_VERSION). I nie może być sprzeczny z następującymi słowami kluczowymi: and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Skrócony operator trójskładnikowy

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

jako v PHP:  {$stock ? 'Skladem' : ''}

zkráceně:    {$stock ? 'Skladem'}

Nowoczesna notacja klucza tablicowego

Klucze tablicowe mogą być zapisywane podobnie jak nazwane parametry podczas wywoływania funkcji:

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

moderně:     {var $arr = [one: 'item 1', two: 'item 2']}

Filtry

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

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

Operator in

Operator in może być użyty do zastąpienia funkcji in_array() Porównanie jest zawsze ścisłe:

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

Opcjonalne łączenie łańcuchów z operatorem undefined-safe

Operator undefined-safe ??-> jest podobny do operatora nullsafe ?->, ale nie spowoduje błędu, jeśli zmienna, właściwość lub indeks w ogóle nie istnieje w tablicy.

{$order??->id}

Mówimy, że jeśli $order istnieje i nie jest null, $order->id będzie wyjściem, ale jeśli $order jest null lub nie istnieje, przestanie oceniać i po prostu zwróci null.

{$user??->address??->street}
// znamená cca isset($user) && isset($user->address) ? $user->address->street : null

Okno historyczne

Latte w ciągu swojej historii wymyśliło kilka syntaktycznych sugar daddies, które kilka lat później pojawiły się w samym PHP. Na przykład w Latte można było napisać pola typu [1, 2, 3] zamiast array(1, 2, 3) lub używać operatora nullsafe $obj?->foo na długo przed tym, jak było to możliwe w samym PHP. Latte wprowadził również operator rozszerzenia tablicy (expand) $arr, który jest odpowiednikiem dzisiejszego operatora ...$arr z PHP.

Ograniczenia PHP w Latte

W Latte można pisać tylko wyrażenia PHP. To znaczy, nie można deklarować klas ani używać struktur kontrolnych, takich jak if, foreach, switch, return, try, throw i innych, zamiast których Latte oferuje własne znaczniki. Nie można też używać atrybutów, backticków czy magicznych stałych, bo to nie miałoby sensu. Nie możesz też użyć unset, echo, include, require, exit, eval, ponieważ nie są to funkcje, lecz specjalne konstrukcje języka PHP, a więc nie są wyrażeniami.

Można jednak obejść te ograniczenia aktywując RawPhpExtension, które pozwala wtedy na użycie dowolnego kodu PHP w tagu {php ...} na ryzyko autora szablonu.