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 е невярно *}
{* извежда '<a href="...">Hello</a>', когато $clickable е вярно *}

Страхотно.

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}

Връзката между името на файла, посочено в тага, и файла на диска е въпрос на loader.

{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 = 'bg'}

Можете да посочвате и типове променливи. Засега те са информативни и 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, чийто stack trace е в духа на шаблоните. Тоест вместо извиквания на функции и методи съдържа извиквания на блокове и вмъквания на шаблони. Ако използвате инструмент за прегледно показване на хвърлените изключения, като например Tracy, прегледно ще ви се покаже call stack, включително всички предавани аргументи.

Помощници за 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>