Oznake Latte

Pregled in opis vseh oznak sistema predlog Latte, ki so vam standardno na voljo.

Izpisovanje

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

V Latte se uporablja oznaka {=...} za izpis katerega koli izraza na izhod. Latte skrbi za vaše udobje, zato če se izraz začne s spremenljivko ali klicem funkcije, ni treba pisati enačaja. Kar v praksi pomeni, da ga skoraj nikoli ni treba pisati:

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

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

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

Prosim, ne iščite v prejšnjem primeru nobenega smisla, a če bi ga tam našli, nam pišite :-)

Ubežanje izpisa

Kaj je najpomembnejša naloga sistema predlog? Preprečiti varnostne luknje. In natanko to počne Latte vedno, ko nekaj izpisujete. Samodejno to ubeži:

<p>{='one < two'}</p>   {* izpiše: '<p>one &lt; two</p>' *}

Da bi bili natančni, Latte uporablja kontekstno občutljivo ubežanje, kar je tako pomembna in edinstvena stvar, da smo ji posvetili ločeno poglavje.

In kaj če izpisujete vsebino, kodirano v HTML, iz zaupanja vrednega vira? Potem lahko enostavno izklopite ubežanje:

{$trustedHtmlString|noescape}

Napačna uporaba filtra noescape lahko vodi do nastanka ranljivosti XSS! Nikoli ga ne uporabljajte, če niste popolnoma prepričani, kaj počnete, in da izpisani niz prihaja iz zaupanja vrednega vira.

Izpis v JavaScriptu

Zahvaljujoč kontekstno občutljivemu ubežanju je čudovito enostavno izpisovati spremenljivke znotraj JavaScripta in pravilno ubežanje uredi Latte.

Spremenljivka ni nujno samo niz, podprt je kateri koli podatkovni tip, ki se nato zakodira kot JSON:

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

Generira:

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

To je tudi razlog, zakaj se okoli spremenljivke ne pišejo narekovaji: Latte jih pri nizih doda sam. In če bi želeli nizovno spremenljivko vstaviti v drug niz, jih preprosto združite:

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

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

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

Filtri

Izpisani izraz je mogoče spremeniti s filtrom. Tako na primer niz pretvorimo v velike črke in skrajšamo na največ 30 znakov:

{$string|upper|truncate:30}

Filtre lahko uporabljate tudi na delnih delih izraza na ta način:

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

Pogoji

{if} {elseif} {else}

Pogoji se obnašajo enako kot njihovi ustrezni v PHP. V njih lahko uporabljate tudi enake izraze, kot jih poznate iz PHP, ni vam treba učiti novega jezika.

{if $product->inStock > Stock::Minimum}
	Na zalogi
{elseif $product->isOnWay()}
	Na poti
{else}
	Ni na voljo
{/if}

Kot vsako parno oznako, tako tudi dvojico {if} ... {/if} lahko zapišemo tudi v obliki n:attributu, na primer:

<p n:if="$count > 0">Na zalogi {$count} kosov</p>

Veste, da lahko n:atributom dodate predpono tag-? Potem se bo pogoj nanašal samo na izpis oznak HTML in vsebina med njimi se bo izpisala vedno:

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

{* izpiše 'Hello', ko je $clickable neresničen *}
{* izpiše '<a href="...">Hello</a>', ko je $clickable resničen *}

Božansko.

n:else

Če pogoj {if} ... {/if} zapišete v obliki n:attributu, imate možnost navesti tudi alternativno vejo s pomočjo n:else:

<strong n:if="$count > 0">Na zalogi {$count} kosov</strong>

<em n:else>ni na voljo</em>

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

{/if $cond}

Morda vas bo presenetilo, da lahko izraz v pogoju {if} navedete tudi v zaključni oznaki. To pride prav v situacijah, ko ob odpiranju pogoja njegove vrednosti še ne poznamo. Recimo temu odložena odločitev.

Na primer, začnemo izpisovati tabelo z zapisi iz baze podatkov in šele po končanem izpisu ugotovimo, da v bazi podatkov ni bilo nobenega zapisa. Tako damo na to pogoj v končno oznako {/if} in če nobenega zapisa ne bo, se nič od tega ne bo izpisalo:

{if}
	<h1>Izpis vrstic iz baze podatkov</h1>

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

Priročno, kajne?

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

{ifset} {elseifset}

Glejte tudi {ifset block}

S pomočjo pogoja {ifset $var} ugotovimo, ali spremenljivka (ali več spremenljivk) obstaja in ima vrednost, ki ni null. Pravzaprav gre za isto kot if (isset($var)) v PHP. Kot vsako parno oznako jo lahko zapišemo tudi v obliki n:attributu, zato si to poglejmo kot primer:

<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 preverjal, ali se je katera od njih spremenila, in glede na to izpisal vsebino. Na primer, naslednji primer izpiše prvo črko imena kot naslov vsakič, ko se pri izpisu imen spremeni:

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

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

Če pa ne navedemo nobenega argumenta, se bo preverjala izrisana vsebina v primerjavi z njenim prejšnjim stanjem. To pomeni, da lahko v prejšnjem primeru mirno izpustimo argument v oznaki. In seveda lahko uporabimo tudi n:attribut:

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

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

Znotraj {ifchanged} lahko navedemo tudi klavzulo {else}.

{switch} {case} {default}

Primerja vrednost z več možnostmi. Gre za analogijo pogojnemu stavku switch, ki ga poznate iz PHP. Vendar ga Latte izboljšuje:

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

Je torej natančen ekvivalent strukture match, s katero prihaja PHP 8.0.

{switch $transport}
	{case train}
		Z vlakom
	{case plane}
		Z letalom
	{default}
		Drugače
{/switch}

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

{switch $status}
{case $status::New}<b>nova postavka</b>
{case $status::Sold, $status::Unknown}<i>ni na voljo</i>
{/switch}

Zanke

V Latte najdete vse zanke, ki jih poznate iz PHP: foreach, for in while.

{foreach}

Zanko zapišemo popolnoma enako kot v PHP:

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

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

Latte na primer preverja, ali ustvarjene spremenljivke pomotoma ne prepišejo globalnih spremenljivk istega imena. To reši situacije, ko računate na to, da je v $lang trenutni jezik strani, in se ne zavedate, da vam je foreach $langs as $lang to spremenljivko prepisalo.

Zanko foreach lahko tudi zelo elegantno in varčno zapišemo s pomočjo n:attributu:

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

Veste, da lahko n:atributom dodate predpono inner-? Potem se bo v zanki ponavljala samo notranjost 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}

Znotraj zanke foreach lahko navedemo klavzulo {else}, katere vsebina se prikaže, če je zanka prazna:

<ul>
	{foreach $people as $person}
		<li>{$person->name}</li>
	{else}
		<li><em>Žal na tem seznamu ni uporabnikov</em></li>
	{/foreach}
</ul>

$iterator

Znotraj zanke foreach Latte ustvari spremenljivko $iterator, s pomočjo katere lahko ugotavljamo koristne informacije o potekajoči zanki:

• $iterator->first – ali gre za prvi prehod skozi zanko?
• $iterator->last – ali gre za zadnji prehod?
• $iterator->counter – kateri prehod je to, šteto od ena?
• $iterator->counter0 – kateri prehod je to, šteto od nič?
• $iterator->odd – ali gre za lih prehod?
• $iterator->even – ali gre za sod prehod?
• $iterator->parent – iterator, ki obdaja trenutnega
• $iterator->nextValue – naslednja postavka v zanki
• $iterator->nextKey – ključ naslednje postavke 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 pameten in $iterator->last deluje ne samo pri poljih, ampak tudi, ko zanka poteka nad splošnim iteratorjem, kjer število postavk ni vnaprej znano.

{first} {last} {sep}

Te oznake lahko uporabljamo znotraj zanke {foreach}. Vsebina {first} se izriše, če gre za prvi prehod. Vsebina {last} se izriše … ali uganete? Da, če gre za zadnji prehod. Pravzaprav gre za okrajšave za {if $iterator->first} in {if $iterator->last}.

Oznake lahko tudi elegantno uporabimo kot n:attribut:

{foreach $rows as $row}
	{first}<h1>Seznam imen</h1>{/first}

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

	<hr n:last>
{/foreach}

Vsebina oznake {sep} se izriše, če prehod ni zadnji, zato je primerna za izrisovanje ločil, na primer vejic med izpisanimi postavkami:

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

To je precej praktično, kajne?

{iterateWhile}

Poenostavlja združevanje linearnih podatkov med iteriranjem v zanki foreach tako, da iteracijo izvaja v vgnezdeni zanki, dokler je pogoj izpolnjen. Preberite podrobna navodila.

Lahko tudi elegantno nadomesti {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}

Glejte tudi filtre batch in group.

{for}

Zanko zapišemo popolnoma enako kot v PHP:

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

Oznako lahko uporabimo tudi kot n:attribut:

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

{while}

Zanko spet zapišemo popolnoma enako kot v PHP:

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

Ali kot n:attribut:

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

Možna je tudi varianta s pogojem v končni oznaki, ki ustreza v PHP zanki do-while:

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

{continueIf} {skipIf} {breakIf}

Za krmiljenje katere koli zanke lahko uporabljamo oznake {continueIf ?} in {breakIf ?}, ki preidejo na naslednji element oz. končajo zanko ob izpolnitvi pogoja:

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

Oznaka {skipIf} je zelo podobna kot {continueIf}, vendar ne povečuje števca $iterator->counter, tako da če ga izpisujemo in hkrati preskočimo nekatere postavke, v številčenju ne bo lukenj. In tudi klavzula {else} se izriše, ko preskočimo vse postavke.

<ul>
	{foreach $people as $person}
		{skipIf $person->age < 18}
		<li>{$iterator->counter}. {$person->name}</li>
	{else}
		<li><em>Žal na tem seznamu ni odraslih</em></li>
	{/foreach}
</ul>

{exitIf}

Konča izrisovanje predloge ali bloka ob izpolnitvi pogoja (t.i. “early exit”).

{exitIf !$messages}

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

Vstavljanje predloge

{include 'file.latte'}

Glejte tudi {include block}

Oznaka {include} naloži in izriše navedeno predlogo. Če bi govorili v jeziku našega priljubljenega jezika PHP, je to nekaj takega kot:

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

Vstavljene predloge nimajo dostopa do spremenljivk aktivnega konteksta, imajo dostop samo do globalnih spremenljivk.

Spremenljivke lahko v vstavljeno predlogo posredujete na ta način:

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

Ime predloge je lahko kateri koli izraz v PHP:

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

Vstavljeno vsebino lahko uredite s pomočjo filtrov. Naslednji primer odstrani ves HTML in prilagodi velikost črk:

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

Privzeto dedovanje predlog v tem primeru nikakor ne figurira. Čeprav lahko v vključeni predlogi uporabljamo bloke, ne pride do zamenjave ustreznih blokov v predlogi, v katero se vključuje. Razmišljajte o vključenih predlogah kot o samostojnih zasenčenih delih strani ali modulov. To vedenje se da spremeniti s pomočjo modifikatorja with blocks:

{include 'template.latte' with blocks}

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

{sandbox}

Pri vstavljanju predloge, ki jo je ustvaril končni uporabnik, bi morali razmisliti o načinu peskovnika (več informacij v dokumentaciji peskovnika):

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

{block}

Glejte tudi {block name}

Bloki brez imena služijo kot način za uporabo filtrov na delu predloge. Na primer, tako lahko uporabimo filter strip, ki odstrani nepotrebne presledke:

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

Upravljanje izjem

{try}

Zahvaljujoč tej oznaki je izjemno enostavno ustvarjati robustne predloge.

Če pri izrisovanju bloka {try} pride do izjeme, se celoten blok zavrže in izrisovanje se bo nadaljevalo šele po njem:

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

Vsebina v neobvezni klavzuli {else} se izriše samo, če nastane izjema:

{try}
	<ul>
		{foreach $twitter->loadTweets() as $tweet}
  			<li>{$tweet->text}</li>
		{/foreach}
	</ul>
	{else}
	<p>Žal nam je, ni uspelo naložiti tvitov.</p>
{/try}

Oznako lahko uporabimo tudi kot n:attribut:

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

Možno je tudi definirati lasten obdelovalnik izjem po meri, na primer zaradi beleženja.

{rollback}

Blok {try} lahko ustavimo in preskočimo tudi ročno s pomočjo {rollback}. Zahvaljujoč temu ni treba vnaprej preverjati vseh vhodnih podatkov in se šele med izrisovanjem lahko odločite, da objekta sploh ne želite izrisati:

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

Spremenljivke

{var} {default}

Nove spremenljivke ustvarimo v predlogi z oznako {var}:

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

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

Oznaka {default} deluje podobno, vendar ustvarja spremenljivke samo takrat, ko ne obstajajo. Če spremenljivka že obstaja in vsebuje vrednost null, ne bo prepisana:

{default $lang = 'sl'}

Lahko navajate tudi tipe spremenljivk. Zaenkrat so informativni in Latte jih 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 navedene privzete vrednosti imata samodejno privzeto vrednost null. Deklarirani tipi so zaenkrat informativni in Latte jih ne preverja.

Druge spremenljivke kot deklarirane se v predlogo ne prenašajo. S tem se razlikuje od oznake {default}.

{capture}

Zajame izpis v spremenljivko:

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

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

Oznako lahko, podobno kot vsako parno oznako, zapišemo tudi kot n:attribut:

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

Izhod HTML se v spremenljivko $var shrani v obliki objekta Latte\Runtime\Html, da ne pride do neželenega ubežanja pri izpisu.

Ostalo

{contentType}

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

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

Njena uporaba je pomembna, ker nastavi kontekstno občutljivo ubežanje in samo tako lahko pravilno ubeži. Na primer {contentType xml} preklopi v način XML, {contentType text} ubežanje popolnoma izklopi.

Če je parameter polnopravni MIME type, kot na primer application/xml, potem še dodatno pošlje HTTP glavo Content-Type v brskalnik:

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

{debugbreak}

Označuje mesto, kjer pride do zaustavitve izvajanja programa in zagona razhroščevalnika, da lahko programer pregleda okolje izvajanja in ugotovi, ali program deluje po pričakovanjih. Podpira Xdebug. Lahko dopolnite pogoj, ki določa, kdaj naj se program zaustavi.

{debugbreak}                {* zaustavi program *}

{debugbreak $counter == 1}  {* zaustavi program ob izpolnitvi pogoja *}

{do}

Izvede kodo PHP in ničesar ne izpisuje. Enako kot pri vseh drugih oznakah se s kodo PHP razume en izraz, glejte omejitve PHP.

{do $num++}

{dump}

Izpiše spremenljivko ali trenutni kontekst.

{dump $name} {* Izpiše spremenljivko $name *}

{dump}       {* Izpiše vse trenutno definirane spremenljivke *}

Zahteva knjižnico Tracy.

{php}

Omogoča izvedbo katere koli kode PHP. Oznako je treba aktivirati s pomočjo razširitve RawPhpExtension.

{spaceless}

Odstrani nepotrebne presledke iz izpisa. Deluje podobno kot filter spaceless.

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

Generira

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

Oznako lahko zapišemo tudi kot n:attribut.

{syntax}

Oznake Latte ni treba omejiti samo na enojne zavite oklepaje. Lahko si izberemo tudi drug ločevalnik in to celo med izvajanjem. Za to služi {syntax …}, kjer kot parameter lahko navedemo:

• double: {{...}}
• off: popolnoma izklopi obdelavo oznak Latte

Z uporabo n:atributov lahko izklopimo Latte na primer samo za en blok JavaScripta:

<script n:syntax="off">
	var obj = {var: 123}; // to ni več oznaka
</script>

Latte je mogoče zelo udobno uporabljati tudi znotraj JavaScripta, le izogniti se je treba konstruktom kot v tem primeru, ko sledi črka takoj za {, glejte Latte znotraj JavaScripta ali CSS.

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

{trace}

Sproži izjemo Latte\RuntimeException, katere sledenje sklada (stack trace) je v duhu predlog. Torej namesto klicev funkcij in metod vsebuje klice blokov in vstavljanje predlog. Če uporabljate orodje za pregledno prikazovanje sproženih izjem, kot je na primer Tracy, se vam pregledno prikaže klicni sklad (call stack) vključno z vsemi posredovanimi argumenti.

Pomočniki kodirnika HTML

n:class

Zahvaljujoč n:class zelo enostavno generirate atribut HTML class natančno po predstavah.

Primer: potrebujem, da ima aktivni element razred active:

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

In nadalje, da ima prvi element razreda first in main:

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

In vsi elementi naj imajo 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 zna z enako eleganco kot ima n:class generirati poljubne atribute HTML.

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

Glede na vrnjene vrednosti izpiše npr.:

<input type="checkbox">

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

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

n:tag

Atribut n:tag zna dinamično spreminjati ime elementa HTML.

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

Če je $heading === null, se izpiše nespremenjena oznaka <h1>. Sicer se spremeni ime elementa na vrednost spremenljivke, tako da se za $heading === 'h3' izpiše:

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

Ker je Latte varen sistem predlog, preverja, ali je novo ime oznake veljavno in ne vsebuje nobenih neželenih ali škodljivih vrednosti.

n:ifcontent

Preprečuje, da bi se izpisal prazen element HTML, tj. element, ki ne vsebuje ničesar razen presledkov.

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

Izpiše glede na vrednost spremenljivke $error:

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

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

Prevodi

Da bi oznake za prevod delovale, je treba aktivirati prevajalnik. Za prevod lahko uporabite tudi filter translate.

{_...}

Prevaja vrednosti v druge jezike.

<a href="basket">{_'Košarica'}</a>
<span>{_$item}</span>

Prevajalniku lahko posredujete tudi druge parametre:

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

{translate}

Prevaja dele predloge:

<h1>{translate}Naročilo{/translate}</h1>

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

Oznako lahko zapišemo tudi kot n:attribut, za prevod notranjosti elementa:

<h1 n:translate>Naročilo</h1>