Nette Documentation Preview

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

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

Ниже приведен минимальный шаблон, иллюстрирующий несколько базовых элементов: теги, n:attributes, комментарии и фильтры.

```latte
{* this is a comment *}
<ul n:if="$items">                {* n:if is n:atribut *}
{foreach $items as $item}         {* tag representing foreach loop *}
	<li>{$item|capitalize}</li>   {* tag that prints a variable with a filter *}
{/foreach}                        {* end of cycle *}
</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:attributes .[#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>
```

Prints:

```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 позволяет вызывать фильтры с помощью знака трубы (пробел перед фильтром допускается):

```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/ru/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
{* this is a comment in 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
{* like 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:attributes, комментарии и фильтры.

{* this is a comment *}
<ul n:if="$items">                {* n:if is n:atribut *}
{foreach $items as $item}         {* tag representing foreach loop *}
	<li>{$item|capitalize}</li>   {* tag that prints a variable with a filter *}
{/foreach}                        {* end of cycle *}
</ul>

Давайте подробнее рассмотрим эти важные элементы и то, как они могут помочь вам создать невероятный шаблон.

Теги

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

Смотрите обзор всех тегов. Кроме того, вы можете создавать пользовательские теги.

Latte понимает PHP

Внутри тегов можно использовать выражения PHP, которые вы хорошо знаете:

Кроме того, Latte добавляет несколько приятных расширений к синтаксису PHP.

n:attributes

Каждый парный тег, например {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>

Prints:

<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 позволяет вызывать фильтры с помощью знака трубы (пробел перед фильтром допускается):

<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 является безопасной системой шаблонизации, она проверяет, что результирующее имя тега является корректным и не содержит нежелательных или вредоносных значений. Также проверяется, что имя конечного тега всегда совпадает с именем открывающего тега.

Комментарии

Комментарии пишутся таким образом и не попадают в вывод:

{* this is a comment in 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(). Сравнение всегда строгое:

{* like 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 ...} под ответственность автора шаблона.