Nette Documentation Preview

syntax 
Syntaxe
*******

.[perex]
Syntax Latte byla navržena s ohledem na praktické potřeby webdesignérů. Hledali jsme co nejpřívětivější syntax, která umožní elegantně zapsat i složité konstrukce. Zároveň jsme zachovali kompatibilitu s PHP, takže se nemusíte učit nový jazyk - stačí využít to, co již znáte.

Níže uvádíme minimální šablonu, která ilustruje několik základních prvků: tagy, n:atributy, komentáře a filtry.

```latte
{* toto je komentář *}
<ul n:if="$items">                {* n:if je n:atribut *}
{foreach $items as $item}         {* tag představující cyklus foreach *}
	<li>{$item|capitalize}</li>   {* tag vypisující proměnnou s filtrem *}
{/foreach}                        {* konec cyklu *}
</ul>
```

Podívejme se blíže na tyto důležité prvky a na to, jak vám mohou pomoci vytvořit úžasnou šablonu.


Tagy
====

Šablona obsahuje tagy (neboli značky či makra), které řídí logiku šablony (například smyčky *foreach*) nebo vypisují výrazy. Pro obojí se používá jednotný delimiter `{ ... }`, což eliminuje nutnost přemýšlet, jaký delimiter v jaké situaci použít, na rozdíl od některých jiných systémů.
Pokud bezprostředně za `{` následuje uvozovka nebo mezera, Latte tento znak nepovažuje za začátek tagu. To umožňuje bezproblémové použití JavaScriptových konstrukcí, JSONu nebo pravidel v CSS přímo v šablonách.

Kompletní [přehled všech tagů|tags] najdete v dokumentaci. Navíc máte možnost vytvářet i [vlastní tagy|extending-latte#tagy] pro specifické potřeby vašeho projektu.


Latte rozumí PHP
================

Uvnitř tagů můžete používat standardní PHP výrazy:

- proměnné
- řetězce (včetně HEREDOC a NOWDOC), pole, čísla, atd.
- [operátory |https://www.php.net/manual/en/language.operators.php]
- volání funkcí a metod (které lze v případě potřeby omezit [sandboxem|sandbox])
- [match |https://www.php.net/manual/en/control-structures.match.php]
- [anonymní funkce |https://www.php.net/manual/en/functions.arrow.php]
- [callbacky |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- víceřádkové komentáře `/* ... */`
- a mnoho dalšího...

Latte navíc rozšiřuje PHP syntax o několik [užitečných vylepšení |#Syntaktický cukr].


n:atributy
==========

Všechny párové tagy, jako například `{if} … {/if}`, které operují nad jedním HTML elementem, lze přepsat do podoby n:atributů. Takto by bylo možné zapsat i `{foreach}` z úvodní ukázky:

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

Funkcionalita se vztahuje na HTML element, ve kterém je n:atribut umístěn:

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

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

Tento kód vypíše:

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

Pomocí prefixu `inner-` můžeme upravit chování tak, aby se vztahovalo pouze na vnitřní obsah elementu:

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

Výsledek bude:

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

Prefix `tag-` umožňuje aplikovat funkcionalitu pouze na samotné HTML tagy:

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

V závislosti na hodnotě proměnné `$url` se vypíše:

```latte
{* když je $url prázdné *}
<p>Title</p>

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

N:atributy nejsou jen zkratkou pro párové tagy. Existují i specifické n:atributy jako [n:href |application:creating-links#V šabloně presenteru] nebo velmi užitečný [n:class |tags#n:class].


Filtry
======

Kompletní seznam [standardních filtrů |filters] najdete v dokumentaci.

Filtry se zapisují za svislítko (před kterým může být mezera):

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

Filtry lze řetězit, přičemž se aplikují zleva doprava:

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

Parametry filtrů se zadávají za jménem filtru, oddělené dvojtečkami nebo čárkami:

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

Filtry lze aplikovat i na výrazy:

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

Na bloky:

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

Nebo přímo na hodnoty (v kombinaci s tagem [`{=expr}`| https://latte.nette.org/cs/tags#Vypisování]):

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


Dynamické HTML tagy .{data-version:3.0.9}
=========================================

Latte podporuje dynamické HTML tagy, což je užitečné, když potřebujete flexibilitu v názvech tagů:

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

Tento kód může generovat například `<h1>Heading</h1>` nebo `<h2>Heading</h2>` v závislosti na hodnotě proměnné `$level`. Dynamické HTML tagy v Latte musí být vždy párové. Alternativou je použití [n:tag |tags#n:tag].

Latte jako bezpečný šablonovací systém kontroluje, zda je výsledný název tagu validní a neobsahuje nežádoucí nebo potenciálně škodlivé hodnoty. Zároveň zajišťuje, že název koncového tagu bude vždy shodný s názvem otevíracího tagu.


Komentáře
=========

Komentáře se zapisují následujícím způsobem a nejsou součástí výstupu:

```latte
{* tohle je komentář v Latte *}
```

Uvnitř tagů lze použít standardní PHP komentáře:

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


Syntaktický cukr
================


Řetězce bez uvozovek
--------------------

U jednoduchých řetězců lze vynechat uvozovky:

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

zkrácená verze:  {var $arr = [hello, btn--default, €]}
```

Jednoduché řetězce se skládají výhradně z písmen, číslic, podtržítek, pomlček a teček. Nesmí začínat číslicí a nesmí začínat nebo končit pomlčkou.
Nesmí být tvořeny pouze velkými písmeny a podtržítky, protože ty jsou považovány za konstanty (např. `PHP_VERSION`).
Také nesmí kolidovat s klíčovými slovy: `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Zkrácený ternární operátor
--------------------------

Pokud je třetí hodnota ternárního operátoru prázdná, lze ji vynechat:

```latte
standardní PHP:  {$stock ? 'Skladem' : ''}

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


Moderní zápis klíčů v poli
--------------------------

Klíče v poli lze zapisovat podobně jako pojmenované parametry při volání funkcí:

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

moderní zápis:   {var $arr = [one: 'item 1', two: 'item 2']}
```


Filtry
------

Filtry lze aplikovat na libovolné výrazy, stačí celý výraz uzavřít do závorek:

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


Operátor `in`
-------------

Operátor `in` nahrazuje funkci `in_array()`. Porovnání je vždy striktní:

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


Historické okénko
-----------------

Latte v průběhu své historie zavedlo mnoho syntaktických vylepšení, která se později objevila i v samotném PHP. Například v Latte bylo možné používat zápis pole jako `[1, 2, 3]` místo `array(1, 2, 3)` nebo nullsafe operátor `$obj?->foo` dlouho před tím, než to umožnilo PHP. Latte také představilo operátor pro rozbalení pole `(expand) $arr`, který je ekvivalentem dnešního PHP operátoru `...$arr`.

Undefined-safe operátor `??->`, podobný nullsafe operátoru `?->`, ale nezpůsobující chybu při neexistující proměnné, vznikl z historických důvodů. Dnes doporučujeme používat standardní PHP operátor `?->`.


Omezení PHP v Latte
===================

V Latte lze používat pouze PHP výrazy. Nelze používat příkazy ukončené středníkem, deklarovat třídy nebo používat [řídící struktury |https://www.php.net/manual/en/language.control-structures.php] jako `if`, `foreach`, `switch`, `return`, `try`, `throw` atd. Místo nich Latte nabízí své vlastní [tagy|tags].
Nelze používat ani [atributy |https://www.php.net/manual/en/language.attributes.php], [backticks |https://www.php.net/manual/en/language.operators.execution.php] či některé [magické konstanty |https://www.php.net/manual/en/language.constants.magic.php].
Také nelze použít `unset`, `echo`, `include`, `require`, `exit`, `eval`, protože nejde o funkce, ale o speciální jazykové konstrukce PHP. Z komentářů jsou podporovány pouze víceřádkové `/* ... */`.

Tato omezení lze obejít aktivací rozšíření [RawPhpExtension |develop#RawPhpExtension], které umožňuje používat ve značce `{php ...}` jakýkoliv PHP kód na zodpovědnost autora šablony.

Syntaxe

Syntax Latte byla navržena s ohledem na praktické potřeby webdesignérů. Hledali jsme co nejpřívětivější syntax, která umožní elegantně zapsat i složité konstrukce. Zároveň jsme zachovali kompatibilitu s PHP, takže se nemusíte učit nový jazyk – stačí využít to, co již znáte.

Níže uvádíme minimální šablonu, která ilustruje několik základních prvků: tagy, n:atributy, komentáře a filtry.

{* toto je komentář *}
<ul n:if="$items">                {* n:if je n:atribut *}
{foreach $items as $item}         {* tag představující cyklus foreach *}
	<li>{$item|capitalize}</li>   {* tag vypisující proměnnou s filtrem *}
{/foreach}                        {* konec cyklu *}
</ul>

Podívejme se blíže na tyto důležité prvky a na to, jak vám mohou pomoci vytvořit úžasnou šablonu.

Tagy

Šablona obsahuje tagy (neboli značky či makra), které řídí logiku šablony (například smyčky foreach) nebo vypisují výrazy. Pro obojí se používá jednotný delimiter { ... }, což eliminuje nutnost přemýšlet, jaký delimiter v jaké situaci použít, na rozdíl od některých jiných systémů. Pokud bezprostředně za { následuje uvozovka nebo mezera, Latte tento znak nepovažuje za začátek tagu. To umožňuje bezproblémové použití JavaScriptových konstrukcí, JSONu nebo pravidel v CSS přímo v šablonách.

Kompletní přehled všech tagů najdete v dokumentaci. Navíc máte možnost vytvářet i vlastní tagy pro specifické potřeby vašeho projektu.

Latte rozumí PHP

Uvnitř tagů můžete používat standardní PHP výrazy:

  • proměnné
  • řetězce (včetně HEREDOC a NOWDOC), pole, čísla, atd.
  • operátory
  • volání funkcí a metod (které lze v případě potřeby omezit sandboxem)
  • match
  • anonymní funkce
  • callbacky
  • víceřádkové komentáře /* ... */
  • a mnoho dalšího…

Latte navíc rozšiřuje PHP syntax o několik užitečných vylepšení.

n:atributy

Všechny párové tagy, jako například {if} … {/if}, které operují nad jedním HTML elementem, lze přepsat do podoby n:atributů. Takto by bylo možné zapsat i {foreach} z úvodní ukázky:

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

Funkcionalita se vztahuje na HTML element, ve kterém je n:atribut umístěn:

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

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

Tento kód vypíše:

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

Pomocí prefixu inner- můžeme upravit chování tak, aby se vztahovalo pouze na vnitřní obsah elementu:

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

Výsledek bude:

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

Prefix tag- umožňuje aplikovat funkcionalitu pouze na samotné HTML tagy:

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

V závislosti na hodnotě proměnné $url se vypíše:

{* když je $url prázdné *}
<p>Title</p>

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

N:atributy nejsou jen zkratkou pro párové tagy. Existují i specifické n:atributy jako n:href nebo velmi užitečný n:class.

Filtry

Kompletní seznam standardních filtrů najdete v dokumentaci.

Filtry se zapisují za svislítko (před kterým může být mezera):

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

Filtry lze řetězit, přičemž se aplikují zleva doprava:

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

Parametry filtrů se zadávají za jménem filtru, oddělené dvojtečkami nebo čárkami:

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

Filtry lze aplikovat i na výrazy:

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

Na bloky:

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

Nebo přímo na hodnoty (v kombinaci s tagem {=expr}):

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

Dynamické HTML tagy

Latte podporuje dynamické HTML tagy, což je užitečné, když potřebujete flexibilitu v názvech tagů:

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

Tento kód může generovat například <h1>Heading</h1> nebo <h2>Heading</h2> v závislosti na hodnotě proměnné $level. Dynamické HTML tagy v Latte musí být vždy párové. Alternativou je použití n:tag.

Latte jako bezpečný šablonovací systém kontroluje, zda je výsledný název tagu validní a neobsahuje nežádoucí nebo potenciálně škodlivé hodnoty. Zároveň zajišťuje, že název koncového tagu bude vždy shodný s názvem otevíracího tagu.

Komentáře

Komentáře se zapisují následujícím způsobem a nejsou součástí výstupu:

{* tohle je komentář v Latte *}

Uvnitř tagů lze použít standardní PHP komentáře:

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

Syntaktický cukr

Řetězce bez uvozovek

U jednoduchých řetězců lze vynechat uvozovky:

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

zkrácená verze:  {var $arr = [hello, btn--default, €]}

Jednoduché řetězce se skládají výhradně z písmen, číslic, podtržítek, pomlček a teček. Nesmí začínat číslicí a nesmí začínat nebo končit pomlčkou. Nesmí být tvořeny pouze velkými písmeny a podtržítky, protože ty jsou považovány za konstanty (např. PHP_VERSION). Také nesmí kolidovat s klíčovými slovy: and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Zkrácený ternární operátor

Pokud je třetí hodnota ternárního operátoru prázdná, lze ji vynechat:

standardní PHP:  {$stock ? 'Skladem' : ''}

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

Moderní zápis klíčů v poli

Klíče v poli lze zapisovat podobně jako pojmenované parametry při volání funkcí:

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

moderní zápis:   {var $arr = [one: 'item 1', two: 'item 2']}

Filtry

Filtry lze aplikovat na libovolné výrazy, stačí celý výraz uzavřít do závorek:

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

Operátor in

Operátor in nahrazuje funkci in_array(). Porovnání je vždy striktní:

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

Historické okénko

Latte v průběhu své historie zavedlo mnoho syntaktických vylepšení, která se později objevila i v samotném PHP. Například v Latte bylo možné používat zápis pole jako [1, 2, 3] místo array(1, 2, 3) nebo nullsafe operátor $obj?->foo dlouho před tím, než to umožnilo PHP. Latte také představilo operátor pro rozbalení pole (expand) $arr, který je ekvivalentem dnešního PHP operátoru ...$arr.

Undefined-safe operátor ??->, podobný nullsafe operátoru ?->, ale nezpůsobující chybu při neexistující proměnné, vznikl z historických důvodů. Dnes doporučujeme používat standardní PHP operátor ?->.

Omezení PHP v Latte

V Latte lze používat pouze PHP výrazy. Nelze používat příkazy ukončené středníkem, deklarovat třídy nebo používat řídící struktury jako if, foreach, switch, return, try, throw atd. Místo nich Latte nabízí své vlastní tagy. Nelze používat ani atributy, backticks či některé magické konstanty. Také nelze použít unset, echo, include, require, exit, eval, protože nejde o funkce, ale o speciální jazykové konstrukce PHP. Z komentářů jsou podporovány pouze víceřádkové /* ... */.

Tato omezení lze obejít aktivací rozšíření RawPhpExtension, které umožňuje používat ve značce {php ...} jakýkoliv PHP kód na zodpovědnost autora šablony.