Dokumentace š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.

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">
<p>User {$name}</p>
...
</div>
{if $cond}
<div class="login">
<p>User {$name}</p>
...
</div>
{/if}
<ul>
<li n:foreach="$items as $item">{$item}</li>
</ul>
<ul>
{foreach $items as $item}
<li>{$item}</li>
{/foreach}
</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">
<li>A {$item}</li>
<li>B {$item}</li>
</ul>
<ul>
{foreach $items as $item}
<li>A {$item}</li>
<li>B {$item}</li>
{/foreach}
</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čílá 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 @.

Na této stránce
Zpět

Další zdroje informací

Facebook poradna

Výměna zkušeností, rady a tipy mezi provozovateli e-shopů na systému UPgates.

Přejít do poradny

Akademie

Získejte znalosti od našich specialistů na marketing, obchod, právo a podnikání.

Přejít do akademie

Novinky z Blogu

Co nového jsme pro vás připravili nebo chystáme najdete na blogu.

Přejít do blogu

Nepodařilo se Vám najít tu správnou odpověď?

Kontaktujte naši technickou podporu, která je tu pro vás od pondělí do pátku 8:00 až 16:00 hod.

Zákaznická podpora