Smarty template engine - 7 (speciální funkce - 1)

18. 4. 2008 | Tomáš Kavalek

Články - Smarty template engine - 7 (speciální funkce - 1)  

Po delší přestávce se opět vrátíme k seriálu o šablonovacím systému Smarty. Dnešním dílem se začneme seznamovat s tzv. speciálními funkcemi.

Obsah

• Úvod
  • assign
  • counter
  • cycle
  • debug
  • eval
  • fetch
  • html_checkboxes
  • html_image
• Závěr

Úvod

Tímto dílem započneme seznamování s tzv. speciálními funkcemi (v originále custom functions, což se mi opravdu hodně těžko překládá, ale už jsem se na českém Internetu setkal s překladem speciální funkce, budu ho tedy i já používat). V podstatě se jedná o již hotové pluginy (těch si můžeme do Smarty doprogramovat, kolik chceme - viz další díly), které můžeme ve svých šablonách používat. Zdrojové kódy všech popisovaných funkcí (resp. pluginů) nalezneme v adresáři Smarty, např. smarty/libs/plugins/.

assign

Funkce assign slouží k přiřazování hodnot proměnným v šablonách. Funkce má dva povinné parametry; prvním z ních je var, kterému přiřazujeme název proměnné, které má být přiřazena hodnota. Druhým parametrem je tedy value, obsahující hodnotu, kterou chceme přiřadit proměnné.

Ukázka použítí funkce assign v šabloně:

{assign var="jmeno" value="Martin"}

Hodnota promenne $jmeno je {$jmeno}.

Dostaneme výstup:

Hodnota promenne $jmeno je Martin.

Použití funkce assign může být mnohem komplexnější, např. použitím matematiky (výrazy však musejí být uzavřeny do zpětných apostrofů, aby šablonovací stroj Smarty nejprve provedl výpočet a až poté přiřazení):

{assign var="a" value=10}
{assign var="obvod" value=`$a*4`}

Obvod ctverce o strane {$a} je {$obvod}.

Dostaneme výstup:

Obvod ctverce o strane 10 je 40.

counter

Funkce counter slouží jako počítadlo. Při prvním zavolání funkce nastavíme požadované vlastnosti, podle nichž při každém dalším zavolání vypisuje hodnotu. Abychom mohli používat několik na sobě nezávislých počítadel, je potřeba si každé počítadlo pojmenovat. K tomu nám slouží parametr name. Dalšími klíčovými parametry jsou start a skip. První určuje inicializační hodnotu počítadla a druhý hodnotu kroku, tedy hodnotu, jež bude při každém zavolání přičtena k hodnotě předchozí. Pro ovlivňování směru kroku slouží parametr direction, který může nabývat hodnot up nebo down - význam je zřejmý. Výpis hodnoty počítadla můžeme explicitně zakázat parametrem print, resp. přiřazením hodnoty false. Posledním parametrem, který se nám může hodit, je assign, jež určuje, do které proměnné v šabloně bude namísto vypsání obsah počítadla uložen.

Ukázka použití různých variant funkce counter v šabloně:

{* Inicializace pocitadla C1 s potlacenim vypisu                            *}
{counter name="c1" start=0 skip=5 print=false}
<br />
{* Inicializace pocitadla C2 bez potlacenim vypisu                          *}
{counter name="c2" start=100 skip=5 direction="down"}
<br />
{* Vypis tri hodnot pocitadla C1                                            *}
{counter name="c1"} {counter name="c1"} {counter name="c1"}
<br />
{* Vypis tri hodnot pocitadla C2                                            *}
{counter name="c2"} {counter name="c2"} {counter name="c2"}
<br />
{* Prirazeni hodnoty pocitadla C2 do promenne a nasledny vypis              *}
{counter name="c2" assign="counter_c2"}
Hodnota c2: {$counter_c2}

Dostaneme výstup:

<br />
100
<br />
5 10 15
<br />
95 90 85
<br />

Hodnota c2: 80

cycle

Funkce cycle slouží k cyklení hodnot předaných proměnnou, tzn. že při každém jejím zavolání je použita další hodnota v pořadí. Když se dostane funkce na konec seznamu hodnot, začne od začátku. Takto lze například měnit systematicky barvy řádku v tabulce. Stejně jako u funkce counter je možné cyklení pojmenovat; k tomu slouží, stejně jako v předchozím případě, parametr name - opět nám to umožní použít nezávisle na sobě několik cyklení. Hodnoty, které mají být cyklovány, předáváme funkci pomocí parametru values. Implicitně se hodnoty oddělují čárkou, chceme-li použít jiný oddělovač, musíme ho definovat pomocí delimiter. Parametry assign a print mají stejný význam jako u funkce counter. Chceme-li z jakéhokoliv důvodu vypsat hodnotu vícekrát, použijeme parametr advance s hodnotou false, čímž nedovolíme funkci přejít na další položku v seznamu hodnot. Posledním možným parametrem je reset, pomocí kterého se cyklus nastaví na první hodnotu seznamu hodnot.

Ukázka jednoduchého použítí funkce cycle v šabloně:

<table>
{* Vypiseme tabulku o deseti radcich s cisly od 0 do 9
   a budeme stridat tri barvy pozadi *}
{section name="c1" start="0" loop="10" step="1"}
<tr style="background-color: {cycle delimiter=" " values="#FF0000 #00FF00 #0000FF"}">
<td>{$smarty.section.c1.index}</td>
</tr> 
{/section}
</table>

Dostaneme výstup:

<table>
<tr style="background-color: #FF0000">
<td>0</td>
</tr> 
<tr style="background-color: #00FF00">
<td>1</td>
</tr> 
<tr style="background-color: #0000FF">
<td>2</td>
</tr> 
<tr style="background-color: #FF0000">
<td>3</td>
</tr> 
<tr style="background-color: #00FF00">
<td>4</td>
</tr> 
<tr style="background-color: #0000FF">
<td>5</td>
</tr> 
<tr style="background-color: #FF0000">
<td>6</td>
</tr> 
<tr style="background-color: #00FF00">
<td>7</td>
</tr> 
<tr style="background-color: #0000FF">
<td>8</td>
</tr> 
<tr style="background-color: #FF0000">
<td>9</td>
</tr> 
</table>

debug

Funkce pro ladění. Probereme později, až se budeme zabývat tvorbou vlastních pluginů a laděním šablon.

eval

Funkce eval slouží k vyhodnocování obsahu proměnných, jako kdyby se jednalo o šablonu. Obsah proměnné je tedy zpracován jako šablona a výsledek je vložen do šablony stávající. Funkce pracuje na principu PHP funkce stejného jména, tedy eval. Funkce má dva parametry, jeden z nich je povinný. Povinným parametrem je samozřejmě var, tedy proměnná, které se má zpracovat - může se jednat jak o proměnnou šablony, tak i konfigurační proměnnou. Druhým parametrem je assign, tedy proměnná, do které má být uložen výsledek. Tuto možnost využijeme tehdy, pokud nechceme výsledek vyhodnocení ihned vypsat do šablony, ale dále s ním pracovat nebo ho použít jinde.

Ukázka různých použítí funkce eval v šabloně:

{* Obsah souboru eval_conf.conf                                             *}
serverName = ABC_Linuxu
articleType = Smarty Template Engine
userInfo = Serial #articleType# na serveru #serverName# od autora {$author}

{* Priradime promenne foo_1 hodnotu                                         *}
{assign var="foo_1" value="Petr Novák"}
{* Priradime promenne foo_2 hodnotu                                         *}
{assign var="foo_2" value="Pavel Novotný"}
{* Promenne k naslednemu zpracovani funkci eval                             *}
{assign var="foo_eval_1" value="Jméno: $foo_1"}
{assign var="foo_eval_2" value="Jméno: $foo_2"}
{* Vyhodnoceni a ulozeni do promenne, resp. okamzity vypis                  *}
{eval var=$foo_eval_1 assign="foo_result"}
{eval var=$foo_eval_2}<br />
{$foo_result}
{* Protoze nebylo potreba konfiguracniho souboru, slo by to i bez eval      *}
{$foo_eval_1}<br />
{$foo_eval_2}
{* Nacteme si konfiguracni soubor - eval bude nyni nutny                    *}
{config_load file="eval_conf.conf"}
{assign var="author" value="Tomáše Kavalka"}
{eval var=#userInfo#}
{* Dukaz toho, ze by to bez eval neslo                                      *}
{#userInfo#}

Dostaneme výstup:

Jméno: Pavel Novotný<br />
Jméno: Petr Novák<br />
Serial Smarty Template Engine na serveru ABC_Linuxu od autora Tomáše Kavalka<br />
Serial {#articleType#} na serveru {#serverName#} od autora {$author}

fetch

Funkce fetch slouží k načtení obsahu souboru a jeho zobrazení, resp. uložení do proměnné. Načítát lze z lokálního souborového systému nebo přes http a ftp protokol. Povinným parametrem je file, jenž udává cestu k souboru, který chceme vložit. Nepovinným parametrem je assing, tedy proměnná, do které má být obsah uložen, namísto zobrazení.

Ukázka různých použítí funkce fetch v šabloně:

{* Vlozeni zdrojoveho kodu skriptu v JS z lokalniho souboroveho systemu      *}
<script type="text/javascript">
{fetch file="/path/to/file/clock.js"}
</script> 
{* Vlozeni jine HTML stranky do sablony                                      *}
{fetch file="http://www.example.com/path/to/file"}
{* Vlozeni textu ze souboru pres FTP                                         *}
{fetch file="ftp://user:password@ftp.example.com/path/to/file.txt"}
{* Vlozeni textu ze souboru pres FTP - s vyuzitim promennych                 *}
{fetch file="ftp://`$user`:`$password`@`$server`/`$path`"}
{* Vlozeni obsahu souboru do promenne a nasledne zpracovani                  *}
{fetch file="http://www.example.com/sun-info/" assign="sun-info"}
{if $sun-info ne ""}
<div id="sun-info">{$sun-info}>/div>
{/if}

Ukázka výstupu není nutná a zároveň by byla obtížná, protože veškeré lokace souboru jsou smyšlené.

html_checkboxes

Funkce html_checkboxes slouží k zjednodušení práce při zobrazování checkboxů. Jak jsme si již zvykli, i tato funkce disponuje parametrem name, díky kterému můžeme specifikovat jméno, pomocí něhož pak přistupujeme k checkboxům - uvedené jméno bude použito v (X)HTML výstupu jako parametr name u checkboxu. Dalším parametrem je values, což je jednorozměrné pole obsahující hodnoty checkboxů (v (X)HTML parametr value). K zobrazení popisků u jednotlivých checkboxů slouží parametr output, který také očekává pole. Chceme-li již při zobrazení šablony některé checkboxy zobrazit jako zaškrtnuté, využijeme parametr selected. Tomu předáme buď název checkboxu, který má být zaškrtnut, nebo pole názvů, má-li být checkboxů označeno několik. K nastavení oddělovače jednotlivých checkboxů slouží parametr separator. Můžeme oddělovat např. mezerou, zalomením řádku, atd. Někteří webdesignéři přiřazují k checkboxům tag label, což zajišťuje možnost pracovat s checkboxy i tak, že lze klikat na popisky, ne přímo na checkboxy. Chceme-li této možnosti využít, přiřadíme parametru labels hodnotu true. Pokud dáváme přednost uložení do proměnné namísto okamžitého výstupu, využijeme již známého parametru assign. Nyní se dostáváme k poslednímu parametru, tím je options. Tento parametr nahrazuje použití parametrů values a output, a to v tom případě, že nechceme předávat funkci dvě pole, ale chceme předat jedno pole asociativní, což je v některých případech lepší, minimálně přehlednější. Použijeme-li jako název parametru cokoliv, co jsem v textu nezmínil, dojde k jednoduchému použití kombinace parametr="hodnota" - ve výsledném (X)HTML to bude parametr tagu input. Viz druhá ukázka a použití stylování přes class.

Ukázka různých použití funkce html_checkboxes v šabloně - s použitím values a output:

<?php
/* PHP soubor                                                              */
$smarty->assign("items_ids", array(1, 2, 3, 4));
$smarty->assign("items_titles", array(
				"Debian",
				"Slax",
				"Red Hat",
				"Ubuntu"));
$smarty->assign("selected_item", 2);
?>

{html_checkboxes name="items" values=$items_ids output=$items_titles
 selected=$selected_item  separator="<br />"}

Ukázka různých použití funkce html_checkboxes v šabloně - s použitím options:

<?php
/* PHP soubor                                                              */
$smarty->assign("items_checkboxes", array(
					1 => "Debian",
					2 => "Slax",
					3 => "Red Hat",
					4 => "Ubuntu"));
$smarty->assign("selected_item", 2);
?>

{html_checkboxes name="items" options=$items_checkboxes selected=$selected_item 
 separator="<br />" class="items-checkboxes"}

V obou případech dostaneme shodný výstup - jediný rozdíl bude v druhém případě, u všech elementů input bude class="items-checkboxes":

<label><input type="checkbox" name="items[]" value="1" />Debian</label><br />
<label><input type="checkbox" name="items[]" value="2" checked="checked" />Slax</label><br />
<label><input type="checkbox" name="items[]" value="3" />Red Hat</label><br />
<label><input type="checkbox" name="items[]" value="4" />Ubuntu</label><br />

html_image

Funkce html_image slouží k zjednodušení práce při zobrazování obrázků. Jediným povinným a důležitým parametrem je file, tedy cesta k souboru s obrázkem. Ostatní parametry jsou nepovinné. Parametry height a width použijeme pouze tehdy, chceme-li změnit velikost obrázku, v opačném případě se velikost doplní automaticky. Pro dodržení (X)HTML standardu je vhodné využít parametr alt, pomocí něhož doplníme obrázku alternativní text. Chceme-li zároveň použít obrázek jako odkaz, předáme parametru href cílovou adresu - obrázek bude obklopen tagem a. Cesta k obrázkům začíná vždy v $_ENV["DOCUMENT_ROOT"], není-li parametrem basedir uvedeno jinak. Posledním parametrm je path_prefix, pomocí něhož lze upravit cestu k obrázku prefixem. Použijeme-li jako název parametru cokoliv, co nebylo zmíněno, platí stejná pravidla, jako u html_checkboxes.

Ukázka různých použítí funkce html_image v šabloně:

{html_image file="foo_1.jpg" href="http://www.example.com" class="extern-link"}
{html_image file="foo_2.jpg" alt="Foo text" border="1"}

Dostaneme výstup:

<a href="http://www.example.com"><img src="foo_1.jpg"
 alt="" width="450" height="600" class="extern-link" /></a>
<img src="foo_2.jpg" alt="Foo text" width="450" height="600" border="1" />

Závěr

V příštím díle budeme pokračovat v seznamování se speciálními funkcemi (custom functions). Čeká nás html_options, html_radios, html_select_date, html_select_time, html_table, mailto, math, popup a textformat.

Diskuse k tomuto článku

[Altaran]

docela by me zajimalo jak je na tom s narocnosti html_image pokud se pouzije vicekrat (100+) po sobe - nacte napred gd info(ty rozmery napr) o vsech do pole a pak to prirazuje, nebo si to incializuje dycky znovu a nacita pri kazdym spusteni??

[Toman]

Dovolil bych si tvrdit, ze pokud je v sablone napr. toto:

{html_image file="foo1.png"}
{html_image file="foo2.png"}
{html_image file="foo3.png"}

tak se pro kazdy obrazek zavola getimagesize, tedy kazdy plugin pracuje oddelene a vraci (X)HTML kod. Jedine cim se setri cas je cacheovani. I tak si ale myslim, ze pristoupit k vyse uvedenym sto obrazkum pomoci getimagesize nezabere az tolik serveroveho casu.

[huhu]

kazdopadne nieje problem to napisat, raz spustit a pozriet preparsovany php zdrojak :)