Nette Documentation Preview

syntax 
Sintaksa
********

.[perex]
Syntax Latte je nastal zaradi praktičnih zahtev spletnih oblikovalcev. Iskali smo uporabniku najbolj prijazno sintakso, s katero lahko elegantno zapišete konstrukcije, ki so sicer pravi izziv.
Hkrati so vsi izrazi zapisani popolnoma enako kot v jeziku PHP, zato se vam ni treba učiti novega jezika. Preprosto kar najbolje izkoristite tisto, kar že poznate.

Spodaj je minimalna predloga, ki ponazarja nekaj osnovnih elementov: oznake, n:atribute, komentarje in filtre.

```latte
{* to je komentar *}
<ul n:if="$items">                {* n:if je n:atribut *}
{foreach $items as $item}         {* oznaka, ki predstavlja zanko foreach *}
	<li>{$item|capitalize}</li>   {* oznaka, ki izpiše spremenljivko s filtrom *}
{/foreach}                        {* konec cikla *}
</ul>
```

Podrobneje si oglejmo te pomembne elemente in kako vam lahko pomagajo zgraditi neverjetno predlogo.


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

Predloga vsebuje oznake, ki nadzorujejo logiko predloge (na primer zanke *foreach*) ali izhodne izraze. Za oboje se uporablja en sam razmejitveni znak `{ ... }`, zato vam ni treba razmišljati o tem, kateri razmejitveni znak uporabiti v kateri situaciji, kot je to v drugih sistemih.
Če znaku `{` sledi narekovaj ali presledek, ga Latte ne obravnava kot začetek oznake, zato lahko v predlogah brez težav uporabljate konstrukcije JavaScript, JSON ali pravila CSS.

Oglejte si [pregled vseh oznak |tags]. Poleg tega lahko ustvarite tudi [oznake po meri |extending-latte#tags].


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

Znotraj oznak lahko uporabite izraze PHP, ki jih dobro poznate:

- spremenljivke
- nizov (vključno s HEREDOC in NOWDOC), polj, števil itd.
- [operatorji |https://www.php.net/manual/en/language.operators.php]
- klice funkcij in metod (ki so lahko omejeni s [peskovnikom |sandbox])
- [ujemanje |https://www.php.net/manual/en/control-structures.match.php]
- [anonimne funkcije |https://www.php.net/manual/en/functions.arrow.php]
- [povratni klici |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- večvrstični komentarji `/* ... */`
- itd.

Poleg tega Latte dodaja več [lepih razširitev |#Syntactic Sugar] sintakse PHP.


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

Vsako parno oznako, kot je `{if} … {/if}`, ki deluje na posamezen element HTML, lahko zapišemo v zapisu [n:atribut |#n:attribute]. Na primer, `{foreach}` iz zgornjega primera je mogoče zapisati tudi na ta način:

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

Funkcija nato ustreza elementu HTML, v katerem je zapisana:

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

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

Izpisi:

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

Z uporabo predpone `inner-` lahko spremenimo obnašanje tako, da funkcionalnost velja samo za telo elementa:

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

Izpisi:

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

S predpono `tag-` se funkcionalnost uporablja samo za oznake HTML:

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

Glede na vrednost spremenljivke `$url` se izpiše:

```latte
// when $url is empty
<p>Title</p>

// when $url equals 'https://nette.org'
<p><a href="https://nette.org">Title</a></p>
```

Vendar pa n:atributi niso le bližnjica za parne oznake, temveč obstajajo tudi nekateri čisti n:atributi, na primer koderjev najboljši prijatelj [n:class |tags#n:class].


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

Oglejte si povzetek [standardnih filtrov |filters].

Latte omogoča klicanje filtrov z uporabo zapisa z znakom pipe (pred njim je dovoljen presledek):

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

Filtri se lahko verižijo, v tem primeru se uporabljajo po vrstnem redu od leve proti desni:

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

Parametri so navedeni za imenom filtra, ločeni z dvopičjem ali vejico:

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

Filtre je mogoče uporabiti na izrazu:

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

Na bloku:

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

Ali neposredno na vrednosti (v kombinaciji z [`{=expr}` | https://latte.nette.org/sl/tags#printing] oznako):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Dinamične oznake HTML .[#toc-dynamic-html-tags]
===============================================

Latte podpira dinamične oznake HTML, ki so uporabne, kadar je potrebna prilagodljivost imen oznak:

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

Zgornja koda lahko na primer ustvari `<h1>Heading</h1>` ali `<h2>Heading</h2>` odvisno od vrednosti spremenljivke `$level`. Dinamične oznake HTML v Latte morajo biti vedno v paru. Njihova alternativa je [n:tag |tags#n:tag].

Ker je Latte varen sistem za oblikovanje predlog, preveri, ali je dobljeno ime oznake veljavno in ne vsebuje neželenih ali zlonamernih vrednosti. Prav tako zagotavlja, da je končno ime oznake vedno enako začetnemu imenu oznake.


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

Komentarji so zapisani na ta način in se ne vključijo v izpis:

```latte
{* to je komentar v Latte *}
```

Komentarji PHP delujejo znotraj oznak:

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


Sintaktični sladkor .[#toc-syntactic-sugar]
===========================================


Nizi brez narekovajev .[#toc-strings-without-quotation-marks]
-------------------------------------------------------------

Za preproste nize lahko izpustite narekovaje:

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

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

Enostavni nizi so tisti, ki so sestavljeni izključno iz črk, številk, podčrtank, pomišljajev in pik. Ne smejo se začeti s številko in ne smejo se začeti ali končati s pomišljajem.
Ne smejo biti sestavljeni samo iz velikih črk in podčrtajev, ker se potem štejejo za konstanto (npr. `PHP_VERSION`).
In ne sme biti v koliziji s ključnimi besedami `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Kratek terminarni operator .[#toc-short-ternary-operator]
---------------------------------------------------------

Če je tretja vrednost ternarnega operatorja prazna, jo lahko izpustite:

```latte
as in PHP:   {$stock ? 'In stock' : ''}

abbreviated: {$stock ? 'In stock'}
```


Sodobni zapis ključev v polju .[#toc-modern-key-notation-in-the-array]
----------------------------------------------------------------------

Ključe polja lahko zapišete podobno kot poimenovane parametre pri klicanju funkcij:

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

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


Filtri .[#toc-filters]
----------------------

Filtre lahko uporabite za katerikoli izraz, samo celoten izraz zapišite v oklepaj:

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


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

Operater `in` se lahko uporablja za zamenjavo funkcije `in_array()`. Primerjava je vedno stroga:

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


Okno v zgodovino .[#toc-a-window-into-history]
----------------------------------------------

Latte je v svoji zgodovini ponudil številne sintaktične bonbončke, ki so se nekaj let pozneje pojavili tudi v samem jeziku PHP. V Latte je bilo na primer mogoče zapisati polja kot `[1, 2, 3]` namesto `array(1, 2, 3)` ali uporabiti operator nullsafe `$obj?->foo` veliko prej, preden je bilo to mogoče v samem PHP. Latte je uvedel tudi operator za razširitev polj `(expand) $arr`, ki je enakovreden današnjemu operatorju `...$arr` iz PHP.

Operator undefined-safe `??->`, ki je podoben operatorju nullsafe `?->`, vendar ne sproži napake, če spremenljivka ne obstaja, je bil ustvarjen iz zgodovinskih razlogov in danes priporočamo uporabo standardnega operatorja PHP `?->`.


Omejitve PHP v Latte .[#toc-php-limitations-in-latte]
=====================================================

V Latte je mogoče zapisati samo izraze PHP. To pomeni, da ni mogoče uporabljati izrazov, ki se končajo s podpičjem. Ne morete deklarirati razredov ali uporabljati [kontrolnih struktur |https://www.php.net/manual/en/language.control-structures.php], kot so `if`, `foreach`, `switch`, `return`, `try`, `throw` in druge, namesto katerih Latte ponuja svoje [oznake |tags].
Prav tako ne morete uporabljati [atributov |https://www.php.net/manual/en/language.attributes.php], [zaklepajev |https://www.php.net/manual/en/language.operators.execution.php] ali [čarobnih konstant |https://www.php.net/manual/en/language.constants.magic.php].
Ne morete uporabiti niti `unset`, `echo`, `include`, `require`, `exit`, `eval`, ker to niso funkcije, temveč posebni konstrukti jezika PHP in zato niso izrazi. Podprti so samo večvrstični komentarji `/* ... */`.

Vendar lahko te omejitve obidete tako, da aktivirate razširitev [RawPhpExtension |develop#RawPhpExtension], ki vam omogoča uporabo katere koli kode PHP v oznaki `{php ...}` na odgovornost avtorja predloge.

Sintaksa

Syntax Latte je nastal zaradi praktičnih zahtev spletnih oblikovalcev. Iskali smo uporabniku najbolj prijazno sintakso, s katero lahko elegantno zapišete konstrukcije, ki so sicer pravi izziv. Hkrati so vsi izrazi zapisani popolnoma enako kot v jeziku PHP, zato se vam ni treba učiti novega jezika. Preprosto kar najbolje izkoristite tisto, kar že poznate.

Spodaj je minimalna predloga, ki ponazarja nekaj osnovnih elementov: oznake, n:atribute, komentarje in filtre.

{* to je komentar *}
<ul n:if="$items">                {* n:if je n:atribut *}
{foreach $items as $item}         {* oznaka, ki predstavlja zanko foreach *}
	<li>{$item|capitalize}</li>   {* oznaka, ki izpiše spremenljivko s filtrom *}
{/foreach}                        {* konec cikla *}
</ul>

Podrobneje si oglejmo te pomembne elemente in kako vam lahko pomagajo zgraditi neverjetno predlogo.

Oznake

Predloga vsebuje oznake, ki nadzorujejo logiko predloge (na primer zanke foreach) ali izhodne izraze. Za oboje se uporablja en sam razmejitveni znak { ... }, zato vam ni treba razmišljati o tem, kateri razmejitveni znak uporabiti v kateri situaciji, kot je to v drugih sistemih. Če znaku { sledi narekovaj ali presledek, ga Latte ne obravnava kot začetek oznake, zato lahko v predlogah brez težav uporabljate konstrukcije JavaScript, JSON ali pravila CSS.

Oglejte si pregled vseh oznak. Poleg tega lahko ustvarite tudi oznake po meri.

Latte razume PHP

Znotraj oznak lahko uporabite izraze PHP, ki jih dobro poznate:

Poleg tega Latte dodaja več lepih razširitev sintakse PHP.

n:atributi

Vsako parno oznako, kot je {if} … {/if}, ki deluje na posamezen element HTML, lahko zapišemo v zapisu n:atribut. Na primer, {foreach} iz zgornjega primera je mogoče zapisati tudi na ta način:

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

Funkcija nato ustreza elementu HTML, v katerem je zapisana:

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

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

Izpisi:

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

Z uporabo predpone inner- lahko spremenimo obnašanje tako, da funkcionalnost velja samo za telo elementa:

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

Izpisi:

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

S predpono tag- se funkcionalnost uporablja samo za oznake HTML:

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

Glede na vrednost spremenljivke $url se izpiše:

// when $url is empty
<p>Title</p>

// when $url equals 'https://nette.org'
<p><a href="https://nette.org">Title</a></p>

Vendar pa n:atributi niso le bližnjica za parne oznake, temveč obstajajo tudi nekateri čisti n:atributi, na primer koderjev najboljši prijatelj n:class.

Filtri

Oglejte si povzetek standardnih filtrov.

Latte omogoča klicanje filtrov z uporabo zapisa z znakom pipe (pred njim je dovoljen presledek):

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

Filtri se lahko verižijo, v tem primeru se uporabljajo po vrstnem redu od leve proti desni:

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

Parametri so navedeni za imenom filtra, ločeni z dvopičjem ali vejico:

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

Filtre je mogoče uporabiti na izrazu:

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

Na bloku:

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

Ali neposredno na vrednosti (v kombinaciji z {=expr} oznako):

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

Dinamične oznake HTML

Latte podpira dinamične oznake HTML, ki so uporabne, kadar je potrebna prilagodljivost imen oznak:

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

Zgornja koda lahko na primer ustvari <h1>Heading</h1> ali <h2>Heading</h2> odvisno od vrednosti spremenljivke $level. Dinamične oznake HTML v Latte morajo biti vedno v paru. Njihova alternativa je n:tag.

Ker je Latte varen sistem za oblikovanje predlog, preveri, ali je dobljeno ime oznake veljavno in ne vsebuje neželenih ali zlonamernih vrednosti. Prav tako zagotavlja, da je končno ime oznake vedno enako začetnemu imenu oznake.

Komentarji

Komentarji so zapisani na ta način in se ne vključijo v izpis:

{* to je komentar v Latte *}

Komentarji PHP delujejo znotraj oznak:

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

Sintaktični sladkor

Nizi brez narekovajev

Za preproste nize lahko izpustite narekovaje:

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

abbreviated: {var $arr = [hello, btn--default, €]}

Enostavni nizi so tisti, ki so sestavljeni izključno iz črk, številk, podčrtank, pomišljajev in pik. Ne smejo se začeti s številko in ne smejo se začeti ali končati s pomišljajem. Ne smejo biti sestavljeni samo iz velikih črk in podčrtajev, ker se potem štejejo za konstanto (npr. PHP_VERSION). In ne sme biti v koliziji s ključnimi besedami and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Kratek terminarni operator

Če je tretja vrednost ternarnega operatorja prazna, jo lahko izpustite:

as in PHP:   {$stock ? 'In stock' : ''}

abbreviated: {$stock ? 'In stock'}

Sodobni zapis ključev v polju

Ključe polja lahko zapišete podobno kot poimenovane parametre pri klicanju funkcij:

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

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

Filtri

Filtre lahko uporabite za katerikoli izraz, samo celoten izraz zapišite v oklepaj:

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

Operator in

Operater in se lahko uporablja za zamenjavo funkcije in_array(). Primerjava je vedno stroga:

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

Okno v zgodovino

Latte je v svoji zgodovini ponudil številne sintaktične bonbončke, ki so se nekaj let pozneje pojavili tudi v samem jeziku PHP. V Latte je bilo na primer mogoče zapisati polja kot [1, 2, 3] namesto array(1, 2, 3) ali uporabiti operator nullsafe $obj?->foo veliko prej, preden je bilo to mogoče v samem PHP. Latte je uvedel tudi operator za razširitev polj (expand) $arr, ki je enakovreden današnjemu operatorju ...$arr iz PHP.

Operator undefined-safe ??->, ki je podoben operatorju nullsafe ?->, vendar ne sproži napake, če spremenljivka ne obstaja, je bil ustvarjen iz zgodovinskih razlogov in danes priporočamo uporabo standardnega operatorja PHP ?->.

Omejitve PHP v Latte

V Latte je mogoče zapisati samo izraze PHP. To pomeni, da ni mogoče uporabljati izrazov, ki se končajo s podpičjem. Ne morete deklarirati razredov ali uporabljati kontrolnih struktur, kot so if, foreach, switch, return, try, throw in druge, namesto katerih Latte ponuja svoje oznake. Prav tako ne morete uporabljati atributov, zaklepajev ali čarobnih konstant. Ne morete uporabiti niti unset, echo, include, require, exit, eval, ker to niso funkcije, temveč posebni konstrukti jezika PHP in zato niso izrazi. Podprti so samo večvrstični komentarji /* ... */.

Vendar lahko te omejitve obidete tako, da aktivirate razširitev RawPhpExtension, ki vam omogoča uporabo katere koli kode PHP v oznaki {php ...} na odgovornost avtorja predloge.