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>
```


Dynamiczne znaczniki HTML .[#toc-dynamic-html-tags]
===================================================

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

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

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

Ponieważ Latte jest bezpiecznym systemem szablonów, sprawdza, czy wynikowa nazwa tagu jest prawidłowa i nie zawiera niepożądanych lub złośliwych wartości. Zapewnia również, że końcowa nazwa tagu jest zawsze taka sama jak nazwa tagu otwierającego.


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}
```


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.

Operator undefined-safe `??->`, który jest podobny do operatora nullsafe `?->`, ale nie powoduje błędu, jeśli zmienna nie istnieje, został stworzony z powodów historycznych i obecnie zalecamy używanie standardowego operatora PHP `?->`.


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

W Latte można pisać tylko wyrażenia PHP. Oznacza to, że nie można używać wyrażeń kończących się średnikiem. 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 swoje [znaczniki |tags].
Nie można również 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] ani żadnych [magicznych stałych |https://www.php.net/manual/en/language.constants.magic.php].
Nie można nawet używać `unset`, `echo`, `include`, `require`, `exit`, `eval`, ponieważ nie są one funkcjami, ale specjalnymi konstrukcjami języka PHP, a zatem nie są wyrażeniami. Obsługiwane są tylko komentarze wielowierszowe `/* ... */`.

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>

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

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

Ponieważ Latte jest bezpiecznym systemem szablonów, sprawdza, czy wynikowa nazwa tagu jest prawidłowa i nie zawiera niepożądanych lub złośliwych wartości. Zapewnia również, że końcowa nazwa tagu jest zawsze taka sama jak nazwa tagu otwierającego.

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}

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.

Operator undefined-safe ??->, który jest podobny do operatora nullsafe ?->, ale nie powoduje błędu, jeśli zmienna nie istnieje, został stworzony z powodów historycznych i obecnie zalecamy używanie standardowego operatora PHP ?->.

Ograniczenia PHP w Latte

W Latte można pisać tylko wyrażenia PHP. Oznacza to, że nie można używać wyrażeń kończących się średnikiem. 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 swoje znaczniki. Nie można również używać atrybutów, backticków ani żadnych magicznych stałych. Nie można nawet używać unset, echo, include, require, exit, eval, ponieważ nie są one funkcjami, ale specjalnymi konstrukcjami języka PHP, a zatem nie są wyrażeniami. Obsługiwane są tylko komentarze wielowierszowe /* ... */.

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.