Dokumentace grafických šablon
Změny v HTML šablonách grafiky e-shopu je možné provádět pouze po aktivaci Rozšířených možností Editoru kódu (více zde). Pro přehlednost se používá šablonovací jazyk Latte s následujícímí specifickými možnostmi, jejichž vysvětlení je předmětem této stránky.
Dokumentace se seznamem proměnných není k dispozici. Pravidlem je, že použít lze pouze ty proměnné, které se aktuálně vyskytují v HTML šablonách. Ty si lze vyhledat podle jejich počátečních znaků {$ . Více zde.
Pro informace ohledně úprav stylů CSS přejděte zde, pro Javascript přejděte zde.
Struktura adresářů a souborů
Více informací najdete v dokumentaci zde.
Značky, filtry, helpery
Šablony jsou soubory s příponou .phtml umístěné v adresářové struktuře. Jejich obsahem je HTML kód, typicky určující layout výsledné stránky.
Obsahují Latte filtery sloužící nejen pro usnadnění zápisu šablon, ale také umožňují pracovat s bloky a podporují kontextově sensitivní escapování.
Základní makra
V kódu šablon lze použít pouze následující seznam značek. Ostatní jsou systémově zakázány.
| Zápis v Latte | PHP ekvivalent nebo význam |
|---|---|
{$variable} |
Vypíše kontextově escapovanou proměnnou. |
{!$variable} |
Vypíše proměnnou bez escapování. |
{* text komentáře *} |
Komentář; bude odstraněn. |
{plink ...} |
Vypíše kontextově escapovaný odkaz. |
{link ...} |
Odkaz nad komponentou. |
{if ?} ... {elseif ?} ... {/if} |
<?php if (?): ?> ... <?php elseif (?): ?> ... <?php endif ?> |
{foreach ?} ... {/foreach} |
<?php foreach (?): ?> ... <?php endforeach ?> |
{for ?} ... {/for} |
<?php foreach (?): ?> ... <?php endforeach ?> |
{while ?} ... {/while}{$variable} |
<?php while (?): ?> ... <?php endwhile ?> |
{include dir/file.phtml} |
Vloží podšablonu. |
{var foo => value} |
Deklaruje proměnnou v šabloně. |
{default foo => value} |
Výchozí hodnoty proměnných šablony. |
{control leftMenu} |
Vykreslí komponentu s daným názvem. |
{l} a {r} |
Vloží znaky { a }. |
Výpis proměnných
Všechny proměnné jsou vypisovány escapované.
Jméno: {$name}<br>
Příjmení: {$surname}<br>
Věk: {$age}
Pokud z nějakého důvodu potřebujeme escapování vypnout, tak před dolar vložíme vykřičník.
<h1>{$title}</h1> {* Escapovaný titulek *}
{!$content} {* Neescapovaný obsah stránky *}
Přizpůsobení escapování podle lokálního typu obsahu
Velmi důležitou vlastností je přizpůsobení escapování podle lokálního typu obsahu (tzv. kontextově senzitivní escapování). Uvnitř JavaScriptu nebo uvnitř CSS se escapuje jinak, než v HTML kódu. Díky tomu je možné zcela nativně používat proměnné uvnitř JavaScriptového kódu.
Příklad:
$template->pole = array(1, 2, 3);
$template->name = "Jim Beam";
<script type="text/javascript">
var pole = {$pole};
var name = {$name}; // ALE POZOR - NESMÍ se už používat extra uvozovky
var anotherName = "{$name}"; // CHYBA, vygeneruje anotherName = ""Jim Beam"";
</script>
Vložíme-li proměnnou v šabloně do html, css nebo javascriptu, vždy se správně escapuje ($id je nějaký identifikátor obsahující libovolné znaky):
<style type="text/css">
#{$id} { background: blue; }
</style>
<script type="text/javascript">
document.getElementById({$id}).style.backgroundColor = 'red';
</script>
<p id="{$id}">Hello!</p>
Vkládání odkazů {plink ...}
Značka {plink} je zkratkou pro $presenter->link a slouží tedy pro generování odkazu na danou akci daného presenteru s danými parametry, resp. na daný signál. Pro zápis cesty se používá stejná syntaxe jako při generování odkazů v presenteru.
{* Vygeneruje relativní cestu na `ProductsPresenter` a na akci detail *}
{plink Product:view, id => $productId}
{* Pokud je aktuálním presenterem právě `ProductPresenter`, tak lze vynechat i jeho jméno *}
{plink view, $productId}
{* Ve všech případech lze předat i více parametrů *}
{plink detail, id => $productId, from => "search", ...}
{plink detail, $productId, from => "search", ...}
Vkládání odkazů {link ...}
Funguje podobně jako {plink}, ale generuje odkazy nad aktuální komponentou.
Podmínky {if ?} ... {/if}
Pro podmíněné vykreslování určitých částí šablon lze použít podmínky ve tvaru {if ?} ... {elseif ?} ... {else} ... {/if} .
Foreach cyklus
Foreach cyklus se chová jako běžný foreach v php s několika rozšířeními.
Uvnitř cyklu je inicializovaná proměnná $iterator, díky které můžete zjistit některé jinak těžko zjistitelné údaje o právě probíhajícím cyklu.
Metody proměnné $iterator:
isFirst()– prochází se cyklem poprvé?isLast()– jde o poslední průchod?getCounter()– čítač průchodů cyklem počítaný od jedničky.isOdd()– jde o lichý průchod?isEven()– jde o sudý průchod?
Příklad:
{foreach $rows as $row}
{if $iterator->isFirst()}
<table>
{/if}
<tr id="row-{$iterator->getCounter()}">
<td>{$row->name}</td>
<td>{$row->email}</td>
</tr>
{if $iterator->isLast()}
</table>
{/if}
{/foreach}
Vkládání souborů
Nelze vytvářet vlastní šablony .phtml, pouze upravovat stávající.
Vkládání souborů se provádí makrem {include file.phtml}. Vložený soubor má k dispozici globální proměnné aktuální šablony ($template->getParams()) a parametry, které mu při volání předáme.
{include userProfile.phtml, id => 12, name => 'John Smith'}
Deklarace proměnných
Někdy může být vhodné deklarovat proměnnou až v šabloně. Pro tyto účely se používá makro {var} (existuje alias {assign} ) za použití následující syntaxe:
{var name => 'John Smith'}
{var age => 27}
{* Vícenásobná deklarace *}
{var name => 'John Smith', age => 27}
V případě, že chceme deklarovat promměnou pouze v případě, že dosud deklarovaná není, tak použijeme makro {default}.
{default page => 1} {* Lze zapsat také jako {if !isset($page)}{var page => 1}{/if} *}
Vykreslování komponent {control ...}
Značka {control} slouží pro snadné vykreslování komponent. Pro lepší pochopení je dobré vědět, jak se tato značka přeloží do PHP.
{control leftMenu}
Lze použít i volání s parametry, které se předají render metodám, například:
{control cartControl:small, $maxItems}
Alternativní zápis pomocí n:atributů
Párová makra lze zapisovat také alternativní syntaxí pomocí tzv. n:atributů.
| Zápis pomocí n:atributů | Standardní zápis |
<div class="login" n:if="$cond"> |
{if $cond} |
<ul> |
<ul> |
<p><strong n:tag-if="$strong">...</strong></p> |
<p>{if $strong}<strong>{/if}...{if $strong}</strong>{/if}</p> |
<ul n:inner-foreach="$items as $item"> |
<ul> |
Podpora helperů
Latte filter podporuje snadné volání helperů za použití této syntaxe:
<h1>{$heading|upper}</h1>
Je možno zřetězit více helperů (resp. modifikátorů):
<h1>{$heading|lower|capitalize}</h1>
Vykonají se v pořadí od levého k pravému.
Další parametry funkce helperu se zadávají za jménem helperu oddělené dvojtečkami.
<a href="...">{$linkText|truncate:20}</a>
Pokročilá makra
| Zápis v Latte | PHP ekvivalent nebo stručný význam |
|---|---|
{=expression} |
<?php echo htmlSpecialChars(expression) ?> |
{!=expression} |
<?php echo expression ?> |
{_expression} |
vypíše překlad s escapováním |
{!_expression} |
vypíše překlad bez escapování |
{ifCurrent} |
speciální případ {if} pro aktivní odkaz |
{snippet ?} ... {/snippet} |
control snippet |
{attr ?} |
usnadňuje zápis atributů html značek |
{block ?} ... {/block} |
block |
{control ...} |
připraví komponentu k vykreslení |
{_expression} a {!_expression}
Tyto značky umožňují překládání v šablonách.
Značka {block}
V šabloně je možné vložit blok pomocí příkazu include.
{include block_name}
Značka {snippet}
Snippety se používají při práci s Ajaxem pro označení logické oblasti na stránce, která má být jako celek v případě Ajaxového požadavku překreslena.
Značka {ifCurrent}
Značka {ifCurrent destination} pomáhá zjistit, zda-li je cíl odkazu shodný s aktuální stránkou. Pokud odkaz směřuje na stránku, která je zrovna zobrazena, můžeme ho například jinak nastylovat a podobně. Trik je v tom, že při generování odkazu se detekuje, jestli odkaz míří na aktuální stránku.
<!-- příklady použití -->
<a href="{link edit, 10}">edituj</a>
<ul class="menu">
<li><a href="{link Default:default}">...</a></li>
<li><a href="{link}">...</a></li>
...
<li {ifCurrent Default:default}class="current"{/ifCurrent}><a href="{link Default:default}">...</a></li>
<!-- rozšíření scope -->
<li {ifCurrent Default:*}class="current"{/ifCurrent}><a href="{link Default:default}">...</a></li>
</ul>
<!-- znegování -->
{ifCurrent Admin:login}{else}<a href="{link Admin:login}">Přihlašte se!</a>{/ifCurrent}
Přehled standardních helperů
| Makro | Ekvivalent funkce v PHP | Popis |
|---|---|---|
lower |
strtolower() | Převede text na malá písmenka. |
upper |
strtoupper() | Převede text na velká písmenka. |
capitalize |
Převede text na malá písmenka, přičemž první písmeno v každém slově bude velké. | |
webalize |
Převede text do tvaru „SEO friendly URL“. | |
date |
Formátování data. | |
bytes |
Lidsky přívětivé vyjádření velikost v bajtech. | |
truncate |
Zkrátí řetězec na požadovaný počet znaků. | |
trim |
trim() | Odstraní bílé znaky ze začátku a konce řetězce. |
strip |
Odstraní bílé znaky (mezery). | |
stripTags |
strip_tags() | Odstraní HTML tagy. |
nl2br |
nl2br() | Zamění odřádkování za <br />. |
translate |
Přeloží text do jiného jazyku. | |
replace |
str_replace() | |
replaceRe |
preg_replace() | |
length |
Vrací délku řetězce. | |
substr |
iconv_substr() | |
repeat |
str_repeat() | |
implode |
implode() | |
number |
number_format() | |
escape |
Escapuje HTML znaky. | |
escapeUrl |
rawurlencode() |
Truncate
Ořízne řetězec na maximální délku a zachová celá slova, je-li to možné. Na konec oříznutého textu se přidá trojtečka, což lze změnit třetím nepovinným parametrem.
Příklad použití v šabloně (s filtrem Latte):
{var title => 'Řekněte, jak se máte?' }
{$title|truncate:5} <!-- Řekn… -->
{$title|truncate:20} <!-- Řekněte, jak se… -->
{$title|truncate:30} <!-- Řekněte, jak se máte? -->
Bytes
Převádí velikosti souborů v bajtech do lidsky čitelné podoby.
Příklad použití v šabloně:
{$size|bytes} <!-- 0 B, 10 B nebo 1.25 GB, ... -->
Lower, upper a capitalize
{var s => "Dobrý den"}
{$s|lower} <!-- dobrý den -->
{$s|upper} <!-- DOBRÝ DEN -->
{$s|capitalize} <!-- Dobrý Den -->
Date
Vlastní formát datumu. Volá php funkci strftime, používají se zde tedy stejné zástupné znaky a pro helper platí stejná omezení jako pro tuto funkci. Helper zpracovává proměnné typu int (timestamp), string nebo instanci třídy DateTime.
{$today|date:'%d.%m.%Y'}
Další funkce
PHP funkce které lze použít v podmínkách nebo v cyklech:
isset()is_null()empty()is_numeric()date()strtotime()min()max()ceil()rand()intval()is_array()in_array()reset()count()strlen()strpos()str_replace()trim()
Ajax a zavináče v kódu
Část kódu, která se aktualizuje Ajaxem, je obalená v tagu {snippet}{/snippet}.
Podmínky, cykly, controls a includes obalující tag {snippet}{/snippet} musí na svém začátku obsahovat znak @.
Ukázka tagu {snippet} obaleného cyklem if:
@{if ....}
{snippet}.....{/snippet}
@{/if}
Definice proměnné
Pokud se definuje proměnná v šabloně mimo snippet a pak se použije uvnitř prvku začínajícího zavináčem, pak tato definice musí také začínat znakem @.
Ukázka této definice proměnné:
@{var $promenna 'hodnota'}
Pokud používáte n:atributy, nelze je použít v ajaxu, protože před ně nelze dát znak @.
Widgety
Grafické šablony verze 3.9 a starší umožňovaly předat do widgetu hodnoty pomocí atributu, např.:
{control contactMenu xxx, maxLevelsCount => 2}
Od grafických šablon verzo 4.0 se widgety přejmenovaly na control, kde je potřeba atributy předávat proměnnou. Např.:
templateOptions => extend($templateOptions, ['number' => 1])
