Latte címkék

Az összes beépített Latte-címke összefoglalása és leírása.

Nyomtatás

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

A Latte a {=...} címkét használja bármely kifejezés kimeneti kiadására. Ha a kifejezés változóval vagy függvényhívással kezdődik, nem szükséges egyenlőségjelet írni. Ami a gyakorlatban azt jelenti, hogy szinte soha nem kell kiírni:

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

Bármit leírhatsz kifejezésként, amit a PHP-ból ismersz. Csak nem kell megtanulnod egy új nyelvet. Például:

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

Kérjük, ne keressenek értelmet az előző példában, de ha találnak benne, írják meg nekünk :-)

Kimenet menekülése

Mi a sablonrendszer legfontosabb feladata? A biztonsági rések elkerülése. És pontosan ezt teszi a Latte, amikor valamit a kimenetre nyomtat. Automatikusan mindent elrejt:

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

Pontosabban, a Latte kontextusfüggő eszkópálást használ, ami olyan fontos és egyedülálló funkció, hogy külön fejezetet szenteltünk neki.

És ha megbízható forrásból származó HTML-kódolt tartalmat nyomtat? Akkor egyszerűen kikapcsolhatja az escapinget:

{$trustedHtmlString|noescape}

A noescape szűrő visszaélésszerű használata XSS sebezhetőséghez vezethet! Soha ne használd, hacsak nem vagy teljesen biztos abban, hogy mit csinálsz, és hogy a nyomtatott karakterlánc megbízható forrásból származik.

Nyomtatás JavaScriptben

A kontextusérzékeny escapingnek köszönhetően csodálatosan egyszerű a változók JavaScripten belüli nyomtatása, és a Latte megfelelően kikerüli őket.

A változónak nem kell sztringnek lennie, bármilyen adattípus támogatott, amit aztán JSON-ként kódol:

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

Generál:

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

Ez az oka annak is, hogy nem szabad a változót idézőjelbe tenni: Latte a karakterláncok köré teszi őket. Ha pedig egy stringváltozót egy másik stringbe akarsz tenni, egyszerűen kapcsold össze őket:

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

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

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

Szűrők

A nyomtatott kifejezés szűrőkkel módosítható. Ez a példa például a karakterláncot nagybetűvé alakítja, és legfeljebb 30 karakterre rövidíti:

{$string|upper|truncate:30}

A kifejezés részeire is alkalmazhat szűrőket az alábbiak szerint:

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

Feltételek

{if} {elseif} {else}

A feltételek ugyanúgy viselkednek, mint a PHP megfelelőik. Használhatja ugyanazokat a kifejezéseket, amelyeket a PHP-ból ismer, nem kell új nyelvet tanulnia.

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

Mint minden páros tag, a {if} ... {/ if} párja is leírható például n:attribútumként:

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

Tudtad, hogy az n:attribútumokhoz hozzáadhatod a tag- előtagot? Ekkor a feltétel csak a HTML-címkéket érinti, és a köztük lévő tartalom mindig ki lesz nyomtatva:

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

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

Szép.

n:else

Ha a {if} ... {/if} feltételt n:attribútum formájában írja, akkor lehetősége van a n:else segítségével egy alternatív ágat is megadni:

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

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

A n:else attribútum a következővel együtt is használható n:ifset, n:foreach, n:try, n:ifcontent, és n:ifchanged.

{/if $cond}

Meglepő lehet, hogy a {if} feltételben szereplő kifejezést a végtagban is meg lehet adni. Ez olyan helyzetekben hasznos, amikor a tag megnyitásakor még nem ismerjük a feltétel értékét. Nevezzük ezt halasztott döntésnek.

Például elkezdünk listázni egy táblázatot rekordokkal az adatbázisból, és csak a jelentés befejezése után vesszük észre, hogy nem volt rekord az adatbázisban. Ezért a {/if} címke végére feltételt teszünk, és ha nincs rekord, akkor egyik sem kerül kiírásra:

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

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

Praktikus, ugye?

A {else} a halasztott feltételben is használható, de a {elseif} nem.

{ifset} {elseifset}

Lásd még {ifset block}

A {ifset $var} feltétel segítségével meghatározhatja, hogy egy változó (vagy több változó) létezik-e, és van-e nem null értékű értéke. Ez tulajdonképpen ugyanaz, mint a if (isset($var)) a PHP-ben. Mint minden páros tag, ez is leírható n:attribútum formában, ezért mutassuk meg példában:

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

{ifchanged}

{ifchanged} ellenőrzi, hogy egy változó értéke megváltozott-e a ciklus (foreach, for vagy while) utolsó iterációja óta.

Ha egy vagy több változót adunk meg a címkében, akkor ellenőrzi, hogy valamelyik változott-e, és ennek megfelelően kiírja a tartalmát. A következő példa például a nevek felsorolásakor minden egyes változáskor a név első betűjét írja ki címként:

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

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

Ha azonban nem adunk meg argumentumot, akkor maga a megjelenített tartalom kerül ellenőrzésre a korábbi állapothoz képest. Ez azt jelenti, hogy az előző példában nyugodtan elhagyhatjuk az argumentumot a címkében. És természetesen használhatjuk az n:attribute-ot is:

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

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

{else} záradékot is beilleszthetünk a {ifchanged} belsejébe.

{switch} {case} {default}

Összehasonlítja az értéket több opcióval. Ez hasonló a PHP-ből ismert switch struktúrához. A Latte azonban továbbfejleszti:

• szigorú összehasonlítást használ (===)
• nem igényel break

Tehát ez pontosan megegyezik a PHP 8.0-ban található match struktúrával.

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

A {case} záradék több, vesszővel elválasztott értéket is tartalmazhat:

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

Hurok

A Latte-ban a PHP-ból ismert ciklusok állnak rendelkezésedre: foreach, for és while.

{foreach}

A ciklust pontosan ugyanúgy írja meg, mint a PHP-ben:

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

Ezen kívül van néhány praktikus csípése, amiről most beszélni fogunk.

Például Latte ellenőrzi, hogy a létrehozott változók véletlenül se írják felül az azonos nevű globális változókat. Ez megmenti Önt, amikor feltételezi, hogy a $lang az oldal aktuális nyelve, és nem veszi észre, hogy a foreach $langs as $lang felülírta az adott változót.

A foreach ciklus is nagyon elegánsan és gazdaságosan írható meg az n:attribútummal:

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

Tudtad, hogy az n:attribútumokhoz a inner- előtagot is be lehet illeszteni? Most akkor csak az elem belső része fog ismétlődni a ciklusban:

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

Tehát valami ilyesmit ír ki:

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

{else}

A foreach ciklushoz választható egy opcionális {else} záradék, amelynek szövege akkor jelenik meg, ha a megadott tömb üres:

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

$iterator

A foreach cikluson belül a $iterator változót inicializáljuk. Az aktuális ciklusra vonatkozó fontos információkat tárolja.

• $iterator->first – ez az első iteráció?
• $iterator->last – ez az utolsó iteráció?
• $iterator->counter – iterációs számláló, 1-től kezdődik.
• $iterator->counter0 – iterációs számláló, 0-ról indul.
• $iterator->odd – ez az iteráció páratlan?
• $iterator->even – ez az iteráció páros?
• $iterator->parent – az aktuális iterátort körülvevő iterátor.
• $iterator->nextValue – a ciklus következő eleme
• $iterator->nextKey – a ciklus következő elemének kulcsa.

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

A láta okos és a $iterator->last nemcsak tömbök esetén működik, hanem akkor is, ha a ciklus egy általános iterátoron fut át, ahol az elemek száma nem ismert előre.

{first} {last} {sep}

Ezek a címkék a {foreach} cikluson belül használhatók. A {first} tartalma az első menetben kerül megjelenítésre. A {last} tartalma renderelésre kerül … kitalálod? Igen, az utolsó lépésnél. Ezek valójában a {if $iterator->first} és a {if $iterator->last} rövidítései.

A címkék n:attribútumként is leírhatók:

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

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

	<hr n:last>
{/foreach}

A {sep} tartalma akkor kerül megjelenítésre, ha az iteráció nem az utolsó, így alkalmas olyan elhatárolójelek, mint például a felsorolt elemek közötti vesszők kiírására:

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

Ez elég praktikus, nem igaz?

{iterateWhile}

Egyszerűsíti a lineáris adatok csoportosítását a foreach ciklusban történő iteráció során egy beágyazott ciklusban történő iterálással, amíg egy feltétel nem teljesül. Olvassa el a részletes utasításokat.

Elegánsan helyettesítheti a {first} és a {last} címet is a fenti példában:

{foreach $rows as $row}
	<table>

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

	</table>
{/foreach}

Lásd még a kötegelt és csoportos szűrőket.

{for}

A ciklust pontosan ugyanúgy írjuk le, mint a PHP-ben:

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

A címkét n:attribútumként is írhatjuk:

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

{while}

A ciklust ismét pontosan ugyanúgy írjuk le, mint a PHP-ben:

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

Vagy n:attribútumként:

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

A végtagban lévő feltétellel rendelkező változat megfelel a do-while ciklusnak a PHP-ban:

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

{continueIf} {skipIf} {breakIf}

Vannak speciális címkék, amelyekkel bármely ciklus vezérlésére használhatod – {continueIf ?} és {breakIf ?}, amelyek a feltételek teljesülése esetén a következő iterációra ugranak, illetve befejezik a kört:

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

A {skipIf} címke nagyon hasonlít a {continueIf} címkéjéhez, de nem növeli a számlálót. Így nem keletkeznek lyukak a számozásban, ha a $iterator->counter kiírásával néhány elemet kihagyunk. A {else} záradék is megjelenik, ha minden elemet kihagyunk.

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

Befejezi egy sablon vagy blokk megjelenítését, ha egy feltétel teljesül (azaz “korai kilépés”).

{exitIf !$messages}

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

Beleértve a sablonokat

{include 'file.latte'}

Lásd még {include block}

A {include} címke betölti és megjeleníti a megadott sablont. Kedvenc PHP nyelvünkön ez így hangzik:

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

A bevont sablonok nem férnek hozzá az aktív kontextus változóihoz, de hozzáférnek a globális változókhoz.

A beillesztett sablonhoz a következő módon adhat át változókat:

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

A sablon neve bármilyen PHP-kifejezés lehet:

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

A beillesztett tartalom szűrőkkel módosítható. A következő példa eltávolít minden HTML-t és beállítja az esetet:

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

A sablon öröklés nem vesz részt ebben alapértelmezés szerint. Bár blokkcímkéket adhat hozzá a bevont sablonokhoz, ezek nem fogják helyettesíteni a megfelelő blokkokat abban a sablonban, amelybe bevonták őket. Gondoljon az inklúziókra úgy, mint az oldalak vagy modulok független és árnyékolt részeire. Ez a viselkedés a with blocks módosítóval módosítható:

{include 'template.latte' with blocks}

A címkében megadott fájlnév és a lemezen lévő fájl közötti kapcsolat a betöltő függvénye.

{sandbox}

Ha egy végfelhasználó által létrehozott sablont vesz fel, fontolja meg a sandboxolást (további információ a sandbox dokumentációban):

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

{block}

Lásd még {block name}

A név nélküli blokkok arra szolgálnak, hogy szűrőket alkalmazhassunk a sablon egy részére. Például alkalmazhat egy csíkszűrőt a felesleges szóközök eltávolítására:

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

Kivételkezelés

{try}

Ez a címke rendkívül megkönnyíti a robusztus sablonok készítését.

Ha a {try} blokk renderelése közben kivétel lép fel, az egész blokk elvetésre kerül, és a renderelés utána folytatódik:

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

A {else} opcionális záradék tartalma csak akkor kerül renderelésre, ha kivétel történik:

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

A címke n:attribútumként is írható:

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

Lehetőség van saját kivételkezelő definiálására is, pl. naplózáshoz:

{rollback}

A {try} blokk manuálisan is megállítható és kihagyható a {rollback} segítségével. Így nem kell előre ellenőrizni az összes bemeneti adatot, és csak a renderelés során lehet eldönteni, hogy van-e értelme renderelni az objektumot.

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

Változók

{var} {default}

A sablonban új változókat hozunk létre a {var} címkével:

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

{* Többszörös nyilatkozat *}
{var $name = 'John Smith', $age = 27}

A {default} címke hasonlóan működik, azzal a különbséggel, hogy csak akkor hoz létre változókat, ha azok nem léteznek. Ha egy változó már létezik, és tartalmazza a null címet, azt nem írja felül:

{default $lang = 'cs'}

A változók típusait is megadhatja. Ezek egyelőre tájékoztató jellegűek, és a Latte nem ellenőrzi őket.

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

{parameters}

Ahogyan egy függvény deklarálja a paramétereit, úgy egy sablon is deklarálhatja a változókat az elején:

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

A $a és $b változók alapértelmezett érték nélkül automatikusan a null alapértelmezett értéket kapják. A deklarált típusok továbbra is tájékoztató jellegűek, és a Latte nem ellenőrzi őket.

A deklarált változókon kívül más nem kerül át a sablonba. Ez egy különbség a {default} címkéhez képest.

{capture}

A {capture} címke használatával a kimenetet egy változóba rögzítheti:

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

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

A címke n:attribútumként is írható, mint bármelyik páros címke:

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

A HTML kimenet a $var változóban tárolódik Latte\Runtime\Html objektumként, hogy elkerülje a nem kívánt escapinget nyomtatáskor.

Egyéb

{contentType}

A címkével megadhatja, hogy a sablon milyen típusú tartalmat képvisel. A lehetőségek a következők:

• html (alapértelmezett típus)
• xml
• javascript
• css
• calendar (iCal)
• text

Használata azért fontos, mert ez állítja be a kontextusfüggő escapinget, és csak így tud a Latte helyesen menekülni. Például a {contentType xml} XML módba kapcsol, a {contentType text} pedig teljesen kikapcsolja az escapinget.

Ha a paraméter egy teljes értékű MIME-típus, például application/xml, akkor a Content-Type HTTP fejlécet is elküldi a böngészőnek:

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

{debugbreak}

Megadja azt a helyet, ahol a kód végrehajtása megszakad. Hibakeresési célokra szolgál, hogy a programozó ellenőrizze a futási környezetet, és biztosítsa, hogy a kód az elvárásoknak megfelelően fut. Támogatja az Xdebugot. Ezenkívül megadható egy feltétel, amikor a kódnak meg kell törnie.

{debugbreak}                {* megszakítja a programot *}

{debugbreak $counter == 1}  {* megszakítja a programot, ha a feltétel teljesül *}

{do}

Végrehajtja a PHP-kódot, és nem ír ki semmit. A többi címkéhez hasonlóan a PHP-kód is egyetlen kifejezés, lásd a PHP korlátait.

{do $num++}

{dump}

Egy változó vagy az aktuális kontextus kiürítése.

{dump $név} {* a $név változó kiírása *}

{dump}       {* dumps az összes definiált változót *}

A Tracy csomagot igényli.

{php}

Lehetővé teszi bármilyen PHP kód futtatását. A címkét a RawPhpExtension kiterjesztés használatával kell aktiválni.

{spaceless}

Eltávolítja a felesleges szóközöket. Hasonló a szóköz nélküli szűrőhöz.

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

Kimenetek:

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

A címke n:attribútumként is írható:

{syntax}

A latte címkéket nem kell csak szimpla szögletes zárójelek közé zárni. Választhat más elválasztójelet is, akár futás közben is. Erre szolgál a {syntax…}, ahol a paraméter lehet:

• double: {{...}}
• off: teljesen kikapcsolja a Latte címkéket

Az n:attribútum jelölés használatával csak egy JavaScript blokk esetében tilthatjuk le a Latte-et:

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

A Latte nagyon kényelmesen használható JavaScript-en belül, csak kerüljük az olyan konstrukciókat, mint ebben a példában, ahol a betű közvetlenül a { után következik, lásd: Latte JavaScripten vagy CSS-en belül.

Ha a {syntax off} (azaz tag, nem az n:attribútum) segítségével kapcsolja ki a Latte-t, akkor szigorúan figyelmen kívül hagyja az összes taget a {/syntax}-ig.

{trace}

Dob egy Latte\RuntimeException kivételt, amelynek stack trace-je a sablonok szellemében van. Így függvények és metódusok hívása helyett blokkok hívását és sablonok beillesztését foglalja magában. Ha a dobott kivételek egyértelmű megjelenítésére szolgáló eszközt, például a Tracy-t használja, akkor jól láthatóvá válik a hívási verem, beleértve az összes átadott argumentumot is.

HTML-tag-segédprogramok

n:class

A n:class segítségével nagyon könnyen létrehozható a class HTML-attribútum pontosan a kívánt módon.

Példa: Az aktív elemnek a active osztállyal kell rendelkeznie:

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

Továbbá az első elemnek a first és a main osztályokkal kell rendelkeznie:

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

És minden elemnek a list-item osztállyal kell rendelkeznie:

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

Elképesztően egyszerű, nem igaz?

n:attr

A n:attr attribútum tetszőleges HTML-attribútumokat generálhat, ugyanolyan eleganciával, mint az n:class.

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

A visszaadott értékektől függően megjeleníti pl:

<input type="checkbox">

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

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

n:tag

A n:tag attribútum dinamikusan megváltoztathatja egy HTML-elem nevét.

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

Ha a $heading === null, a <h1> címke változatlanul kiírásra kerül. Ellenkező esetben az elem neve a változó értékére változik, így a $heading === 'h3' esetében azt írja ki:

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

Mivel a Latte egy biztonságos templating rendszer, ellenőrzi, hogy az új tag neve érvényes-e, és nem tartalmaz-e nem kívánt vagy rosszindulatú értékeket.

n:ifcontent

Megakadályozza, hogy egy üres HTML-elem kiírásra kerüljön, azaz egy olyan elem, amely csak szóközöket tartalmaz.

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

A $error változó értékeitől függően ez kiíródik:

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

{* $error = 'Kötelező' *}
<div>
	<div class="error">Kötelező</div>
</div>

Fordítás

Ahhoz, hogy a fordítási címkék működjenek, be kell állítania a fordítót. Használhatja a translate szűrőt a fordításhoz.

{_...}

Lefordítja az értékeket más nyelvekre.

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

A fordítónak más paraméterek is átadhatók:

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

{translate}

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

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

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

attribútumként is írható, hogy lefordítsuk az elem belsejét:

<h1 n:translate>Order</h1>