Nette Documentation Preview

syntax 
Синтаксис
*********

.[perex]
Синтаксисът Latte е създаден от практическите нужди на уеб дизайнерите. Търсехме най-удобния синтаксис, с който можете елегантно да записвате конструкции, които иначе са истински проблем.
В същото време всички изрази са написани по същия начин, както в PHP, така че не е необходимо да учите нов език. Просто използвайте това, което вече знаете.

По-долу е представен минимален шаблон, който илюстрира няколко основни елемента: тагове, n:атрибути, коментари и филтри.

```latte
{* това е коментар *}
<ul n:if="$items">                {* n:if е n:atribut *}
{foreach $items as $item}         {* таг, представляващ цикъла foreach *}
	<li>{$item|capitalize}</li>   {* таг, който отпечатва променлива с филтър *}
{/foreach}                        {* край на цикъла *}
</ul>
```

Нека разгледаме по-отблизо тези важни елементи и как те могат да ви помогнат да създадете невероятен шаблон.


Етикети .[#toc-tags]
====================

Шаблонът съдържа тагове, които управляват логиката на шаблона (напр. цикли *foreach*) или изходните изрази. Един и същ сепаратор се използва и в двата случая `{ ... }`, така че не е необходимо да мислите кой сепаратор да използвате в дадена ситуация, както е при други системи.
Ако `{` е последвано от обърната запетая или интервал, Latte не го счита за начало на таг, така че можете да използвате JavaScript, JSON или CSS правила в шаблоните си без проблеми.

Вижте [преглед на всички етикети |tags]. Можете също така да създавате [персонализирани тагове |extending-latte#Tags].


Latte разбира PHP .[#toc-latte-understands-php]
===============================================

Вътре в таговете можете да използвате добре познати изрази на PHP:

- променливи
- низове (включително HEREDOC и NOWDOC), масиви, числа и др.
- [оператори |https://www.php.net/manual/en/language.operators.php]
- извиквания на функции и методи (които могат да бъдат ограничени от [пясъчната кутия |sandbox]).
- [кореспонденция |https://www.php.net/manual/en/control-structures.match.php]
- [анонимни функции |https://www.php.net/manual/en/functions.arrow.php]
- [обратни повиквания |https://www.php.net/manual/en/functions.first_class_callable_syntax.php]
- многоредови коментари `/* ... */`
- и т.н.

Latte добавя и някои [хубави разширения на |#Syntactic-Sugar] синтаксиса на PHP.


n:атрибути .[#toc-n-attributes]
===============================

Всеки сдвоен таг, например `{if} … {/if}`, който работи с един HTML елемент, може да бъде записан в нотация [n:attribute |#n:attribute]. Например `{foreach}` в горния пример може да се запише като

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

След това функционалността съответства на HTML елемента, в който е записана:

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

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

Отпечатъци:

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

Използвайки префикса `inner-`, можем да променим поведението, така че функционалността да се прилага само за тялото на елемента:

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

Отпечатъци:

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

Или с префикс `tag-` функционалността се прилага само за HTML тагове:

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

В зависимост от стойността на променливата `$url` ще бъде изведено следното:

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

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

Въпреки това n:attributes не е само съкращение за сдвоени тагове, но има и някои чисти n:attributes, като например най-добрият приятел на програмистите [n:class |tags#n-class].


Филтри .[#toc-filters]
======================

Вижте кратко описание на [стандартните филтри |filters].

Latte ви позволява да извиквате филтри със знака pipe (позволен е интервал преди филтъра):

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

Филтрите могат да бъдат свързани във верига, като в този случай се прилагат в последователност отляво надясно:

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

Параметрите се поставят след името на филтъра, разделени с двоеточие или запетая:

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

Към даден израз могат да се прилагат филтри:

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

В блока:

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

Или директно върху стойността (в комбинация с [`{=expr}` | https://latte.nette.org/bg/tags#printing] таг):
```latte
<h1>{='  Hello world  '|trim}<h1>
```


Динамични HTML етикети .[#toc-dynamic-html-tags]
================================================

Latte поддържа динамични HTML тагове, които са полезни, когато се нуждаете от гъвкавост в имената на таговете:

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

Например, кодът по-горе може да генерира `<h1>Heading</h1>` или `<h2>Heading</h2>` в зависимост от стойността на променливата `$level`. Динамичните HTML тагове в Latte трябва винаги да бъдат сдвоени. Тяхната алтернатива е [n:tag |tags#n:tag].

Тъй като Latte е сигурна система за шаблониране, тя проверява дали полученото име на тага е валидно и не съдържа нежелани или злонамерени стойности. Тя също така гарантира, че името на крайния таг винаги е същото като името на началния таг.


Коментарите са изключени за .[#toc-comments]
============================================

Коментарите се записват по този начин и не влизат в изхода:

```latte
{* това е коментар в Latte *}
```

Коментарите на PHP работят в рамките на тагове:

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


Синтактична захар .[#toc-syntactic-sugar]
=========================================


Некотирани низове .[#toc-strings-without-quotation-marks]
---------------------------------------------------------

За прости низове не могат да се използват кавички:

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

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

Прости низове са тези, които се състоят само от букви, цифри, подчертавания, тирета и точки. Те не трябва да започват с цифра и не трябва да започват или завършват с дефис.
То не трябва да се състои само от главни букви и подчертавания, защото тогава се счита за константа (например `PHP_VERSION`).
И не трябва да се припокрива с ключовите думи `and`, `array`, `clone`, `default`, `false`, `in`, `instanceof`, `new`, `null`, `or`, `return`, `true`, `xor`.


Кратък троен оператор .[#toc-short-ternary-operator]
----------------------------------------------------

Ако третата стойност на троичния оператор е празна, тя може да бъде пропусната:

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

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


Съвременна нотация на ключови масиви .[#toc-modern-key-notation-in-the-array]
-----------------------------------------------------------------------------

Ключовете на масива могат да се записват по същия начин като именуваните параметри при извикване на функции:

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

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


Филтри .[#toc-filters]
----------------------

Филтрите могат да се използват за всякакви изрази, просто поставете всичко в скоби:

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


Оператор `in` .[#toc-operator-in]
---------------------------------

Операторът `in` може да се използва за замяна на функцията `in_array()`. Сравнението винаги е строго:

```latte
{* като in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}
```


Прозорец към историята .[#toc-a-window-into-history]
----------------------------------------------------

В своята история Latte предлага няколко синтаксиса, които се появяват в самия PHP няколко години по-късно. Например в Latte беше възможно да се записват масиви като `[1, 2, 3]` вместо `array(1, 2, 3)`, или да използвате оператора nullsafe `$obj?->foo` много преди това да е възможно в самия PHP. Latte въведе и оператора за разширяване на масива `(expand) $arr`, който е еквивалентен на днешния оператор `...$arr` от PHP.

Операторът undefined-safe `??->`, който е подобен на оператора nullsafe `?->`, но не предизвиква грешка, ако променливата не съществува, е създаден по исторически причини и днес препоръчваме да се използва стандартният оператор на PHP `?->`.


Ограничения на PHP в Latte .[#toc-php-limitations-in-latte]
===========================================================

В Latte могат да се записват само PHP изрази. Това означава, че не могат да се използват изрази, завършващи с точка и запетая. Не можете да декларирате класове или да използвате [структури за управление |https://www.php.net/manual/en/language.control-structures.php], като например `if`, `foreach`, `switch`, `return`, `try`, `throw` и други, вместо които Latte предлага своите [тагове |tags].
Също така не можете да използвате [атрибути |https://www.php.net/manual/en/language.attributes.php], [задни тирета |https://www.php.net/manual/en/language.operators.execution.php] или други [магически константи |https://www.php.net/manual/en/language.constants.magic.php].
Не можете дори да използвате `unset`, `echo`, `include`, `require`, `exit`, `eval`, защото те не са функции, а специални конструкции на езика PHP и следователно не са изрази. Поддържат се само многоредови коментари `/* ... */`.

Въпреки това можете да заобиколите тези ограничения, като активирате [разширението RawPhpExtension |develop#RawPhpExtension], което ви позволява да използвате всякакъв PHP код в тага `{php ...}` под отговорността на автора на шаблона.

Синтаксис

Синтаксисът Latte е създаден от практическите нужди на уеб дизайнерите. Търсехме най-удобния синтаксис, с който можете елегантно да записвате конструкции, които иначе са истински проблем. В същото време всички изрази са написани по същия начин, както в PHP, така че не е необходимо да учите нов език. Просто използвайте това, което вече знаете.

По-долу е представен минимален шаблон, който илюстрира няколко основни елемента: тагове, n:атрибути, коментари и филтри.

{* това е коментар *}
<ul n:if="$items">                {* n:if е n:atribut *}
{foreach $items as $item}         {* таг, представляващ цикъла foreach *}
	<li>{$item|capitalize}</li>   {* таг, който отпечатва променлива с филтър *}
{/foreach}                        {* край на цикъла *}
</ul>

Нека разгледаме по-отблизо тези важни елементи и как те могат да ви помогнат да създадете невероятен шаблон.

Етикети

Шаблонът съдържа тагове, които управляват логиката на шаблона (напр. цикли foreach) или изходните изрази. Един и същ сепаратор се използва и в двата случая { ... }, така че не е необходимо да мислите кой сепаратор да използвате в дадена ситуация, както е при други системи. Ако { е последвано от обърната запетая или интервал, Latte не го счита за начало на таг, така че можете да използвате JavaScript, JSON или CSS правила в шаблоните си без проблеми.

Вижте преглед на всички етикети. Можете също така да създавате персонализирани тагове.

Latte разбира PHP

Вътре в таговете можете да използвате добре познати изрази на PHP:

Latte добавя и някои хубави разширения на синтаксиса на PHP.

n:атрибути

Всеки сдвоен таг, например {if} … {/if}, който работи с един HTML елемент, може да бъде записан в нотация n:attribute. Например {foreach} в горния пример може да се запише като

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

След това функционалността съответства на HTML елемента, в който е записана:

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

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

Отпечатъци:

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

Използвайки префикса inner-, можем да променим поведението, така че функционалността да се прилага само за тялото на елемента:

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

Отпечатъци:

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

Или с префикс tag- функционалността се прилага само за HTML тагове:

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

В зависимост от стойността на променливата $url ще бъде изведено следното:

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

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

Въпреки това n:attributes не е само съкращение за сдвоени тагове, но има и някои чисти n:attributes, като например най-добрият приятел на програмистите n:class.

Филтри

Вижте кратко описание на стандартните филтри.

Latte ви позволява да извиквате филтри със знака pipe (позволен е интервал преди филтъра):

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

Филтрите могат да бъдат свързани във верига, като в този случай се прилагат в последователност отляво надясно:

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

Параметрите се поставят след името на филтъра, разделени с двоеточие или запетая:

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

Към даден израз могат да се прилагат филтри:

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

В блока:

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

Или директно върху стойността (в комбинация с {=expr} таг):

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

Динамични HTML етикети

Latte поддържа динамични HTML тагове, които са полезни, когато се нуждаете от гъвкавост в имената на таговете:

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

Например, кодът по-горе може да генерира <h1>Heading</h1> или <h2>Heading</h2> в зависимост от стойността на променливата $level. Динамичните HTML тагове в Latte трябва винаги да бъдат сдвоени. Тяхната алтернатива е n:tag.

Тъй като Latte е сигурна система за шаблониране, тя проверява дали полученото име на тага е валидно и не съдържа нежелани или злонамерени стойности. Тя също така гарантира, че името на крайния таг винаги е същото като името на началния таг.

Коментарите са изключени за

Коментарите се записват по този начин и не влизат в изхода:

{* това е коментар в Latte *}

Коментарите на PHP работят в рамките на тагове:

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

Синтактична захар

Некотирани низове

За прости низове не могат да се използват кавички:

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

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

Прости низове са тези, които се състоят само от букви, цифри, подчертавания, тирета и точки. Те не трябва да започват с цифра и не трябва да започват или завършват с дефис. То не трябва да се състои само от главни букви и подчертавания, защото тогава се счита за константа (например PHP_VERSION). И не трябва да се припокрива с ключовите думи and, array, clone, default, false, in, instanceof, new, null, or, return, true, xor.

Кратък троен оператор

Ако третата стойност на троичния оператор е празна, тя може да бъде пропусната:

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

abbreviated: {$stock ? 'In stock'}

Съвременна нотация на ключови масиви

Ключовете на масива могат да се записват по същия начин като именуваните параметри при извикване на функции:

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

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

Филтри

Филтрите могат да се използват за всякакви изрази, просто поставете всичко в скоби:

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

Оператор in

Операторът in може да се използва за замяна на функцията in_array(). Сравнението винаги е строго:

{* като in_array($item, $items, true) *}
{if $item in $items}
	...
{/if}

Прозорец към историята

В своята история Latte предлага няколко синтаксиса, които се появяват в самия PHP няколко години по-късно. Например в Latte беше възможно да се записват масиви като [1, 2, 3] вместо array(1, 2, 3), или да използвате оператора nullsafe $obj?->foo много преди това да е възможно в самия PHP. Latte въведе и оператора за разширяване на масива (expand) $arr, който е еквивалентен на днешния оператор ...$arr от PHP.

Операторът undefined-safe ??->, който е подобен на оператора nullsafe ?->, но не предизвиква грешка, ако променливата не съществува, е създаден по исторически причини и днес препоръчваме да се използва стандартният оператор на PHP ?->.

Ограничения на PHP в Latte

В Latte могат да се записват само PHP изрази. Това означава, че не могат да се използват изрази, завършващи с точка и запетая. Не можете да декларирате класове или да използвате структури за управление, като например if, foreach, switch, return, try, throw и други, вместо които Latte предлага своите тагове. Също така не можете да използвате атрибути, задни тирета или други магически константи. Не можете дори да използвате unset, echo, include, require, exit, eval, защото те не са функции, а специални конструкции на езика PHP и следователно не са изрази. Поддържат се само многоредови коментари /* ... */.

Въпреки това можете да заобиколите тези ограничения, като активирате разширението RawPhpExtension, което ви позволява да използвате всякакъв PHP код в тага {php ...} под отговорността на автора на шаблона.