Tag-uri Latte

Prezentare generală și descrierea tuturor tag-urilor (sau etichetelor ori macro-urilor) sistemului de șabloane Latte, care vă sunt disponibile în mod standard.

Afișare

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

În Latte se folosește tag-ul {=...} pentru afișarea oricărei expresii în output. Latte ține la confortul dvs., așa că dacă expresia începe cu o variabilă sau un apel de funcție, nu este nevoie să scrieți semnul egal. Ceea ce în practică înseamnă că aproape niciodată nu este nevoie să îl scrieți:

Nume: {$name} {$surname}<br>
Vârstă: {date('Y') - $birth}<br>

Ca expresie puteți scrie orice cunoașteți din PHP. Nu trebuie, pur și simplu, să învățați un nou limbaj. De exemplu:

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

Vă rugăm, nu căutați niciun sens în exemplul anterior, dar dacă găsiți vreunul, scrieți-ne :-)

Escaparea outputului

Care este cea mai importantă sarcină a unui sistem de șabloane? Prevenirea găurilor de securitate. Și exact asta face Latte întotdeauna când afișați ceva. Escapează automat:

<p>{='one < two'}</p>   {* afișează: '<p>one &lt; two</p>' *}

Pentru a fi exacți, Latte folosește escaparea sensibilă la context, ceea ce este un lucru atât de important și unic, încât i-am dedicat un capitol separat.

Și ce se întâmplă dacă afișați conținut codificat în HTML dintr-o sursă de încredere? Atunci puteți dezactiva ușor escaparea:

{$trustedHtmlString|noescape}

Utilizarea incorectă a filtrului noescape poate duce la vulnerabilitatea XSS! Nu-l utilizați niciodată dacă nu sunteți absolut sigur de ceea ce faceți și că șirul afișat provine dintr-o sursă de încredere.

Afișarea în JavaScript

Datorită escapării sensibile la context, este minunat de ușor să afișați variabile în interiorul JavaScriptului, iar Latte se ocupă de escaparea corectă.

Variabila nu trebuie să fie doar un șir, este suportat orice tip de date, care apoi este codificat ca JSON:

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

Generează:

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

Acesta este și motivul pentru care nu se scriu ghilimele în jurul variabilei: Latte le adaugă singur pentru șiruri. Și dacă doriți să inserați o variabilă șir într-un alt șir, pur și simplu le concatenați:

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

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

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

Filtre

Expresia afișată poate fi modificată prin filtre. Astfel, de exemplu, convertim un șir în majuscule și îl scurtăm la maximum 30 de caractere:

{$string|upper|truncate:30}

Puteți aplica filtre și pe părți parțiale ale expresiei în acest mod:

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

Condiții

{if} {elseif} {else}

Condițiile se comportă la fel ca omologii lor din PHP. Puteți folosi în ele aceleași expresii pe care le cunoașteți din PHP, nu trebuie să învățați un nou limbaj.

{if $product->inStock > Stock::Minimum}
	În stoc
{elseif $product->isOnWay()}
	Pe drum
{else}
	Indisponibil
{/if}

Ca orice tag pereche, și perechea {if} ... {/if} poate fi scrisă și sub formă de n:atribut, de exemplu:

<p n:if="$count > 0">În stoc {$count} bucăți</p>

Știați că la n:atribute puteți adăuga prefixul tag-? Atunci condiția se va aplica doar la afișarea tag-urilor HTML, iar conținutul dintre ele se va afișa întotdeauna:

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

{* afișează 'Hello' când $clickable este fals *}
{* afișează '<a href="...">Hello</a>' când $clickable este adevărat *}

Grozav.

n:else

Dacă scrieți condiția {if} ... {/if} sub formă de n:atribut, aveți posibilitatea de a specifica și o ramură alternativă folosind n:else:

<strong n:if="$count > 0">În stoc {$count} bucăți</strong>

<em n:else>indisponibil</em>

Atributul n:else poate fi folosit și în pereche cu n:ifset, n:foreach, n:try, n:ifcontent și n:ifchanged.

{/if $cond}

Poate vă va surprinde că expresia din condiția {if} poate fi specificată și în tag-ul de închidere. Acest lucru este util în situațiile în care, la deschiderea condiției, încă nu cunoaștem valoarea sa. Să numim asta decizie amânată.

De exemplu, începem să afișăm un tabel cu înregistrări din baza de date și abia după finalizarea afișării realizăm că în baza de date nu a existat nicio înregistrare. Atunci punem condiția în tag-ul de închidere {/if} și dacă nu există nicio înregistrare, nimic din toate acestea nu se va afișa:

{if}
	<h1>Listarea rândurilor din baza de date</h1>

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

Util, nu-i așa?

În condiția amânată se poate folosi și {else}, dar nu {elseif}.

{ifset} {elseifset}

Vezi și {ifset block}

Folosind condiția {ifset $var}, verificăm dacă variabila (sau mai multe variabile) există și are o valoare non-null. De fapt, este același lucru cu if (isset($var)) în PHP. Ca orice tag pereche, poate fi scris și sub formă de n:atribut, așa că să arătăm asta ca exemplu:

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

{ifchanged}

{ifchanged} verifică dacă valoarea unei variabile s-a schimbat de la ultima iterație într-o buclă (foreach, for sau while).

Dacă specificăm una sau mai multe variabile în tag, va verifica dacă vreuna dintre ele s-a schimbat și va afișa conținutul în consecință. De exemplu, următorul exemplu afișează prima literă a numelui ca titlu de fiecare dată când se schimbă la afișarea numelor:

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

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

Dacă însă nu specificăm niciun argument, se va verifica conținutul randat față de starea sa anterioară. Acest lucru înseamnă că, în exemplul anterior, putem omite liniștit argumentul din tag. Și, desigur, putem folosi și n:atribut:

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

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

În interiorul {ifchanged} se poate specifica și clauza {else}.

{switch} {case} {default}

Compară valoarea cu mai multe opțiuni. Este un echivalent al instrucțiunii condiționale switch, pe care o cunoașteți din PHP. Cu toate acestea, Latte o îmbunătățește:

• folosește comparare strictă (===)
• nu necesită break

Este deci echivalentul exact al structurii match introdusă în PHP 8.0.

{switch $transport}
	{case train}
		Cu trenul
	{case plane}
		Cu avionul
	{default}
		Altfel
{/switch}

Clauza {case} poate conține mai multe valori separate prin virgule:

{switch $status}
{case $status::New}<b>element nou</b>
{case $status::Sold, $status::Unknown}<i>indisponibil</i>
{/switch}

Bucle

În Latte găsiți toate buclele pe care le cunoașteți din PHP: foreach, for și while.

{foreach}

Bucla se scrie exact la fel ca în PHP:

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

În plus, are câteva caracteristici utile despre care vom vorbi acum.

Latte, de exemplu, verifică dacă variabilele create nu suprascriu accidental variabile globale cu același nume. Salvează situații în care contați pe faptul că $lang conține limba curentă a paginii și nu realizați că foreach $langs as $lang v-a suprascris acea variabilă.

Bucla foreach poate fi scrisă și foarte elegant și concis folosind n:atribut:

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

Știați că la n:atribute puteți adăuga prefixul inner-? Atunci doar interiorul elementului se va repeta în buclă:

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

Deci se va afișa ceva de genul:

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

{else}

În interiorul buclei foreach se poate specifica clauza {else}, al cărei conținut se afișează dacă bucla este goală:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Ne pare rău, nu există utilizatori în această listă</em></li>
	{/foreach}
</ul>

$iterator

În interiorul buclei foreach, Latte creează variabila $iterator, cu ajutorul căreia putem afla informații utile despre bucla în curs:

• $iterator->first – este prima trecere prin buclă?
• $iterator->last – este ultima trecere?
• $iterator->counter – a câta trecere este, numărând de la unu?
• $iterator->counter0 – a câta trecere este, numărând de la zero?
• $iterator->odd – este o trecere impară?
• $iterator->even – este o trecere pară?
• $iterator->parent – iteratorul care îl înconjoară pe cel curent
• $iterator->nextValue – elementul următor din buclă
• $iterator->nextKey – cheia elementului următor din buclă

{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 este inteligent și $iterator->last funcționează nu doar pentru array-uri, ci și atunci când bucla parcurge un iterator general, unde numărul de elemente nu este cunoscut în avans.

{first} {last} {sep}

Aceste tag-uri pot fi folosite în interiorul buclei {foreach}. Conținutul {first} se randează dacă este prima trecere. Conținutul {last} se randează… ghiciți? Da, dacă este ultima trecere. Sunt de fapt prescurtări pentru {if $iterator->first} și {if $iterator->last}.

Tag-urile pot fi folosite și elegant ca n:atribut:

{foreach $rows as $row}
	{first}<h1>Lista de nume</h1>{/first}

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

	<hr n:last>
{/foreach}

Conținutul tag-ului {sep} se randează dacă trecerea nu este ultima, fiind util pentru randarea separatoarelor, de exemplu, virgule între elementele afișate:

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

Este destul de practic, nu-i așa?

{iterateWhile}

Simplifică gruparea datelor liniare în timpul iterării într-o buclă foreach, efectuând iterația într-o buclă imbricată atâta timp cât condiția este îndeplinită. Citiți un tutorial detaliat.

Poate înlocui elegant și {first} și {last} din exemplul de mai sus:

{foreach $rows as $row}
	<table>

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

	</table>
{/foreach}

Vezi și filtrele batch și group.

{for}

Bucla o scriem exact la fel ca în PHP:

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

Tag-ul poate fi folosit și ca n:atribut:

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

{while}

Bucla o scriem din nou exact la fel ca în PHP:

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

Sau ca n:atribut:

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

Este posibilă și varianta cu condiția în tag-ul de închidere, care corespunde în PHP buclei do-while:

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

{continueIf} {skipIf} {breakIf}

Pentru controlul oricărei bucle se pot folosi tag-urile {continueIf ?} și {breakIf ?}, care trec la elementul următor, respectiv încheie bucla la îndeplinirea condiției:

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

Tag-ul {skipIf} este foarte similar cu {continueIf}, dar nu incrementează contorul $iterator->counter, astfel încât dacă îl afișăm și în același timp sărim peste unele elemente, nu vor exista goluri în numerotare. De asemenea, clauza {else} se randează dacă sărim peste toate elementele.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Ne pare rău, nu există adulți în această listă</em></li>
	{/foreach}
</ul>

{exitIf}

Încheie randarea șablonului sau a blocului la îndeplinirea condiției (așa-numitul “early exit”).

{exitIf !$messages}

<h1>Mesaje</h1>
<div n:foreach="$messages as $message">
   {$message}
</div>

Includerea șablonului

{include 'file.latte'}

Vezi și {include block}

Tag-ul {include} încarcă și randează șablonul specificat. Dacă am vorbi în limbajul limbii noastre preferate PHP, este ceva de genul:

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

Șabloanele incluse nu au acces la variabilele contextului activ, au acces doar la variabilele globale.

Puteți transmite variabile în șablonul inclus în acest mod:

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

Numele șablonului poate fi orice expresie PHP:

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

Conținutul inclus poate fi modificat folosind filtre. Următorul exemplu elimină tot HTML-ul și modifică dimensiunea literelor:

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

În mod implicit, moștenirea șabloanelor nu figurează în niciun fel în acest caz. Chiar dacă în șablonul inclus putem folosi blocuri, nu se va produce înlocuirea blocurilor corespunzătoare din șablonul în care se include. Gândiți-vă la șabloanele incluse ca la părți separate și izolate ale paginilor sau modulelor. Acest comportament poate fi schimbat folosind modificatorul with blocks:

{include 'template.latte' with blocks}

Relația dintre numele fișierului specificat în tag și fișierul de pe disc este responsabilitatea loaderului.

{sandbox}

La includerea unui șablon creat de utilizatorul final, ar trebui să luați în considerare modul sandbox (mai multe informații în documentația sandbox):

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

{block}

Vezi și {block name}

Blocurile fără nume servesc ca o modalitate de a aplica filtre pe o parte a șablonului. De exemplu, astfel se poate aplica filtrul strip, care elimină spațiile inutile:

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

Gestionarea excepțiilor

{try}

Datorită acestui tag, este extrem de ușor să creați șabloane robuste.

Dacă în timpul randării blocului {try} apare o excepție, întregul bloc este anulat și randarea va continua după el:

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

Conținutul din clauza opțională {else} se randează doar când apare o excepție:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Ne pare rău, nu s-au putut încărca tweet-urile.</p>
{/try}

Tag-ul poate fi folosit și ca n:atribut:

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

Este posibil, de asemenea, să definiți propriul handler de excepții, de exemplu, pentru logare.

{rollback}

Blocul {try} poate fi oprit și sărit și manual folosind {rollback}. Datorită acestui fapt, nu trebuie să verificați în prealabil toate datele de intrare și abia în timpul randării puteți decide că nu doriți să randați deloc obiectul:

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

Variabile

{var} {default}

Variabile noi creăm în șablon cu tag-ul {var}:

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

{* Declarație multiplă *}
{var $name = 'John Smith', $age = 27}

Tag-ul {default} funcționează similar, dar creează variabile doar dacă nu există. Dacă variabila există deja și conține valoarea null, nu va fi suprascrisă:

{default $lang = 'ro'}

Puteți specifica și tipurile variabilelor. Deocamdată sunt informative și Latte nu le verifică.

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

{parameters}

Așa cum o funcție își declară parametrii, și un șablon poate declara la început variabilele sale:

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

Variabilele $a și $b fără valoare implicită specificată au automat valoarea implicită null. Tipurile declarate sunt deocamdată informative și Latte nu le verifică.

Alte variabile decât cele declarate nu sunt transferate în șablon. Prin aceasta se diferențiază de tag-ul {default}.

{capture}

Capturează outputul într-o variabilă:

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

<p>Capturat: {$var}</p>

Tag-ul poate fi, la fel ca orice tag pereche, scris și ca n:atribut:

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

Outputul HTML se salvează în variabila $var sub formă de obiect Latte\Runtime\Html, pentru a preveni escaparea nedorită la afișare.

Altele

{contentType}

Cu acest tag specificați ce tip de conținut reprezintă șablonul. Opțiunile sunt:

• html (tip implicit)
• xml
• javascript
• css
• calendar (iCal)
• text

Utilizarea sa este importantă, deoarece setează escaparea sensibilă la context și doar așa poate escapa corect. De exemplu, {contentType xml} comută în modul XML, {contentType text} dezactivează complet escaparea.

Dacă parametrul este un tip MIME complet, cum ar fi application/xml, atunci trimite și antetul HTTP Content-Type către browser:

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

{debugbreak}

Indică locul unde execuția programului va fi suspendată și debuggerul va fi pornit, pentru ca programatorul să poată inspecta mediul de rulare și să verifice dacă programul funcționează conform așteptărilor. Suportă Xdebug. Se poate adăuga o condiție care determină când programul trebuie suspendat.

{debugbreak}                {* suspendă programul *}

{debugbreak $counter == 1}  {* suspendă programul la îndeplinirea condiției *}

{do}

Execută cod PHP și nu afișează nimic. La fel ca la toate celelalte tag-uri, prin cod PHP se înțelege o singură expresie, vezi limitările PHP.

{do $num++}

{dump}

Afișează variabila sau contextul curent.

{dump $name} {* Afișează variabila $name *}

{dump}       {* Afișează toate variabilele definite curent *}

Necesită biblioteca Tracy.

{php}

Permite executarea oricărui cod PHP. Tag-ul trebuie activat folosind extensia RawPhpExtension.

{spaceless}

Elimină spațiul alb inutil din output. Funcționează similar cu filtrul spaceless.

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

Generează

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

Tag-ul poate fi scris și ca n:atribut.

{syntax}

Tag-urile Latte nu trebuie să fie delimitate doar de acolade simple. Putem alege și alt delimitator, chiar și în timpul rulării. Pentru aceasta servește {syntax …}, unde ca parametru se poate specifica:

• double: {{...}}
• off: dezactivează complet procesarea tag-urilor Latte

Folosind n:atribute, se poate dezactiva Latte, de exemplu, doar pentru un bloc JavaScript:

<script n:syntax="off">
	var obj = {var: 123}; // acesta nu mai este un tag
</script>

Latte poate fi folosit foarte convenabil și în interiorul JavaScriptului, trebuie doar evitate construcțiile ca în acest exemplu, unde o literă urmează imediat după {, vezi Latte în interiorul JavaScriptului sau CSS.

Dacă dezactivați Latte folosind {syntax off} (adică prin tag, nu prin n:atribut), va ignora consecvent toate tag-urile până la {/syntax}

{trace}

Aruncă o excepție Latte\RuntimeException, al cărei stack trace este în spiritul șabloanelor. Adică, în loc de apeluri de funcții și metode, conține apeluri de blocuri și includeri de șabloane. Dacă utilizați un instrument pentru afișarea clară a excepțiilor aruncate, cum ar fi Tracy, vi se va afișa clar call stack-ul, inclusiv toți argumentii transmiși.

Ajutoare pentru coderul HTML

n:class

Datorită n:class, generați foarte ușor atributul HTML class exact conform așteptărilor.

Exemplu: am nevoie ca elementul activ să aibă clasa active:

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

Și în plus, ca primul element să aibă clasele first și main:

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

Și toate elementele trebuie să aibă clasa list-item:

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

Uimitor de simplu, nu-i așa?

n:attr

Atributul n:attr poate genera orice atribute HTML cu aceeași eleganță ca n:class.

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

În funcție de valorile returnate, afișează de ex.:

<input type="checkbox">

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

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

n:tag

Atributul n:tag poate schimba dinamic numele elementului HTML.

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

Dacă $heading === null, se va afișa neschimbat tag-ul <h1>. Altfel, numele elementului se schimbă în valoarea variabilei, deci pentru $heading === 'h3' se va afișa:

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

Deoarece Latte este un sistem de șabloane sigur, verifică dacă noul nume al tag-ului este valid și nu conține valori nedorite sau dăunătoare.

n:ifcontent

Previne afișarea unui element HTML gol, adică un element care nu conține nimic altceva decât spații.

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

Afișează în funcție de valoarea variabilei $error:

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

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

Traduceri

Pentru ca tag-urile de traducere să funcționeze, trebuie activat traducătorul. Pentru traducere puteți folosi și filtrul translate.

{_...}

Traduce valorile în alte limbi.

<a href="basket">{_'Coș'}</a>
<span>{_$item}</span>

Traducătorului i se pot transmite și alți parametri:

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

{translate}

Traduce părți ale șablonului:

<h1>{translate}Comandă{/translate}</h1>

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

Tag-ul poate fi scris și ca n:atribut, pentru traducerea interiorului elementului:

<h1 n:translate>Comandă</h1>