Smarty, šablonovací systém - 4 (vestavěné funkce 1)

14. 2. 2007 | Tomáš Kavalek | Návody | 11200×

V dnešním článku si projdeme některé vestavěné funkce Smarty (capture, config_load, foreach a foreachelse). Ty, které projít nezvládneme, probereme v dalším díle.

Obsah

• Úvod
• capture
• config_load
• foreach a foreachelse
  • index
  • iteration
  • first a last
  • total
• Závěr

Úvod

Vlastnosti a možnosti vestavěných funkcí jsou velice rozsáhlé, proto bych hned v úvodu rád zdůraznil, že část věnovaná vestavěným funkcím bude rozdělena na více dílů. Zatím předpokládám, že se bude jednat o tři díly. Pokud však narazím na něco, co bude vyžadovat detailnější rozbor a popis, může se stát, že dílů bude víc. Slibuji však, že se budu snažit tuto kapitolu zbytečně nenatahovat, aby nevznikl jakýkoliv odpor k Smarty ;-).

capture

Místo toho, aby došlo k okamžitému zobrazení šablony, je její výstup, resp. vše mezi tagy {capture} a {/capture}, uloženo do proměnné. Tato funkce je vhodná zejména v případech, kdy chceme odladit chyby, které by mohly být způsobeny chybějící šablonou, nevhodným výstupem pluginu (viz další kapitoly) apod. Funkce capture umožňuje použití dvou parametrů, oba jsou volitelné. První parametrem je name, což je identifikátor obsahu „zachyceného“ funkcí capture. Pomocí toho identifikátoru budeme moci k obsahu přistupovat přes nám již známou rezervovanou proměnnou $smarty. Chceme-li však „zachycený“ obsah uložit přímo do nějaké proměnné, použijeme parametr assign se jménem proměnné. Jako obvykle a i u následujících funkcí nám nejvíce řekne ukázkový kód. V ukázce mírně předběhneme, bude totiž použito funkcí if a include.

{* Chceme do nasi stranky vlozit reklamni banner.
   Pokud by doslo k problemu a vkladany obsah byl
   prazdny, banner nevlozime. Pokud bychom ho vlozili
   stranka by nebyla validni, protoze prazdny DIV
   neni povolen. *}

{capture name="banner"}
{include file="banner.tpl"}
{/capture}

{* Provedeme trivialni test na prazdnost zachyceneho
   obsahu. Pokud byla sablona nactena a obsahuje banner,
   zobrazime ho, jinak ne. *}

{if $smarty.capture.banner ne ""}
<div class="banner">{$smarty.capture.banner}</div>
{/if}

Je důležité mít na paměti, že formátování zdrojového kódu nám může ovlivnit očekávaný průběh zpracování šablony, v tomto případě capture. Zdrojový kód pak sice vypadá lépe, ale změní nám chování. Uveďme si příklad na předchozím výpisu. Zápis capture a include by vypadal lépe takto:

{capture name="banner"}
 {include file="banner.tpl"}
{/capture}

Avšak mezera, která se nachází před {include ... bude součástí „zachyceného“ výstupu. Takže i v případě, že bude soubor šablony banneru prázdný, nebude podmínka splněna, protože $smarty.capture.banner bude obsahovat znak " " - jedna mezera. Doporučil bych v tomto případě a při takovémto ošetření zapisovat takto:

{capture name="banner"}{include file="banner.tpl"}{/capture}

Chceme-li „zachycený“ obsah uložit do námi definované proměnné, např. pro pozdější použití, použijeme parametr assign, jak již bylo řečeno výše. Jak to vypadá v kódu, ukazuje následující výpis:

{* Ulozime si do promenne $ip IP adresu
   navstevnika pro pozdejsi pouziti. *}

{capture name="ip_address"
   assign="ip"}{$smarty.server.REMOTE_ADDR}{/capture}

{* Nyni muzeme kdekoliv pouzit IP adresu
   navstevnika, je ulozena v $ip. *}

<div>Vaše IP adresa je {$ip}</div>

Pravda, nejedná se o příliš užitečný příklad, ale k nastínění použití uložení „zachyceného“ obsahu do proměnné snad stačí.

config_load

Existence konfiguračních souborů byla již mírně nastíněna v druhém díle tohoto seriálu, kde se hovořilo o syntaxi zápisu proměnných. Funkce config_load tedy slouží k nahrání konfiguračního souboru (konfigurační soubory jsou hledány v adresáři definovaném pomocí $smarty->config_dir při inicializaci Smarty v PHP). Funkce umožňuje použití čtyř parametrů, z nichž jeden je povinný a tři volitelné. V běžné praxi stačí dva parametry, ostatní lze nalézt v dokumentaci k funkci config_load. Zaměříme se tedy pouze na parametr file (povinný) a section. Parametr file udává jméno konfiguračního souboru, který chceme načíst, a ze kterého chceme používat konfigurační proměnné. Konfigurační soubor může být rozdělen na sekce. V praxi to znamená, že nepotřebujeme více konfiguračních souborů, třeba na definici barvy záhlaví, definici barvy zápatí a definici barvy samotného obsahu stránky. V jednom konfiguračním souboru vytvoříme tři sekce, pro každou část stránky zvlášť, a pak je postupně zpracujeme. Nezbývá nic jiného, než si ukázat použití v praxi. My si ukážeme použití sekcí na změně titulku stránky, aby ukázka nebyla zbytečně zdlouhavá a složitá.

Mějme konfigurační soubor config.conf s následujícím obsahem:

# Komentare v konfiguracnich souborech
# zacinaji krizkem, jsou jednoradkove.

# Definice globalnich konfiguracnich promennych
pageTitle = "Testovani konfiguracniho souboru"
userName  = "Tester"

# Sekce s nazvem Uzivatel
[Uzivatel]
userName  = "Uzivatel"

# Byla-li jiz definovana promenna stejne
# jmena, dojde k prostemu prepsani jejiho
# obsahu. Jako v jinych jazycich, plati
# posledni definice.

Nyní tedy v šabloně zavoláme funkci config_load a můžeme používat konfigurační proměnné.

{config_load file="config.conf"}

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
   <meta http-equiv="content-type" content="text/html;
      charset=iso8859-2" />
   <title>{#pageTitle#} - {#userName#}</title>
  </head>
 <body>
  <h1>Stránka pro uživatele {#userName#}</h1>
 </body>
</html>

V předchozím výpisu, pokud tuto šablonu použijeme, budou dosazeny konfigurační proměnné ze souboru config.conf, ale pouze z globální části. Sekce označená jako [Uzivatel] bude vynechána. Chceme-li tuto sekci použít, využijeme vhodně parametru section, kterým funkce config_load disponuje. V následujícím výpisu načteme konfigurační soubor a zároveň Smarty projde i sekci [Uzivatel], takže #userName# bude obsahovat řetězec Uzivatel, nikoliv Tester, jak tomu bylo v předchozím případě.

{config_load file="config.conf" section="Uzivatel"}

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <meta http-equiv="content-type" content="text/html;
     charset=iso8859-2" />
  <title>{#pageTitle#} - {#userName#}</title>
 </head>
 <body>
  <h1>Stránka pro uživatele {#userName#}</h1>
 </body>
</html>

Předpokládám, že ukázkový výstup není potřeba, chování šablony je zřejmé. Místo konfiguračních proměnných se doplní jejich obsah ze souboru. V obou případech bude obsah pageTitle stejný. V prvním výpisu má proměnná userName hodnotu Tester, ve druhém pak Uzivatel.

foreach a foreachelse

Funkce foreach slouží k procházení jednoduchých asociativních polí. K procházení složitějších datových polí je nutné používat funkce section (viz dále). Funkce je vlastně cyklus, tzn. že musí být ukončen. Jinak řečeno, vše co je mezi {foreach} a {/foreach} se „cyklí“. Funkce disponuje čtyřmi parametry. Dva parametry (from a item) jsou povinné a dva parametry (key a name) volitelné. Parametru from přiřadíme pole, které se má procházet, a parametru item jméno proměnné, do které se má uložit položka pole při každém průchodu. To je příklad nejjednoduššího použití, které si demonstrujeme na následujícím výpisu.

Pro následující výpisy předpokládejme přiřazení hodnot do pole v PHP takto:

<?php
 $pole = array("Petr", "Martin", "Jan");
 $smarty->assign("pole", $pole);
?>

V šabloně chceme vypsat obsah pole $pole do nečíslovaného seznamu. Použijeme tedy funkci foreach následujícím způsobem:

<ul>
{foreach from="$pole" item="jmeno"}
 <li>{$jmeno}</li>
{/foreach}
</ul>

Výsledek je zřejmý, ale pro jistotu - výstup bude vypadat takto:

<ul>
 <li>Petr</li>
 <li>Martin</li>
 <li>Jan</li>
</ul>

Zatím jsme si vystačili s parametry from a item, nyní si ukážeme, k čemu slouží key. Jak již název napovídá, bude se do proměnné, která je tomuto parametru přiřazena, ukládat název klíče hodnoty ukládané do item (obdobné funkci foreach v PHP).

Pro následující výpisy předpokládejme přiřazení hodnot do pole v PHP takto:

<?php
 $pole = array(6 => "Petr", 4 => "Martin", 12 => "Jan");
 $smarty->assign("pole", $pole);
?>

V šabloně chceme vypsat obsah pole $pole do nečíslovaného seznamu, společně s hodnotami klíčů. Použijeme tedy funkci foreach následujícím způsobem:

<ul>
{foreach from="$pole" item="jmeno" key="klic"}
 <li><b>{$klic}</b> - {$jmeno}</li>
{/foreach}
</ul>

Výsledek je opět zřejmý a bude vypadat takto:

<ul>
 <li><b>6</b> - Petr</li>
 <li><b>4</b> - Martin</li>
 <li><b>12</b> - Jan</li>
</ul>

Způsob použití může být i složitější. Pro demonstraci použijeme dvourozměrné pole a zároveň si vysvětlíme použití foreachelse. Část foreachelse se provede pouze tehdy, pokud předáme parametru from neexistující nebo prázdné pole.

Pro následující výpisy předpokládejme přiřazení hodnot do pole v PHP takto:

<?php
 $smarty->assign("kontakty", array(
             array("jmeno" => "Petr",
                "mail"  => "petr@abclinuxu.cz",
                "mobil" => "775 123 456"),
             array("jmeno" => "Martin",
                "mail"  => "martin@abclinuxu.cz",
                "mobil" => "776 123 456"),
             array("jmeno" => "Jan",
                "mail"  => "jan@abclinuxu.cz",
                "mobil" => "777 123 456")));
 $smarty->assign("kontakty", $kontakty);
?>

Jako už několikrát v předchozích případech chceme vypsat obsah pole, co jiného :-). Abychom tedy provedli nějakou změnu, vypíšeme obsah pole do jednoduché tabulky. Použijeme následující šablonu:

<table>
 <tr>
  <td><b>Jméno</b></td>
  <td><b>E-mail</b></td>
  <td><b>Telefon</b></td>
 </tr>
{foreach from="$kontakty" item="polozka"}
 <tr>
  <td>{$polozka.jmeno}</td>
  <td>{$polozka.mail}</td>
  <td>{$polozka.mobil}</td>
 </tr>
{foreachelse}
{* Tato cast se provede v pripade prazdneho pole *}
 <tr>
  <td><b>Neplatná vstupní data</b></td>
 </tr>
{/foreach}
</table>

V šabloně jsme použili přístup k prvkům v dvourozměrném poli pomocí tečkové notace (viz druhý díl). Výstupem této šablony bude (v případě existujícího vstupu, jinak se provede větev foreachelse) toto:

<table>
 <tr>
  <td><b>Jméno</b></td>
  <td><b>E-mail</b></td>
  <td><b>Telefon</b></td>
 </tr>
 <tr>
  <td>Petr</td>
  <td>petr@abclinuxu.cz</td>
  <td>775 123 456</td>
 </tr>
 <tr>
  <td>Martin</td>
  <td>martin@abclinuxu.cz</td>
  <td>776 123 456</td>
 </tr>
 <tr>
  <td>Jan</td>
  <td>jan@abclinuxu.cz</td>
  <td>777 123 456</td>
 </tr>
</table>

Zbývá poslední parametr funkce foreach a to name. Pokud si funkci, resp. jeji cyklus, pojmenujeme, a to právě pomocí tohoto parametru, můžeme pomocí speciální konstrukce získávat informace z průběhu cyklus. Slouží nám k tomu konstrukce $smarty.foreach.jmeno.vlastnost, kde za jmeno dosadíme řetězec, který jsme přiřadili parametru name daného cyklu. Jako vlastnost můžeme vybrat jednu z následujících hodnot: index, iteration, first, last, show a total.

index

Pomocí této vlastnosti můžeme sledovat aktuální hodnotu indexu v poli (počáteční hodnota při prvním příchodu je 0). Této vlastnosti můžeme využít například při různém vybarvení lichých a sudých řádků tabulky. My si ukážeme pouze výpis této hodnoty s využitím pole $kontakty.

<table>
 <tr>
  <td><b>Č.</b></td>
  <td><b>Jméno</b></td>
  <td><b>E-mail</b></td>
  <td><b>Telefon</b></td>
 </tr>
{foreach from="$kontakty" item="polozka" name="kontakty"}
 <tr>
  <td>{$smarty.foreach.kontakty.index+1}</td>
  <td>{$polozka.jmeno}</td>
  <td>{$polozka.mail}</td>
  <td>{$polozka.mobil}</td>
 </tr>
{foreachelse}
{* Tato cast se provede v pripade prazdneho pole *}
 <tr>
  <td><b>Neplatná vstupní data</b></td>
 </tr>
{/foreach}
</table>

Výstup stejný jako v předchozím případě s tím rozdílem, že tabulka navíc obsahuje jeden sloupeček, ve kterém je vypsáno číslo řádku. Hodnotu index je nutné upravit přičtením čísla 1, aby řádkování nezačínalo nulou. Tomu lze předejít použitím vlastnosti iteration, viz dále.

iteration

Tato vlastnost obsahuje hodnotu, která je rovna hodnotě iterace cyklu. Počáteční hodnotou je 1. Toto číslo je při každém průchodu zvětšeno o jedna. Jednoduchý demonstrační příklad, který ukáže rozdíl mezi index a iteration:

{foreach from="$kontakty" item="polozka" name="kontakty"}
 {$smarty.foreach.kontakty.index}|
 {$smarty.foreach.kontakty.iteration}, 
{/foreach}

Výstupem této testovací šablony bude řada čísel 0|1, 1|2, 2|3.

first a last

Vlastnost first má hodnotu TRUE při prvním průchodu cyklem, v ostatních případech má hodnotu FALSE. Opakem je vlastnost last, která má hodnotu TRUE při posledním průchodu cyklem, v ostatních případech má hodnotu FALSE. Použití by mělo být zřejmé (ve spojení s funkcí if - příští díl).

total

Vlastnost total obsahuje číslo, které odpovídá celkovému počtu iterací, které cyklus foreach vykonal.

Závěr

V příštím díle budeme pokračovat v seznamování s vestavěnými funkcemi. Probereme funkce if, include, include_php, insert, ldelim a rdelim.

       

Komentáře

[Karel Vantuch]

Mi neni jasna jedna vec proc smarty nebo nejaky jiny sablonovaci system je napsany v php, vzdyt to musi byt dost pomale, proc neni smarty napsany v cecku a neni soucasti php engine?

[AraxoN]

Tiež som nad tým už uvažoval... Šlo by to urobiť ako extension do PHP. Čo som pozeral, tak by to nemalo byť až také ťažké. Akurát Smarty sa mi nepáčia, lebo sú trochu, ehm, ťažkotonážne, a pripadá mi, že autori vyvinuli nový jazyk podobný jazyku PHP. Akurát mi nie je jasné prečo tento PHP-like jazyk naprogramovali v samotnom jazyku PHP.

Šablóny by mali slúžiť HTML-károm, ktorí viacmenej nevedia programovať. Vo chvíli keď šablóny začnú prekypovať všelijakými riadiacimi štruktúrami, tak podľa môjho názoru strácajú zmysel. Neoddeľujú programový kód od HTML-ka a pri práci s nimi si neprogramátori musia dávať hneď väčší pozor. To už rovno môžu používať pôvodné PHP.

Typický prípad použitia šablón vidím v tom, že najprv kockatí programátori naprogramujú čo je treba a k tomu dodajú sadu hnusných šablón, lebo nemajú grafické cítenie. Potom príjde webdizajnér (v zmysle grafik) a ten dodané šablóny poľudští. Grafikove IT schopnosti končia pri HTML kóde a CSS-ku, ak má prístup k niečomu viac, tak to je potenciálny průser.

[Toman]

Vas "typicky pripad" je odpoved na otazku Ja si mysli, ze by se casem Smarty mohl stat extensions, resp. melo tomu asi byt ihned od pocatku. Tim, jak jste jiz zminil a bylo zmineno i o prispevek vyse, ze je Smarty v PHP, je opravdu dost krkolomne, me ale prinasi moznosti zpracovat "nejakou" sablonu a kolegove CSSkari se o vsechno ostatni postaraji. Predhodit jim PHP kod, kde budou nejake ty HTML tagy, to muzu soubory rovnou poslat na /dev/null

[AraxoN]

Nespochybňujem opodstatnenosť existencie šablón. Nakoniec - aj my používame šablóny na oddelenie HTML od programového kódu. Čo ale spochybňujem je smer, ktorým sa uberajú Smarty - takéto konštrukcie podľa môjho názoru nemajú v šablónach existovať:

{capture name="ip_address"
   assign="ip"}{$smarty.server.REMOTE_ADDR}{/capture}

či

<ul>
{foreach from="$pole" item="jmeno" key="klic"}
 <li><b>{$klic}</b> - {$jmeno}</li>
{/foreach}
</ul>

alebo

{$smarty.now|date_format:"%d.%m.%Y"}

To už nie sú šablóny, to je normálne programovanie, ktoré by malo ostať pred HTML-kármi ukryté.

[Daniel Kvasnička ml.]

Jde o to urcit hranici mezi business logikou a logikou tykajici se vypsani spocitanych dat na obrazovku -- a to je duvod proc si myslim, ze druhy vami uvedeny priklad do sablony patri. Nedela nic jineho, nez rotuje pole a vypisuje jeho hodnoty, nic nepocita ani podobne, jde o zalezitost prezentace. Mit tohle v business logice by me pripadlo nesystemove.