SMARTY – funkce

29. ledna 2004

•

Tento článek věnujeme funkcím v šablonách. Možnosti využití funkcí v šablonách jsou široké, ale nejčastěji je využijeme při formátování výstupu skriptů nebo při zpřehledňování HTML kódu. SMARTY obsahuje ve standardním balíku několik desítek funkcí, z nichž si ovšem ukážeme jen některé představíme.

Funkce lze rozdělit na dvě skupiny – uživatelské, jejichž kód najdeme v adresáři plugins (respektive v adresáři nastaveném v proměnné $plugins_dir třídy Smarty) a funkce vestavěné, jejichž kód je „natvrdo“ zakomponován do tříd Smarty, popřípadě Smarty_Compile.

Vestavěné funkce

Vestavěné funkce, na rozdíl od uživatelských, nevytváří ani neformátují obsah výsledné stránky, ale slouží především ke vkládání souborů (php skriptů, šablon i konfiguračních souborů).

capture

Použitím funkce capture dosáhneme toho, že část šablony, která je uzavřena mezi tagy capture, bude uložena do proměnné definované atributem name. Takto „odchycený“ text můžeme následně umístit na libovolné místo šablony. K tomu postačí vložit proměnnou $smarty.capture.hodnota_atributu_name na požadované místo šablony.

V následujícím příkladu si ukážeme jeden ze způsobů, jak funkci capture využít. Předpokládejme, že vytváříme internetový obchod. Jako každý správný obchodník budeme chtít čas od času pořádat spotřebitelské soutěže. Na každé stránce pak budeme chtít zobrazit upoutávku na právě probíhající soutěž.

Jak k tomu využít SMARTY? Na libovolné místo v šabloně vložíme část kódu, který se bude starat o vytvoření malé upoutávky. Abychom si usnadnili práci, vložíme do šablony (prostřednictvím funkce assign, viz níže) také proměnou, jejíž hodnota bude určovat, zda se má upoutávka zobrazit:

…
{* boolean hodnota urcijici, zda se ma upoutavka zobrazit *}
{assign var=“showAd“ value=true}

Nyní do šablony vložíme, mezi tagy capture, text upoutávky:

{if $showAd}
    {capture name=ad}
        Kupte si naše nové krásné auto.<br>
        Za nízkou cenu a bez volantu!<br>
        <strong>Nekupujte zajíce v pytli. Nakupujte u nás!</strong>
    {/capture}
{/if}

Posledním krokem je vložení „odchyceného“ obsahu na to správné místo v šabloně:

{if $showAd}
<!– Zde je upoutavka –>
Upoutávka týdne:{$smarty.capture.ad}
{/if}

config_load

Příkaz config_load slouží k načtení konfiguračního souboru. Tomuto příkazu se vrátíme v některém z následujících článků.

include

Další důležitou funkcí je include, která slouží ke vkládání souborů šablon. Pomocí tohoto příkazu lze, obdobně jako v PHP příkazy include a require, rozčlenit prezentaci do několika částí.

Povinným parametrem funkce include je atribut file, který obsahuje název vkládaného souboru. Dalším volitelným parametrem je assign obsahující název proměnné, do které bude obsah vkládané šablony uložen místo toho, aby byl zobrazen. Prostřednictvím atributů příkazu include lze také vkládané šabloně předat nejen hodnoty, ale i názvy proměnných. Název proměnné je použit jako atribut funkce include a hodnota proměnné je hodnotou atributu.

Nyní můžeme upravit náš předchozí příklad. Část kódu vytvářející upoutávku uložíme do samostatného souboru (advert.tpl). Ten pak budeme vkládat do hlavní šablony prostřednictvím příkazu include.

Soubor advert.tpl:

{if $showAd}
    Kupte si naše nové krásné auto.<br>
    Za nízkou cenu a bez volantu!<br>
    <strong>Nekupujte zajíce v pytli. Nakupujte u nás!</strong>
{/if}

Obsah šablony:

{include assign=“ad“ file=“advert.tpl“ showAd=true}
{if $ad ne „“}
<!– Zde je upoutavka –>
Upoutávka týdne:{$ad}
{/if}

Příkaz include v našem příkladě obsahuje atributy file a assign. Šabloně advert.tpl je také, prostřednictvím příkazu include, předána proměnná showAd určující, zda se má upoutávka zobrazit. Všimněte si, že proměnou $showAd nemusíme v souboru advert.tpl vytvářet příkazem assign, což bychom museli udělat, pokud bychom ji nepředali šabloně jako atribut funkce include.

include_php

Obdobou předchozího příkazu je include_php, sloužící k vkládání zdrojového kódu skriptu přímo do šablony. Kromě atributů file a assign, je možné použít s tímto příkazem také boolean atribut once označující, zda má být zdrojový kód do šablony vložen pouze jednou nebo při každém volání tohoto příkazu. Příkaz include_php použijete často tehdy, pokud budete chtít šabloně předat hodnoty, které jsou uloženy v databázi, nebo které jsou výsledkem vámi naprogramovaného algoritmu.

insert

Příkaz insert se chová stejně jako příkaz include (má také stejné atributy). Jediný rozdíl mezi těmito příkazy je způsob chování v případě použití cache systému, který je spolu se SMARTY k dispozici. Vkládaná šablona nebude, v případě použití příkazu insert, uložena do dočasné paměti a její obsah tak bude načten při každém vyvolání příkazu insert. Opačně se chová příkaz include, při jehož použití bude vkládaná šablona uložena do cache paměti. Více si o chache řekneme v některém z příštích článků.

php

Příkaz php slouží, jak název napovídá, k vložení PHP kódu přímo do šablony. Tento příkaz by měl být používán jen zřídka, protože tak dochází ke snížení přehlednosti šablon a může dojít i k nechtěným chybám při úpravě dokumentu. Pokud nutně potřebujete do šablony vložit PHP kód, pak použijte raději příkaz include_php.

strip

Obdobou modifikátoru strip je i stejnojmenný příkaz, který odstraní mezery a nové řádky z označené části HTML kódu. Jedná se o velmi užitečnou funkci, která umožňuje zachovat přehlednost kódu šablony a zároveň snížit velikost výsledného souboru.

{* ukazka tabulky *}
{strip}
    <table width=“760″ align=“center“ border=“1″ cellspacing=“0″ cellpadding=“7″ style=“border-collapse: collapse“>
    <tr>
        <td valign=“top“ colspan=“3″>Hlavička</td>
    </tr>
    <tr>
        <td valign=“top“ rowspan=“2″ width=“150″>Levý sloupec</td>
        <td valign=“top“ width=“500″>Obsah</td>
        <td valign=“top“ rowspan=“2″ width=“110″>Pravý sloupec</td>
    </tr>
    <tr>
        <td valign=“top“>Patička</td>
    </tr>
    </table>
{/strip}

Výsledek funkce strip:

<table width=“760″ align=“center“ border=“1″ cellspacing=“0″ cellpadding=“7″ style=“border-collapse: collapse“><tr><td valign=“top“ colspan=“3″>Hlavička</td></tr><tr><td valign=“top“ rowspan=“2″ width=“150″>Levý sloupec</td><td valign=“top“ width=“500″>Obsah</td><td valign=“top“ rowspan=“2″ width=“110″>Pravý sloupec</td></tr><tr><td valign=“top“>Patička</td></tr></table>

Uživatelské funkce

Jak jsme si již řekli v předchozích článcích, můžeme vytvářet a v šablonách používat libovolné uživatelské funkce, které pro svůj konkrétní projekt potřebujeme. V distribuci SMARTY najdeme bezmála dvacet nejčastěji používaných funkcí, z nichž si v krátkosti uvedeme ty nejdůležitější.

assign

Příkaz assign slouží k vytvoření proměnné uvnitř šablony a k přiřazení hodnoty této proměnné. Atributy příkazu jsou var (název proměnné) a value (hodnota proměnné).

cycle

Cycle je užitečnou funkcí, zvláště při vytváření tabulek. Jediným povinným atributem je values, obsahující pole nebo hodnoty oddělené čárkami (oddělovač může být změněn atributem delimiter). Funkci cycle je možné použít pouze uvnitř cyklu (foreach nebo section), kde zajistí cyklické střídání hodnot obsažených v atributu values.

Pro pochopení fungování této funkce použijeme modifikovaný příklad z předchozího článku. Abychom zlepšili čitelnost tabulky, použijeme různá pozadí lichých a sudých řádků tabulky. Na místo definice stylu pozadí řádků vložíme funkci cycle s atributem values obsahující pozadí pro lichý (White) a sudý (Silver) řádek:

{section name=zbozi loop=$pole}
    {if $smarty.section.zbozi.first}
        <table>
    {/if}
    {* stridani hodnot barvy pozadi *}
    <tr style=“background-color: {cycle values=“White, Silver“} ;“>
            <td>{$pole[zbozi]}</td>
    </tr>
    {if $smarty.section.zbozi.last}
        </table>
    {/if}
{/section}

Výsledkem tohoto kódu bude například tato přehledná tabulka.

mailto

Jak název napovídá, jedná se o funkci vytvářející odkaz na e-mailovou adresu. Jediným povinným atributem je adress , jehož hodnotou je, jak jinak, e-mailová adresa. Atributem, který stojí za povšimnutí, je encode, sloužící k zakódování e-mailové adresy tak, aby jí nebylo možno stáhnout ze stránek pomocí automatických nástrojů.

{mailto address=“ja@doma.com“}
{mailto address=“ja@doma.com“ text=“napiste mi“}
{mailto address=“ja@doma.com“ encode=“javascript“}
{mailto address=“ja@doma.com“ encode=“hex“}

Výsledek:

<a href=“mailto:ja@doma.com“ >ja@doma.com</a>
<a href=“mailto:ja@doma.com“ >napiste mi</a>
<SCRIPT language=“javascript“>%64%6f%63%75%6d%65%6e%74%2e%77%72%69%74%65%28%27%3c%61%20%68%72%65%66%3d%22%6d%61%69%6c%74%6f%3a%6a%61%40%64%6f%6d%61%2e%63%6f%6d%22%20%3e%6a%61%40%64%6f%6d%61%2e%63%6f%6d%3c%2f%61%3e%27%29%3b‘))</SCRIPT>
<a href=“mailto:%6d%65@%64%6f%6d%61%69%6e.%63%6f%6d“ >me@d&
#x6f;main.com</a>

Rodina funkcí html_

Sedm funkcí, začínajících na html_ (konkrétně: html_select_date, html_select_time, html_image, html_checkboxes, html_radios, html_options a html_table), slouží k vytváření HTML elementů , především formulářových prvků. Při jejich použití je jim prostřednictvím atributu (nejčastěji se tento atribut jmenuje values) předáno pole hodnot, ze kterých je následně vytvořen zvolený prvek HTML stránky. Většina těchto funkcí má mnoho atributů a proto se jimi zde nebudeme detailněji zabývat. Jejich kompletní výpis najdete v dokumentaci systému SMARTY.

Textformat

Funkce textformat je zaměřena především na formátování jednotlivých odstavců textu. Můžeme například nastavit šířku (atribut wrap ), odsazení první řádky (atribut indent_first ), odsazení všech řádků (atribut indent ) a podobně.

Novinky ve Smarty 2.6.0

V polovině listopadu roku 2003 byla uvolněna nová verze šablonovacího systému SMARTY. Velkou změnou prošla vnitřní architektura systému, který je z větší části modularizovaný. Výsledkem této úpravy je vznik nového podadresáře core, obsahujícího interní funkce, které byly přesunuty z třídy Smarty do formy pluginů, čímž se hlavní třída Smarty zmenšila o celou jednu třetinu.

Druhou podstatnou změnou v nové verzi je možnost používat jednoduché matematické výrazy přímo v šablonách bez nutnosti použití funkce math. Při psaní těchto výrazů se musíte vyvarovat mezer mezi operátory a proměnnými. To samé také platí bohužel i o závorkách.

…
{assign var=“p“ value=15}
{assign var=“q“ value=3}
value: {$p*$q-2+$q} <br>
…

Úprav se dočkala také třída Config_File, která má na starosti zpracování a kompilaci konfiguračních souborů.

Pozn. aut.: Krátce před dokončením tohoto článku vyšla další nová verze Smarty 2.6.1, opravující především některé drobnější chyby z předcházející verze.