Теги Latte

Зведення та опис усіх вбудованих тегів Latte.

Друк

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

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

Name: {$name} {$surname}<br>
Age: {date('Y') - $birth}<br>

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

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

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

Ескейпінг-виведення

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

<p>{='one < two'}</p>   {* prints: '<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} !');         // ERROR!
</script>

Фільтри

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

{$string|upper|truncate:30}

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

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

Умови

{if} {elseif} {else}

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

{if $product->inStock > Stock::Minimum}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

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

<p n:if="$count > 0">In stock {$count} items</p>

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

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

{* prints 'Hello' when $clickable is falsey *}
{* prints '<a href="...">Hello</a>' when $clickable is truthy *}

Чудово.

n:else

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

<strong n:if="$count > 0">In stock {$count} items</strong>

<em n:else>not available</em>

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

{/if $cond}

Вас може здивувати, що вираз в умові {if} також може бути вказано в тезі end. Це корисно в ситуаціях, коли ми ще не знаємо значення умови на момент відкриття тега. Назвемо це відкладеним рішенням.

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

{if}
	<h1>Printing rows from the database</h1>

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

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

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

{ifset} {elseifset}

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

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

<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:attribute:

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

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

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

{switch} {case} {default}

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

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

Таким чином, це точний еквівалент структури match, з якою поставляється PHP 8.0.

{switch $transport}
	{case train}
		By train
	{case plane}
		By plane
	{default}
		Differently
{/switch}

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

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</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:attribute:

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

Чи знаєте ви, що до n:attributes можна додавати префікс 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>Sorry, no users in this list</em></li>
	{/foreach}
</ul>

$iterator

Усередині циклу foreach ініціалізується змінна $iterator. У ній зберігається важлива інформація про поточний цикл.

• $iterator->first – це перша ітерація?
• $iterator->last – це остання ітерація?
• $iterator->counter – лічильник ітерацій, починається з 1
• $iterator->counter0 – лічильник ітерацій, починається з 0
• $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}

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

{first} {last} {sep}

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

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

{foreach $rows as $row}
	{first}<h1>List of names</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}

{for}

Ми пишемо цикл точно так само, як і в PHP:

{for $i = 0; $i < 10; $i++}
	<span>Item #{$i}</span>
{/for}

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

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

{while}

Знову ж таки, ми пишемо цикл точно так само, як і в PHP:

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

Або як n:attribute:

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

Варіант з умовою наприкінці тега відповідає циклу do-while у PHP:

{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>Sorry, no adult users in this list</em></li>
	{/foreach}
</ul>

{exitIf}

Завершує відмальовування шаблону або блоку при виконанні умови.

{exitIf !$messages}

<h1>Messages</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 'untrusted.latte', level: 3, data: $menu}

{block}

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

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

{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>Sorry, the tweets could not be loaded.</p>
{/try}

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

<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} працює аналогічно, за винятком того, що він створює змінні, тільки якщо вони не існують:

{default $lang = 'cs'}

Ви також можете вказати типи змінних. Наразі вони є інформативними і 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}, ви можете захопити виведення у змінну:

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

<p>Captured: {$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

Його використання важливе, оскільки він встановлює контекстно-залежне екранування, і тільки після цього Latte може правильно екранувати. Наприклад, {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}
	<ul>
		<li>Hello</li>
	</ul>
{/spaceless}

Вихідні дані:

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

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

{syntax}

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

• double: {{...}}
• off: повністю відключає теги Latte

Використовуючи нотацію n:attribute, ми можемо вимкнути Latte тільки для блоку JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // this isn't a tag any more
</script>

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

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

{trace}

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

Помічники тегів HTML

n:клас

Завдяки 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 може генерувати довільні HTML-атрибути з тією ж елегантністю, що й n:class.

{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">{_'Basket'}</a>
<span>{_$item}</span>

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

<a href="basket">{_'Basket', domain: order}</a>

{translate}

Překládá části šablony:

<h1>{translate}Order{/translate}</h1>

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

Тег також може бути записаний як n:attribute, щоб перекласти внутрішню частину елемента:

<h1 n:translate>Order</h1>