Latte Etichete

Rezumat și descriere a tuturor etichetelor Latte încorporate.

Imprimare

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

Latte utilizează eticheta {=...} pentru a imprima orice expresie la ieșire. Dacă expresia începe cu o variabilă sau cu un apel de funcție, nu este necesar să se scrie un semn egal. Ceea ce, în practică, înseamnă că aproape niciodată nu este necesar să fie scris:

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

Puteți scrie ca expresie orice știți din PHP. Pur și simplu nu trebuie să învățați un nou limbaj. De exemplu:

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

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

Ieșire prin evadare

Care este cea mai importantă sarcină a unui sistem de șabloane? Să evite găurile de securitate. Și exact asta face Latte de fiecare dată când imprimați ceva la ieșire. El scapă automat totul:

<p>{='one < two'}</p>   {* prints: '<p>one &lt; two</p>' *}

Mai exact, Latte folosește escape-ul sensibil la context, care este o caracteristică atât de importantă și unică încât i-am dedicat un capitol separat.

Și dacă imprimați conținut codificat HTML dintr-o sursă de încredere? Atunci puteți să dezactivați cu ușurință scăparea:

{$trustedHtmlString|noescape}

Utilizarea abuzivă a filtrului noescape poate duce la o vulnerabilitate XSS! Nu îl utilizați niciodată decât dacă sunteți absolut sigur de ceea ce faceți și dacă șirul pe care îl imprimați provine dintr-o sursă de încredere.

Imprimarea în JavaScript

Datorită scăpării sensibile la context, este foarte ușor să imprimați variabile în JavaScript, iar Latte le va scăpa în mod corespunzător.

Variabila nu trebuie să fie un șir de caractere, este acceptat orice tip de date, care este apoi 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 puneți variabilele între ghilimele: Latte le adaugă în jurul șirurilor de caractere. Iar dacă doriți să puneți o variabilă de șir de caractere în alt șir de caractere, pur și simplu le concatenați:

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

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

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

Filtre

Expresia tipărită poate fi modificată prin filtre. De exemplu, acest exemplu convertește șirul în majuscule și îl scurtează la maximum 30 de caractere:

{$string|upper|truncate:30}

De asemenea, puteți aplica filtre la părți ale unei expresii, după cum urmează:

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

Condiții

{if} {elseif} {else}

Condițiile se comportă în același mod ca și omologii lor din PHP. Puteți utiliza 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}
	In stock
{elseif $product->isOnWay()}
	On the way
{else}
	Not available
{/if}

La fel ca orice tag pair, o pereche de {if} ... {/ if} poate fi scrisă ca n:attribute, de exemplu:

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

Știați că puteți adăuga prefixul tag- la n:attribute? În acest caz, condiția va afecta doar etichetele HTML, iar conținutul dintre ele va fi întotdeauna tipărit:

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

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

Frumos.

n:else

Dacă scrieți condiția {if} ... {/if} sub forma unui n:atribut, aveți opțiunea de a specifica o ramură alternativă folosind n:else:

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

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

Atributul n:else poate fi, de asemenea, utilizat împreună cu n:ifset, n:foreach, n:try, n:ifcontent, și n:ifchanged.

{/if $cond}

S-ar putea să fiți surprins de faptul că expresia din condiția {if} poate fi, de asemenea, specificată în eticheta end. Acest lucru este util în situațiile în care nu cunoaștem încă valoarea condiției la deschiderea tag-ului. Să o numim o decizie amânată.

De exemplu, începem să listăm un tabel cu înregistrări din baza de date și abia după ce finalizăm raportul ne dăm seama că nu exista nicio înregistrare în baza de date. Deci, punem condiția în tag-ul de sfârșit {/if} și, dacă nu există nicio înregistrare, nu se va imprima nimic:

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

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

Practic, nu-i așa?

De asemenea, puteți utiliza {else} în condiția amânată, dar nu și {elseif}.

{ifset} {elseifset}

A se vedea și {ifset block}

Utilizați condiția {ifset $var} pentru a determina dacă o variabilă (sau mai multe variabile) există și dacă are o valoare diferită de cea nulă. De fapt, este același lucru cu if (isset($var)) în PHP. La fel ca orice tag pair, aceasta poate fi scrisă sub forma n:attribute, așa că haideți să o arătăm în exemplu:

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

{ifchanged}

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

Dacă specificăm una sau mai multe variabile în etichetă, aceasta va verifica dacă vreuna dintre ele s-a schimbat și va imprima conținutul în consecință. De exemplu, exemplul următor tipărește prima literă a unui nume ca titlu de fiecare dată când se schimbă atunci când se listează nume:

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

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

Cu toate acestea, dacă nu se furnizează niciun argument, conținutul redat în sine va fi verificat în raport cu starea sa anterioară. Acest lucru înseamnă că, în exemplul anterior, putem omite în siguranță argumentul din tag. Și, bineînțeles, putem folosi și n:attribute:

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

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

De asemenea, puteți include o clauză {else} în interiorul {ifchanged}.

{switch} {case} {default}

Compară valoarea cu mai multe opțiuni. Aceasta este similară structurii switch pe care o cunoașteți din PHP. Cu toate acestea, Latte o îmbunătățește:

• utilizează o comparație strictă (===)
• nu are nevoie de un break

Așadar, este echivalentul exact al structurii match cu care vine PHP 8.0.

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

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

{switch $status}
{case $status::New}<b>new item</b>
{case $status::Sold, $status::Unknown}<i>not available</i>
{/switch}

Bucle

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

{foreach}

Ciclul se scrie exact la fel ca în PHP:

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

În plus, el are câteva ajustări utile despre care vom vorbi acum.

De exemplu, Latte verifică dacă variabilele create nu suprascriu accidental variabilele globale cu același nume. Acest lucru vă va salva atunci când presupuneți că $lang este limba curentă a paginii și nu vă dați seama că foreach $langs as $lang a suprascris acea variabilă.

Bucla foreach poate fi, de asemenea, scrisă foarte elegant și economic cu n:attribute:

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

Știați că puteți adăuga prefixul inner- la n:attribute? Astfel, numai partea interioară a elementului va fi repetată în buclă:

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

Deci, se tipărește ceva de genul:

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

{else}

Bucla foreach poate primi o clauză opțională {else} al cărei text este afișat dacă matricea dată este goală:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Sorry, no users in this list</em></li>
	{/foreach}
</ul>

$iterator

În cadrul buclei foreach se inițializează variabila $iterator. Aceasta conține informații importante despre bucla curentă.

• $iterator->first – este aceasta prima iterație?
• $iterator->last – este aceasta ultima iterație?
• $iterator->counter – contorul de iterații, începe de la 1
• $iterator->counter0 – contorul de iterații, începe de la 0
• $iterator->odd – este această iterație impară?
• $iterator->even – este această iterație pară?
• $iterator->parent – iteratorul care îl înconjoară pe cel curent
• $iterator->nextValue – următorul element din buclă
• $iterator->nextKey – cheia următorului element 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}

Lapte este inteligent și $iterator->last funcționează nu numai pentru array-uri, ci și atunci când bucla se execută peste un iterator general în care numărul de elemente nu este cunoscut dinainte.

{first} {last} {sep}

Aceste etichete pot fi utilizate în interiorul buclei {foreach}. Conținutul din {first} este redat pentru prima trecere. Conținutul din {last} este redat … puteți ghici? Da, pentru ultima trecere. Acestea sunt, de fapt, prescurtări pentru {if $iterator->first} și {if $iterator->last}.

Etichetele pot fi scrise și sub forma n:attributes:

{foreach $rows as $row}
	{first}<h1>List of names</h1>{/first}

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

	<hr n:last>
{/foreach}

Conținutul {sep} este redat dacă iterația nu este ultima, astfel încât este potrivit pentru imprimarea delimitatorilor, cum ar fi virgulele între elementele enumerate:

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

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

{iterateWhile}

Simplifică gruparea datelor liniare în timpul iterației într-o buclă foreach prin iterația într-o buclă imbricata până când este îndeplinită o condiție. Citiți instrucțiunile detaliate.

De asemenea, poate înlocui în mod elegant {first} și {last} în 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}

A se vedea, de asemenea, filtrele de lot și de grup.

{for}

Scriem ciclul exact în același mod ca în PHP:

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

Eticheta poate fi scrisă și sub forma n:attribute:

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

{while}

Din nou, scriem ciclul exact în același mod ca în PHP:

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

Sau ca n:attribute:

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

O variantă cu o condiție în tag-ul final corespunde buclei do-while din PHP:

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

{continueIf} {skipIf} {breakIf}

Există etichete speciale pe care le puteți utiliza pentru a controla orice buclă – {continueIf ?} și {breakIf ?} care trec la următoarea iterație și, respectiv, încheie bucla, dacă sunt îndeplinite condițiile:

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

Eticheta {skipIf} este foarte asemănătoare cu {continueIf}, dar nu incrementează contorul. Astfel, nu există găuri în numerotare atunci când tipăriți $iterator->counter și săriți peste unele elemente. De asemenea, clauza {else} va fi redată atunci când săriți peste toate elementele.

<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}

Încheie redarea unui șablon sau a unui bloc atunci când este îndeplinită o condiție (de exemplu, “ieșire anticipată”).

{exitIf !$messages}

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

Includerea șabloanelor

{include 'file.latte'}

A se vedea și {include block}

Eticheta {include} încarcă și redă șablonul specificat. În limbajul nostru preferat, PHP, este ca și cum ar fi:

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

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

Puteți transmite variabile către șablonul inserat în felul următor:

{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 inserat poate fi modificat cu ajutorul filtrelor. Următorul exemplu elimină toate elementele HTML și ajustează cazul:

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

Moștenirea șablonului nu este implicată în mod implicit. Deși puteți adăuga etichete de bloc la șabloanele care sunt incluse, acestea nu vor înlocui blocurile corespunzătoare din șablonul în care sunt incluse. Gândiți-vă la incluziuni ca la părți independente și ecranate ale paginilor sau modulelor. Acest comportament poate fi schimbat cu ajutorul modificatorului with blocks:

{include 'template.latte' with blocks}

Relația dintre numele de fișier specificat în etichetă și fișierul de pe disc este o chestiune de încărcător.

{sandbox}

Atunci când includeți un șablon creat de un utilizator final, ar trebui să aveți în vedere sandboxing-ul acestuia (mai multe informații în documentația sandbox):

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

{block}

A se vedea și {block name}

Blocurile fără nume servesc la capacitatea de a aplica filtre unei părți din șablon. De exemplu, puteți aplica un filtru de benzi pentru a elimina spațiile inutile:

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

Gestionarea excepțiilor

{try}

Aceste etichete facilitează foarte mult crearea de șabloane robuste.

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

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

Conținutul clauzei opționale {else} este redat numai atunci când apare o excepție:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Sorry, the tweets could not be loaded.</p>
{/try}

Eticheta poate fi scrisă și sub forma n:attribute:

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

De asemenea, este posibil să se definească propriul gestionar de excepții, de exemplu, pentru logare:

{rollback}

Blocul {try} poate fi, de asemenea, oprit și sărit manual folosind {rollback}. Astfel, nu trebuie să verificați în prealabil toate datele de intrare și numai în timpul redării puteți decide dacă este utilă redarea obiectului.

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

Variabile

{var} {default}

Vom crea noi variabile în șablon cu ajutorul etichetei {var}:

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

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

Eticheta {default} funcționează în mod similar, cu excepția faptului că aceasta creează variabile numai dacă acestea nu există. Dacă o variabilă există deja și conține null, aceasta nu va fi suprascrisă:

{default $lang = 'cs'}

De asemenea, puteți specifica tipurile de variabile. Deocamdată, acestea sunt informative și Latte nu le verifică.

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

{parameters}

La fel cum o funcție își declară parametrii, un șablon își poate declara variabilele la începutul său:

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

Variabilele $a și $b care nu au o valoare implicită au automat valoarea implicită null. Tipurile declarate sunt în continuare informative, iar Latte nu le verifică.

În afară de variabilele declarate, acestea nu sunt transmise în șablon. Aceasta este o diferență față de eticheta {default}.

{capture}

Prin utilizarea etichetei {capture} puteți captura ieșirea într-o variabilă:

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

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

Eticheta poate fi scrisă și sub forma n:attribute, ca orice altă etichetă de tip pereche:

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

Rezultatul HTML este stocat în variabila $var ca obiect Latte\Runtime\Html pentru a evita scăpările nedorite la imprimare.

Altele

{contentType}

Utilizați eticheta pentru a specifica ce tip de conținut reprezintă șablonul. Opțiunile sunt următoarele:

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

Utilizarea sa este importantă, deoarece setează escape-ul sensibil la context și numai atunci Latte poate evada corect. De exemplu, {contentType xml} comută în modul XML, {contentType text} dezactive complet scăparea.

În cazul în care parametrul este un tip MIME complet, cum ar fi application/xml, se trimite, de asemenea, un antet HTTP Content-Type către browser:

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

{debugbreak}

Specifică locul în care se va întrerupe execuția codului. Este utilizat în scopuri de depanare pentru ca programatorul să inspecteze mediul de execuție și să se asigure că codul se execută conform așteptărilor. Este compatibil cu Xdebug. În plus, puteți specifica o condiție în care codul trebuie să se întrerupă.

{debugbreak}                {* întrerupe programul *}

{debugbreak $counter == 1}  {* întrerupe programul dacă este îndeplinită condiția *}

{do}

Execută codul PHP și nu tipărește nimic. Ca și în cazul celorlalte etichete, codul PHP este o singură expresie, a se vedea Limitări PHP.

{do $num++}

{dump}

Aruncă o variabilă sau contextul curent.

{dump $name} {* aruncă variabila $name *}

{dump}       {* descarcă toate variabilele definite *}

Necesită pachetul Tracy.

{php}

Vă permite să executați orice cod PHP. Eticheta trebuie să fie activată cu ajutorul extensiei RawPhpExtension.

{spaceless}

Elimină spațiile albe inutile. Este similar cu filtrul fără spațiu.

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

Ieșiri:

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

Eticheta poate fi scrisă și sub forma n:attribute:

{syntax}

Etichetele Latte nu trebuie să fie incluse doar în acolade simple. Puteți alege un alt separator, chiar și în timpul execuției. Acest lucru se face prin {syntax…}, unde parametrul poate fi:

• double: {{...}}
• off: dezactivează complet etichetele Latte

Prin utilizarea notației n:attribute putem dezactiva Latte doar pentru un bloc JavaScript:

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

Latte poate fi folosit foarte confortabil în JavaScript, doar evitați construcțiile ca în acest exemplu, unde litera urmează imediat după {, vezi Latte în JavaScript sau CSS.

Dacă dezactivați Latte cu {syntax off} (adică tag-ul, nu atributul n:), acesta va ignora cu strictețe toate tag-urile până la {/syntax}.

{trace}

Aruncă o excepție Latte\RuntimeException, a cărei urmă din stivă este în spiritul șabloanelor. Astfel, în loc să apeleze funcții și metode, implică apelarea de blocuri și inserarea de șabloane. Dacă utilizați un instrument pentru afișarea clară a excepțiilor aruncate, cum ar fi Tracy, veți vedea clar stiva de apelare, inclusiv toate argumentele transmise.

Ajutoare pentru etichete HTML

n:class

Datorită n:class, este foarte ușor să generați atributul HTML class exact așa cum aveți nevoie.

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

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

Și mai am nevoie 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}

Iar 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 atribute HTML arbitrare cu aceeași eleganță ca și n:class.

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

În funcție de valorile returnate, acesta 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 în mod dinamic numele unui element HTML.

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

Dacă $heading === null, atributul <h1> este tipărit fără modificări. În caz contrar, numele elementului este schimbat cu valoarea variabilei, astfel încât pentru $heading === 'h3' se scrie:

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

Deoarece Latte este un sistem de modelare securizat, acesta verifică dacă noul nume de etichetă este valid și nu conține valori nedorite sau rău intenționate.

n:ifcontent

Împiedică tipărirea unui element HTML gol, adică a unui element care nu conține decât spații albe.

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

În funcție de valorile variabilei $error, se va imprima:

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

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

Traducere

Pentru a face ca etichetele de traducere să funcționeze, trebuie să configurați translator. De asemenea, puteți utiliza translate filtru pentru traducere.

{_...}

Traduce valorile în alte limbi.

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

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

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

{translate}

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

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

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

Eticheta poate fi scrisă și sub forma n:attribute, pentru a traduce interiorul elementului:

<h1 n:translate>Order</h1>