Latte Tags

Povzetek in opis vseh vgrajenih oznak Latte.

Tiskanje

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

Latte uporablja oznako {=...} za izpis poljubnega izraza na izhod. Če se izraz začne s spremenljivko ali klicem funkcije, ni treba napisati znaka enakosti. Kar v praksi pomeni, da ga skoraj nikoli ni treba zapisati:

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

Kot izraz lahko zapišete karkoli, kar poznate iz PHP. Ni se vam treba učiti novega jezika. Na primer:

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

Če pa boste v prejšnjem primeru našli kakšen pomen, nam pišite :-)

Pobegli izpis

Katera je najpomembnejša naloga sistema predlog? Izogibanje varnostnim luknjam. In prav to stori Latte, kadar koli nekaj natisnete na izhod. Vse samodejno pobegne:

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

To je tako pomembna in edinstvena lastnost, da smo ji posvetili posebno poglavje.

In če iz zanesljivega vira natisnete vsebino, kodirano v HTML? Potem lahko pobege preprosto izklopite:

{$trustedHtmlString|noescape}

Zloraba filtra noescape lahko privede do ranljivosti XSS! Nikoli ga ne uporabljajte, razen če ste trdno prepričani, kaj počnete in da niz, ki ga tiskate, prihaja iz zaupanja vrednega vira.

Tiskanje v jeziku JavaScript

Zaradi kontekstno občutljivega eskapiranja je tiskanje spremenljivk v javascriptu zelo enostavno in Latte jih bo pravilno eskaliral.

Ni nujno, da je spremenljivka niz, podprta je katerakoli podatkovna vrsta, ki se nato kodira kot JSON:

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

Generira:

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

To je tudi razlog, zakaj spremenljivke ne postavljajte v narekovaje**: Latte jih doda okoli nizov. Če želite spremenljivko v nizu vstaviti v drug niz, ju preprosto združite:

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

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

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

Filtri

Izpisani izraz lahko spremenite s filtri. Ta primer na primer pretvori niz v velike črke in ga skrajša na največ 30 znakov:

{$string|upper|truncate:30}

Filtre lahko uporabite tudi za dele izraza, kot sledi:

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

Pogoji

{if} {elseif} {else}

Pogoji se obnašajo enako kot njihovi ustrezniki v jeziku PHP. Uporabljate lahko enake izraze, kot jih poznate iz PHP, ni se vam treba učiti novega jezika.

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

Tako kot katero koli drugo parno oznako lahko par {if} ... {/ if} zapišete kot n:atribut, na primer:

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

Ali veste, da lahko n:atributom dodate predpono tag-? Potem bo pogoj vplival samo na oznake HTML, vsebina med njimi pa bo vedno izpisana:

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

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

Lepo.

n:else

Če pogoj {if} ... {/if} zapišete v obliki n:atributa, imate možnost določiti alternativno vejo z uporabo n:else:

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

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

Atribut n:else lahko uporabite tudi v povezavi z n:ifset, n:foreach, n:try, n:ifcontent, in n:ifchanged.

{/if $cond}

Morda vas bo presenetilo, da lahko izraz v pogoju {if} določite tudi v končni oznaki. To je uporabno v primerih, ko ob odprtju oznake še ne poznamo vrednosti pogoja. Temu pravimo odložena odločitev.

Na primer, začnemo izpisovati tabelo z zapisi iz podatkovne zbirke in šele po končanem izpisu ugotovimo, da v podatkovni zbirki ni bilo nobenega zapisa. Zato na koncu oznake {/if} postavimo pogoj in če ni nobenega zapisa, se ne bo izpisal noben:

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

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

Priročno, kajne?

V odloženem pogoju lahko uporabite tudi {else}, ne pa tudi {elseif}.

{ifset} {elseifset}

Glej tudi {ifset block}

Pogoj {ifset $var} uporabite za ugotavljanje, ali spremenljivka (ali več spremenljivk) obstaja in ima vrednost, ki ni ničelna. To je pravzaprav enako kot if (isset($var)) v PHP. Kot vsako parno oznako lahko tudi to zapišemo v obliki n:atribut, zato jo prikažimo na primeru:

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

{ifchanged}

{ifchanged} preveri, ali se je vrednost spremenljivke spremenila od zadnje iteracije v zanki (foreach, for ali while).

Če v oznaki navedemo eno ali več spremenljivk, bo preveril, ali se je katera od njih spremenila, in ustrezno izpiše vsebino. Naslednji primer na primer pri naštevanju imen ob vsaki spremembi izpiše prvo črko imena kot naslov:

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

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

Če pa ni podan noben argument, se bo sama izpisana vsebina preverila glede na prejšnje stanje. To pomeni, da lahko v prejšnjem primeru argument v oznaki mirno izpustimo. Seveda lahko uporabimo tudi n:attribute:

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

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

V stavek {else} lahko vključite tudi stavek znotraj stavka {ifchanged}.

{switch} {case} {default}

Primerja vrednost z več možnostmi. To je podobno strukturi switch, ki jo poznate iz PHP. Vendar jo Latte izboljša:

• uporablja strogo primerjavo (===)
• ne potrebuje break

Tako je to natančen ekvivalent strukture match, ki jo vsebuje PHP 8.0.

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

Klavzula {case} lahko vsebuje več vrednosti, ločenih z vejicami:

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

Zanke

V Latte so vam na voljo vse zanke, ki jih poznate iz PHP: foreach, for in while.

{foreach}

Cikel zapišete na popolnoma enak način kot v PHP:

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

Poleg tega ima nekaj priročnih izboljšav, o katerih bomo govorili zdaj.

Latte na primer preverja, da ustvarjene spremenljivke ne prepišejo globalnih spremenljivk z istim imenom. To vas bo rešilo, ko boste domnevali, da je $lang trenutni jezik strani, in se ne boste zavedali, da je foreach $langs as $lang prepisala to spremenljivko.

Z n:atributom lahko zelo elegantno in ekonomično zapišete tudi zanko foreach:

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

Ali ste vedeli, da lahko predpono inner- dodamo predponi n:attributes? Zdaj se bo v zanki ponovil samo notranji del elementa:

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

Tako se izpiše nekaj takega:

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

{else}

Zanka foreach lahko sprejme neobvezno {else} določilo, katerega besedilo se prikaže, če je podano polje prazno:

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

$iterator

Znotraj zanke foreach se inicializira spremenljivka $iterator. V njej so shranjene pomembne informacije o trenutni zanki.

• $iterator->first – ali je to prva iteracija?
• $iterator->last – ali je to zadnja iteracija?
• $iterator->counter – števec iteracij, začne se od 1
• $iterator->counter0 – števec iteracij, začne se z 0
• $iterator->odd – ali je ta iteracija liha?
• $iterator->even – ali je ta iteracija soda?
• $iterator->parent – iterator, ki obkroža trenutni iterator
• $iterator->nextValue – naslednji element v zanki
• $iterator->nextKey – ključ naslednjega elementa v zanki

{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 je pametna in $iterator->last ne deluje le za polja, temveč tudi takrat, ko zanka teče nad splošnim iteratorjem, kjer število elementov ni vnaprej znano.

{first} {last} {sep}

Te oznake lahko uporabite znotraj zanke {foreach}. Vsebina {first} se pri prvem prehodu izriše. Vsebina {last} se prikaže … lahko uganete? Da, pri zadnjem prehodu. To so pravzaprav bližnjice za {if $iterator->first} in {if $iterator->last}.

Oznake se lahko zapišejo tudi kot n:attributes:

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

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

	<hr n:last>
{/foreach}

Vsebina {sep} se izriše, če iteracija ni zadnja, zato je primerna za izpis razmejitvenih elementov, kot so vejice med naštetimi elementi:

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

To je precej praktično, kajne?

{iterateWhile}

Poenostavi razvrščanje linearnih podatkov v skupine med iteracijo v zanki foreach z iteracijo v ugnezdeni zanki, dokler ni izpolnjen pogoj. Preberite podrobna navodila.

Elegantno lahko nadomesti tudi {first} in {last} v zgornjem primeru:

{foreach $rows as $row}
	<table>

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

	</table>
{/foreach}

Oglejte si tudi paketne in skupinske filtre.

{for}

Cikel zapišemo na popolnoma enak način kot v PHP:

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

Oznaka se lahko zapiše tudi kot n:atribut:

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

{while}

Ponovno zapišemo cikel na popolnoma enak način kot v PHP:

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

ali kot n:atribut:

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

Varianta s pogojem v končni oznaki ustreza zanki do-while v PHP:

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

{continueIf} {skipIf} {breakIf}

Obstajajo posebne oznake, ki jih lahko uporabite za nadzor katere koli zanke – {continueIf ?} in {breakIf ?}, s katerima preskočite na naslednjo iteracijo oziroma končate zanko, če so izpolnjeni pogoji:

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

Oznaka {skipIf} je zelo podobna oznaki {continueIf}, vendar ne povečuje števca. Tako ni lukenj v številčenju, če izpišete $iterator->counter in preskočite nekatere elemente. Tudi določilo {else} bo izpisano, če preskočite vse elemente.

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

Zaključi upodabljanje predloge ali bloka, ko je izpolnjen pogoj (tj. “zgodnji izhod”).

{exitIf !$messages}

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

Vključevanje predlog

{include 'file.latte'}

Glej tudi {include block}

Oznaka {include} naloži in prikaže določeno predlogo. V našem priljubljenem jeziku PHP je to tako:

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

Vključene predloge nimajo dostopa do spremenljivk aktivnega konteksta, imajo pa dostop do globalnih spremenljivk.

Vstavljeni predlogi lahko spremenljivke posredujete na naslednji način:

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

Ime predloge je lahko kateri koli izraz PHP:

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

Vstavljeno vsebino je mogoče spremeniti s filtri. Naslednji primer odstrani vse elemente HTML in prilagodi primer:

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

Dedovanje predlog pri tem privzeto ne sodeluje. Čeprav lahko v vključene predloge dodate oznake blokov, te ne bodo nadomestile ustreznih blokov v predlogi, v katero so vključene. Vključitve si predstavljajte kot neodvisne in zaščitene dele strani ali modulov. To obnašanje lahko spremenite z uporabo modifikatorja with blocks:

{include 'template.latte' with blocks}

Razmerje med imenom datoteke, navedenim v oznaki, in datoteko na disku je stvar nalagalnika.

{sandbox}

Če vključite predlogo, ki jo je ustvaril končni uporabnik, morate razmisliti o tem, da jo vključite v peskovnik (več informacij v dokumentaciji o peskovniku):

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

{block}

Glej tudi {block name}

Bloki brez imena omogočajo uporabo filtrov za del predloge. Uporabite lahko na primer filter za odstranjevanje nepotrebnih presledkov:

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

Obravnava izjem

{try}

S temi oznakami je izredno enostavno izdelati robustne predloge.

Če se med izrisovanjem bloka {try} pojavi izjema, se celoten blok zavrže in izrisovanje se nadaljuje po njem:

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

Vsebina neobveznega stavka {else} se izriše le, če pride do izjeme:

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

Oznaka je lahko zapisana tudi kot n:atribut:

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

Prav tako je mogoče definirati lastne izvajalce izjem za npr. beleženje:

{rollback}

Blok {try} lahko ustavite in preskočite tudi ročno z uporabo {rollback}. Tako vam ni treba vnaprej preveriti vseh vhodnih podatkov, šele med izrisovanjem pa se lahko odločite, ali je smiselno objekt izrisati.

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

Spremenljivke

{var} {default}

V predlogi bomo ustvarili nove spremenljivke z oznako {var}:

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

{* Večkratna deklaracija *}
{var $name = 'John Smith', $age = 27}

Oznaka {default} deluje podobno, le da ustvarja spremenljivke le, če ne obstajajo. Če spremenljivka že obstaja in vsebuje oznako null, se ne prepiše:

{default $lang = 'cs'}

Določite lahko tudi vrste spremenljivk. Za zdaj so informativne in jih Latte ne preverja.

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

{parameters}

Tako kot funkcija deklarira svoje parametre, lahko tudi predloga na začetku deklarira svoje spremenljivke:

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

Spremenljivki $a in $b brez privzete vrednosti imata samodejno privzeto vrednost null. Deklarirane vrste so še vedno informativne in jih Latte ne preverja.

Druge kot deklarirane spremenljivke se ne posredujejo v predlogo. To je razlika v primerjavi z oznako {default}.

{capture}

Z uporabo oznake {capture} lahko izhodne podatke zajamete v spremenljivko:

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

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

Oznaka je lahko zapisana tudi kot n:attribute, kot vsaka parna oznaka:

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

Izpis HTML je shranjen v spremenljivki $var kot predmet Latte\Runtime\Html, da se pri tiskanju izognemo nezaželenemu escapiranju.

Drugo

{contentType}

Z oznako določite, katero vrsto vsebine predstavlja predloga. Možnosti so:

• html (privzeta vrsta)
• xml
• javascript
• css
• calendar (iCal)
• text

Njegova uporaba je pomembna, ker nastavi kontekstno občutljivo eskapiranje in le tako lahko Latte pravilno eskapira. Na primer, {contentType xml} preklopi v način XML, {contentType text} pa popolnoma izklopi escapiranje.

Če je parameter polnopravna vrsta MIME, kot je application/xml, se brskalniku pošlje tudi glavička HTTP Content-Type:

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

{debugbreak}

Določa mesto, kjer se izvajanje kode prekine. Uporablja se za namene razhroščevanja, da lahko programer preveri okolje izvajanja in zagotovi, da se koda izvaja v skladu s pričakovanji. Podpira Xdebug. Poleg tega lahko določite pogoj, kdaj naj se koda prekine.

{debugbreak}                {* prekinitev programa *}

{debugbreak $counter == 1}  {* prekine program, če je pogoj izpolnjen *}

{do}

Izvrši kodo PHP in ne izpiše ničesar. Tako kot pri vseh drugih oznakah je PHP koda en sam izraz, glejte Omejitve PHP.

{do $num++}

{dump}

Izbriše spremenljivko ali trenutni kontekst.

{dump $name} {* odvrže spremenljivko $name *}

{dump}       {* izprazni vse definirane spremenljivke *}

Zahteva paket Tracy.

{php}

Omogoča izvajanje katere koli kode PHP. Oznaka mora biti aktivirana z razširitvijo RawPhpExtension.

{spaceless}

Odstrani nepotrebne bele lise. Podoben je filtru brez presledkov.

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

Rezultati:

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

Izpisi: Oznaka se lahko zapiše tudi kot n:attribute:

{syntax}

Oznake Latte ni treba zapirati samo v enojne oglate oklepaje. Tudi med izvajanjem lahko izberete drugo ločilo. To storite s pomočjo spletne strani {syntax…}, kjer je lahko parameter:

• dvojno: {{...}}
• off: popolnoma onemogoči oznake Latte

Z uporabo zapisa n:attribute lahko onemogočimo Latte samo za blok JavaScript:

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

Latte se lahko zelo udobno uporablja znotraj JavaScripta, le izogibajte se konstrukcijam kot v tem primeru, kjer črka sledi takoj za {, glejte Latte znotraj JavaScripta ali CSS.

Če Latte izklopite s {syntax off} (tj. z oznako, ne z atributom n:), bo strogo ignoriral vse oznake do {/syntax}.

{trace}

Vrže izjemo Latte\RuntimeException, katere zasledovanje je v duhu predlog. Tako namesto klicanja funkcij in metod vključuje klicanje blokov in vstavljanje predlog. Če uporabljate orodje za jasen prikaz vrženih izjem, kot je Tracy, boste jasno videli klicni niz, vključno z vsemi posredovanimi argumenti.

Pomočniki za oznake HTML

n:class

Zahvaljujoč n:class, je zelo enostavno ustvariti atribut HTML class točno tako, kot potrebujete.

Primer: Potrebujem, da ima element active razred active:

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

Poleg tega potrebujem, da ima prvi element razreda first in main:

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

Vsi elementi pa morajo imeti razred list-item:

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

Neverjetno preprosto, kajne?

n:attr

Atribut n:attr lahko ustvari poljubne atribute HTML z enako eleganco kot n:class.

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

Glede na vrnjene vrednosti prikaže npr:

<input type="checkbox">

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

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

n:tag

Atribut n:tag lahko dinamično spremeni ime elementa HTML.

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

Če je $heading === null, je <h1> se oznaka izpiše brez sprememb. V nasprotnem primeru se ime elementa spremeni v vrednost spremenljivke, tako da se za $heading === 'h3' zapiše:

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

Ker je Latte varen sistem za oblikovanje predlog, preveri, ali je ime nove oznake veljavno in ne vsebuje neželenih ali zlonamernih vrednosti.

n:ifcontent

Preprečuje izpis praznega elementa HTML, tj. elementa, ki vsebuje le bele prostore.

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

Odvisno od vrednosti spremenljivke $error se bo to natisnilo:

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

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

Prevod

Za delovanje prevajalskih oznak morate nastaviti prevajalnik. Uporabite lahko tudi translate filter za prevajanje.

{_...}

Prevaja vrednosti v druge jezike.

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

Prevajalniku lahko posredujete tudi druge parametre:

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

{translate}

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

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

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

Za prevajanje notranjosti elementa se lahko oznaka zapiše tudi kot n:attribute:

<h1 n:translate>Order</h1>