Теги Latte

Огляд та опис усіх тегів системи шаблонів Latte, які вам стандартно доступні.

Виведення

{$var} {...} {=...}

У Latte використовується тег {=...} для виведення будь-якого виразу. Latte дбає про вашу зручність, тому якщо вираз починається зі змінної або виклику функції, не потрібно писати знак рівності. Що на практиці означає, що його майже ніколи не потрібно писати:

Ім'я: {$name} {$surname}<br>
Вік: {date('Y') - $birth}<br>

Як вираз ви можете записати все, що знаєте з PHP. Вам просто не потрібно вивчати нову мову. Наприклад:

{='0' . ($num ?? $num * 3) . ', ' . PHP_VERSION}

Будь ласка, не шукайте в попередньому прикладі жодного сенсу, але якби ви його там знайшли, напишіть нам :-)

Екранування виведення

Яке найважливіше завдання системи шаблонів? Запобігти діркам у безпеці. І саме це робить Latte завжди, коли ви щось виводите. Автоматично це екранує:

<p>{='one < two'}</p>   {* виведе: '<p>one &lt; two</p>' *}

Щоб бути точними, Latte використовує контекстно-залежне екранування, що є настільки важливою та унікальною річчю, що ми присвятили цьому окремий розділ.

А що, якщо ви виводите вміст, закодований у HTML з надійного джерела? Тоді можна легко вимкнути екранування:

{$trustedHtmlString|noescape}

Неправильне використання фільтра noescape може призвести до виникнення уразливості XSS! Ніколи не використовуйте його, якщо ви не повністю впевнені в тому, що робите, і що рядок, який виводиться, походить з надійного джерела.

Виведення в JavaScript

Завдяки контекстно-залежному екрануванню надзвичайно легко виводити змінні всередині JavaScript, а правильне екранування забезпечить Latte.

Змінна не обов'язково має бути рядком, підтримується будь-який тип даних, який потім кодується як JSON:

{var $foo = ['hello', true, 1]}
<script>
	alert({$foo});
</script>

Згенерує:

<script>
	alert(["hello", true, 1]);
</script>

Це також причина, чому навколо змінної не пишуться лапки: Latte додасть їх для рядків самостійно. А якщо ви захочете вставити рядкову змінну в інший рядок, просто об'єднайте їх:

<script>
	alert('Hello ' + {$name} + '!');  // OK

	alert({="Hello $name!"});         // OK

	alert('Hello {$name} !');         // ПОМИЛКА!
</script>

Фільтри

Виведений вираз може бути змінений фільтром. Так, наприклад, рядок переведемо у верхній регістр і скоротимо до максимум 30 символів:

{$string|upper|truncate:30}

Фільтри можна використовувати і для окремих частин виразу таким чином:

{$left . ($middle|upper) . $right}

Умови

{if} {elseif} {else}

Умови поводяться так само, як їхні аналоги в PHP. Ви можете використовувати в них ті самі вирази, які знаєте з PHP, вам не потрібно вивчати нову мову.

{if $product->inStock > Stock::Minimum}
	В наявності
{elseif $product->isOnWay()}
	В дорозі
{else}
	Недоступно
{/if}

Як і будь-який парний тег, так і пару {if} ... {/if} можна записувати у вигляді n:атрибуту, наприклад:

<p n:if="$count > 0">В наявності {$count} штук</p>

Чи знаєте ви, що до n:атрибутів можна додати префікс tag-? Тоді умова стосуватиметься лише виведення HTML-тегів, а вміст між ними виводитиметься завжди:

<a href="..." n:tag-if="$clickable">Hello</a>

{* виведе 'Hello' коли $clickable є false *}
{* виведе '<a href="...">Hello</a>' коли $clickable є true *}

Чудово.

n:else

Якщо умову {if} ... {/if} записати у вигляді n:атрибуту, ви маєте можливість вказати й альтернативну гілку за допомогою n:else:

<strong n:if="$count > 0">В наявності {$count} штук</strong>

<em n:else>недоступно</em>

Атрибут n:else можна використовувати також у парі з n:ifset, n:foreach, n:try, n:ifcontent та n:ifchanged.

{/if $cond}

Можливо, вас здивує, що вираз в умові {if} можна вказати також у закриваючому тезі. Це зручно в ситуаціях, коли при відкритті умови ми ще не знаємо її значення. Назвемо це відкладеним рішенням.

Наприклад, ми починаємо виводити таблицю із записами з бази даних і лише після завершення виведення розуміємо, що в базі даних не було жодного запису. Тоді поставимо умову на це в кінцевому тезі {/if}, і якщо жодного запису не буде, нічого з цього не виведеться:

{if}
	<h1>Виведення рядків з бази даних</h1>

	<table>
	{foreach $resultSet as $row}
		...
	{/foreach}
	</table>
{/if isset($row)}

Зручно, чи не так?

У відкладеній умові можна використовувати й {else}, але не {elseif}.

{ifset} {elseifset}

Див. також {ifset block}

За допомогою умови {ifset $var} ми перевіряємо, чи існує змінна (або кілька змінних) і має значення, відмінне від null. Власне, це те саме, що if (isset($var)) у PHP. Як і будь-який парний тег, його можна записувати й у вигляді n:атрибуту, тож покажемо це як приклад:

<meta name="robots" content={$robots} n:ifset="$robots">

{ifchanged}

{ifchanged} перевіряє, чи змінилося значення змінної з останньої ітерації в циклі (foreach, for або while).

Якщо в тезі вказати одну або кілька змінних, він перевірятиме, чи змінилася якась із них, і відповідно виведе вміст. Наприклад, наступний приклад виведе першу літеру імені як заголовок щоразу, коли вона зміниться під час виведення імен:

{foreach ($names|sort) as $name}
	{ifchanged $name[0]} <h2>{$name[0]}</h2> {/ifchanged}

	<p>{$name}</p>
{/foreach}

Однак, якщо не вказати жодного аргументу, перевірятиметься відрендерений вміст порівняно з його попереднім станом. Це означає, що в попередньому прикладі ми можемо спокійно опустити аргумент у тезі. І, звичайно, також можемо використовувати n:атрибут:

{foreach ($names|sort) as $name}
	<h2 n:ifchanged>{$name[0]}</h2>

	<p>{$name}</p>
{/foreach}

Всередині {ifchanged} можна також вказати клаузулу {else}.

{switch} {case} {default}

Порівнює значення з кількома варіантами. Це аналог умовного оператора switch, який ви знаєте з PHP. Однак Latte його вдосконалює:

• використовує строге порівняння (===)
• не потребує break

Це, отже, точний еквівалент структури match, яка з'явилася в PHP 8.0.

{switch $transport}
	{case train}
		Поїздом
	{case plane}
		Літаком
	{default}
		Інакше
{/switch}

Клаузула {case} може містити кілька значень, розділених комами:

{switch $status}
{case $status::New}<b>новий елемент</b>
{case $status::Sold, $status::Unknown}<i>недоступний</i>
{/switch}

Цикли

У Latte ви знайдете всі цикли, які знаєте з PHP: foreach, for та while.

{foreach}

Цикл записуємо абсолютно так само, як у PHP:

{foreach $langs as $code => $lang}
	<span>{$lang}</span>
{/foreach}

Крім того, він має кілька зручних функцій, про які ми зараз розповімо.

Latte, наприклад, перевіряє, чи створені змінні випадково не перезаписують глобальні змінні з тією ж назвою. Це рятує ситуації, коли ви розраховуєте, що в $lang є поточна мова сторінки, і не усвідомлюєте, що foreach $langs as $lang вам цю змінну перезаписало.

Цикл foreach також можна дуже елегантно та економно записати за допомогою n:атрибуту:

<ul>
	<li n:foreach="$items as $item">{$item->name}</li>
</ul>

Чи знаєте ви, що до n:атрибутів можна додати префікс inner-? Тоді в циклі повторюватиметься лише вміст елемента:

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

Отже, виведеться щось на зразок:

<div>
	<h4>Foo</h4>
	<p>Lorem ipsum.</p>
	<h4>Bar</h4>
	<p>Sit dolor.</p>
</div>

{else}

Всередині циклу foreach можна вказати клаузулу {else}, вміст якої відобразиться, якщо цикл порожній:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>На жаль, у цьому списку немає користувачів</em></li>
	{/foreach}
</ul>

$iterator

Всередині циклу foreach Latte створює змінну $iterator, за допомогою якої ми можемо дізнаватися корисну інформацію про поточний цикл:

• $iterator->first – чи це перший прохід циклу?
• $iterator->last – чи це останній прохід?
• $iterator->counter – який це прохід, рахуючи від одиниці?
• $iterator->counter0 – який це прохід, рахуючи від нуля?
• $iterator->odd – чи це непарний прохід?
• $iterator->even – чи це парний прохід?
• $iterator->parent – ітератор, що оточує поточний
• $iterator->nextValue – наступний елемент у циклі
• $iterator->nextKey – ключ наступного елемента в циклі

{foreach $rows as $row}
	{if $iterator->first}<table>{/if}

	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>

	{if $iterator->last}</table>{/if}
{/foreach}

Latte розумний, і $iterator->last працює не лише з масивами, а й коли цикл проходить над загальним ітератором, де заздалегідь невідома кількість елементів.

{first} {last} {sep}

Ці теги можна використовувати всередині циклу {foreach}. Вміст {first} відрендериться, якщо це перший прохід. Вміст {last} відрендериться … чи вгадаєте ви? Так, якщо це останній прохід. Це фактично скорочення для {if $iterator->first} та {if $iterator->last}.

Теги також можна елегантно використовувати як n:атрибут:

{foreach $rows as $row}
	{first}<h1>Список імен</h1>{/first}

	<p>{$row->name}</p>

	<hr n:last>
{/foreach}

Вміст тегу {sep} відрендериться, якщо прохід не є останнім, тому він зручний для рендерингу роздільників, наприклад, ком між виведеними елементами:

{foreach $items as $item} {$item} {sep}, {/sep} {/foreach}

Це досить практично, чи не так?

{iterateWhile}

Спрощує групування лінійних даних під час ітерації в циклі foreach, виконуючи ітерацію у вкладеному циклі, доки умова виконана. Прочитайте детальний посібник.

Може також елегантно замінити {first} та {last} у прикладі вище:

{foreach $rows as $row}
	<table>

	{iterateWhile}
	<tr id="row-{$iterator->counter}">
		<td>{$row->name}</td>
		<td>{$row->email}</td>
	</tr>
	{/iterateWhile true}

	</table>
{/foreach}

Див. також фільтри batch та group.

{for}

Цикл записуємо абсолютно так само, як у PHP:

{for $i = 0; $i < 10; $i++}
	<span>Елемент {$i}</span>
{/for}

Тег також можна використовувати як n:атрибут:

<h1 n:for="$i = 0; $i < 10; $i++">{$i}</h1>

{while}

Цикл знову записуємо абсолютно так само, як у PHP:

{while $row = $result->fetch()}
	<span>{$row->title}</span>
{/while}

Або як n:атрибут:

<span n:while="$row = $result->fetch()">
	{$row->title}
</span>

Можливий також варіант з умовою в кінцевому тезі, що відповідає в PHP циклу do-while:

{while}
	<span>{$item->title}</span>
{/while $item = $item->getNext()}

{continueIf} {skipIf} {breakIf}

Для керування будь-яким циклом можна використовувати теги {continueIf ?} та {breakIf ?}, які переходять до наступного елемента відповідно або завершують цикл при виконанні умови:

{foreach $rows as $row}
	{continueIf $row->date < $now}
	{breakIf $row->parent === null}
	...
{/foreach}

Тег {skipIf} дуже схожий на {continueIf}, але не збільшує лічильник $iterator->counter, тому якщо ми його виводимо і водночас пропускаємо деякі елементи, в нумерації не буде пропусків. А також клаузула {else} відрендериться, якщо ми пропустимо всі елементи.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>На жаль, у цьому списку немає дорослих</em></li>
	{/foreach}
</ul>

{exitIf}

Завершує рендеринг шаблону або блоку при виконанні умови (так званий “early exit”).

{exitIf !$messages}

<h1>Повідомлення</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

Включення шаблону

{include 'file.latte'}

Див. також {include block}

Тег {include} завантажує та рендерить вказаний шаблон. Якщо говорити мовою нашої улюбленої мови PHP, це щось на зразок:

<?php include 'header.phtml'; ?>

Включені шаблони не мають доступу до змінних активного контексту, вони мають доступ лише до глобальних змінних.

Змінні до включеного шаблону можна передавати таким чином:

{include 'template.latte', foo: 'bar', id: 123}

Назва шаблону може бути будь-яким виразом у PHP:

{include $someVar}
{include $ajax ? 'ajax.latte' : 'not-ajax.latte'}

Включений вміст можна змінити за допомогою фільтрів. Наступний приклад видаляє весь HTML та змінює регістр літер:

<title>{include 'heading.latte' |stripHtml|capitalize}</title>

За замовчуванням успадкування шаблонів у цьому випадку ніяк не фігурує. Хоча у включеному шаблоні ми можемо використовувати блоки, не відбувається заміни відповідних блоків у шаблоні, до якого включається. Думайте про включені шаблони як про окремі ізольовані частини сторінок або модулів. Цю поведінку можна змінити за допомогою модифікатора with blocks:

{include 'template.latte' with blocks}

Зв'язок між назвою файлу, вказаною в тезі, та файлом на диску є справою завантажувача.

{sandbox}

При включенні шаблону, створеного кінцевим користувачем, вам слід розглянути режим sandbox (більше інформації в документації sandbox):

{sandbox 'untrusted.latte', level: 3, data: $menu}

{block}

Див. також {block name}

Блоки без імені служать як спосіб застосування фільтрів до частини шаблону. Наприклад, так можна застосувати фільтр strip, який видаляє зайві пробіли:

{block|strip}
<ul>
	<li>Hello World</li>
</ul>
{/block}

Обробка винятків

{try}

Завдяки цьому тегу надзвичайно легко створювати надійні шаблони.

Якщо під час рендерингу блоку {try} виникає виняток, весь блок відкидається, і рендеринг продовжується після нього:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
{/try}

Вміст у необов'язковій клаузулі {else} рендериться лише тоді, коли виникає виняток:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>На жаль, не вдалося завантажити твіти.</p>
{/try}

Тег також можна використовувати як n:атрибут:

<ul n:try>
	...
</ul>

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

{rollback}

Блок {try} можна зупинити та пропустити також вручну за допомогою {rollback}. Завдяки цьому вам не потрібно заздалегідь перевіряти всі вхідні дані, і лише під час рендерингу ви можете вирішити, що об'єкт взагалі не хочете рендерити:

{try}
<ul>
	{foreach $people as $person}
 		{skipIf $person->age < 18}
 		<li>{$person->name}</li>
	{else}
		{rollback}
	{/foreach}
</ul>
{/try}

Змінні

{var} {default}

Нові змінні ми створюємо в шаблоні тегом {var}:

{var $name = 'John Smith'}
{var $age = 27}

{* Множинна декларація *}
{var $name = 'John Smith', $age = 27}

Тег {default} працює подібно, але створює змінні лише тоді, коли вони не існують. Якщо змінна вже існує і містить значення null, вона не буде перезаписана:

{default $lang = 'uk'}

Ви можете вказувати й типи змінних. Поки що вони інформативні, і Latte їх не перевіряє.

{var string $name = $article->getTitle()}
{default int $id = 0}

{parameters}

Так само, як функція оголошує свої параметри, може й шаблон на початку оголосити свої змінні:

{parameters
	$a,
	?int $b,
	int|string $c = 10
}

Змінні $a та $b без вказаного значення за замовчуванням автоматично мають значення за замовчуванням null. Оголошені типи поки що інформативні, і Latte їх не перевіряє.

Інші змінні, крім оголошених, до шаблону не передаються. Цим він відрізняється від тегу {default}.

{capture}

Захоплює виведення у змінну:

{capture $var}
<ul>
	<li>Hello World</li>
</ul>
{/capture}

<p>Захоплено: {$var}</p>

Тег можна, подібно до будь-якого парного тегу, записати також як n:атрибут:

<ul n:capture="$var">
	<li>Hello World</li>
</ul>

HTML-виведення зберігається в змінну $var у вигляді об'єкта Latte\Runtime\Html, щоб уникнути небажаного екранування при виведенні.

Інше

{contentType}

Тегом ви визначаєте, який тип вмісту представляє шаблон. Можливості:

• html (тип за замовчуванням)
• xml
• javascript
• css
• calendar (iCal)
• text

Його використання важливе, оскільки він встановлює контекстно-залежне екранування і лише так може екранувати правильно. Наприклад, {contentType xml} перемикає в режим XML, {contentType text} екранування повністю вимикає.

Якщо параметром є повноцінний MIME-тип, наприклад application/xml, то він ще й надсилає HTTP-заголовок Content-Type до браузера:

{contentType application/xml}
<?xml version="1.0"?>
<rss version="2.0">
	<channel>
		<title>RSS feed</title>
		<item>
			...
		</item>
	</channel>
</rss>

{debugbreak}

Позначає місце, де відбудеться призупинення виконання програми та запуск налагоджувача, щоб програміст міг провести інспекцію середовища виконання та з'ясувати, чи працює програма відповідно до очікувань. Підтримує Xdebug. Можна додати умову, яка визначає, коли програму слід призупинити.

{debugbreak}                {* призупиняє програму *}

{debugbreak $counter == 1}  {* призупиняє програму при виконанні умови *}

{do}

Виконує PHP-код і нічого не виводить. Так само, як і для всіх інших тегів, під PHP-кодом розуміється один вираз, див. обмеження PHP.

{do $num++}

{dump}

Виводить змінну або поточний контекст.

{dump $name} {* Виводить змінну $name *}

{dump}       {* Виводить усі поточні визначені змінні *}

Потребує бібліотеку Tracy.

{php}

Дозволяє виконати будь-який PHP-код. Тег необхідно активувати за допомогою розширення RawPhpExtension.

{spaceless}

Видаляє зайві пробіли з виведення. Працює подібно до фільтра spaceless.

{spaceless}
	<ul>
		<li>Hello</li>
	</ul>
{/spaceless}

Згенерує

<ul> <li>Hello</li> </ul>

Тег також можна записати як n:атрибут.

{syntax}

Теги Latte не обов'язково повинні бути обмежені лише простими фігурними дужками. Ми можемо вибрати й інший роздільник, і навіть під час виконання. Для цього служить {syntax …}, де як параметр можна вказати:

• double: {{...}}
• off: повністю вимикає обробку тегів Latte

З використанням n:атрибутів можна вимкнути Latte, наприклад, лише для одного блоку JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // це вже не тег
</script>

Latte можна дуже зручно використовувати і всередині JavaScript, достатньо уникати конструкцій, як у цьому прикладі, коли літера йде одразу за {, див. Latte всередині JavaScript або CSS.

Якщо Latte вимкнути за допомогою {syntax off} (тобто тегом, а не n:атрибутом), він буде послідовно ігнорувати всі теги до {/syntax}

{trace}

Викидає виняток Latte\RuntimeException, стек викликів якого відповідає духу шаблонів. Тобто замість викликів функцій та методів містить виклики блоків та включення шаблонів. Якщо ви використовуєте інструмент для наочного відображення викинутих винятків, як-от Tracy, вам наочно відобразиться стек викликів, включаючи всі передані аргументи.

Помічники HTML-кодера

n:class

Завдяки n:class дуже легко згенерувати HTML-атрибут class точно за задумом.

Приклад: потрібно, щоб активний елемент мав клас active:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active">...</a>
{/foreach}

А далі, щоб перший елемент мав класи first та main:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main'">...</a>
{/foreach}

І всі елементи повинні мати клас list-item:

{foreach $items as $item}
	<a n:class="$item->isActive() ? active, $iterator->first ? 'first main', list-item">...</a>
{/foreach}

Дивовижно просто, чи не так?

n:attr

Атрибут n:attr вміє з такою ж елегантністю, як n:class, генерувати будь-які HTML-атрибути.

{foreach $data as $item}
	<input type="checkbox" n:attr="value: $item->getValue(), checked: $item->isActive()">
{/foreach}

Залежно від повернутих значень виведе, напр.:

<input type="checkbox">

<input type="checkbox" value="Hello">

<input type="checkbox" value="Hello" checked>

n:tag

Атрибут n:tag вміє динамічно змінювати назву HTML-елемента.

<h1 n:tag="$heading" class="main">{$title}</h1>

Якщо $heading === null, виведеться без змін тег <h1>. Інакше назва елемента зміниться на значення змінної, тож для $heading === 'h3' виведеться:

<h3 class="main">...</h3>

Оскільки Latte є безпечною системою шаблонів, вона перевіряє, чи є нова назва тегу дійсною і не містить жодних небажаних або шкідливих значень.

n:ifcontent

Запобігає виведенню порожнього HTML-елемента, тобто елемента, що не містить нічого, крім пробілів.

<div>
	<div class="error" n:ifcontent>{$error}</div>
</div>

Виведе залежно від значення змінної $error:

{* $error = '' *}
<div>
</div>

{* $error = 'Required' *}
<div>
	<div class="error">Required</div>
</div>

Переклади

Щоб теги для перекладу працювали, потрібно активувати перекладач. Для перекладу ви також можете використовувати фільтр translate.

{_...}

Перекладає значення на інші мови.

<a href="basket">{_'Кошик'}</a>
<span>{_$item}</span>

Перекладачу можна передавати й інші параметри:

<a href="basket">{_'Кошик', domain: order}</a>

{translate}

Перекладає частини шаблону:

<h1>{translate}Замовлення{/translate}</h1>

{translate domain: order}Lorem ipsum ...{/translate}

Тег також можна записати як n:атрибут, для перекладу вмісту елемента:

<h1 n:translate>Замовлення</h1>