Co jsou pluginy?

Pro pluginy by se měl používat korektní český termín "zásuvné moduly". Jedná se o rozšíření funkčnosti, známé je rozšiřování funkčnosti software (například pluginy Chatzilla, WizzRSS a Web Developer pro Mozilla/Firefox). Pro Smarty existuje nepřeberné množství takovýchto rozšíření, které usnadňují a urychlují vývoj webových aplikací, některé, z hlediska autora seriálu, zajímavé budou představeny v několika následujících dílech, ale pokud čtenář nenajde plugin s potřebnými vlastnostmi, nic mu nebrání napsat si vlastní (a případně jej uvolnit alespoň pod LGPL).

Pluginy pro Smarty šablony je třeba před použitím includovat do projektu (vhodným místem je init.php, který je spouštěn na začátku každého PHP sctiptu), nebo do scriptů/šablon, které tento plugin potřebují. V případě použití Smarty pluginů je třeba inicializovat pole $plugins_dir, kde jsou uloženy adresáře s jednitlivými pluginy (pro každý plugin lze mít vlastní adresář). Inicializaci lze provést přímo v souboru Smart.class.php, nebo přiřazením $page->plugins_dir=array(dir1[, dir2]). Je-li to pluginem vyžadováno, je také nutné vytvořit instanci třídy, která může nést inicializační hodnoty.

Pluginy jsou v podstatě běžné funkce, mají pevně danou strukturu názvu (pluginu/souboru i funkce), typ a počet parametrů.
Podle typu je určeno použití pluginu. Název pluginu i funkce musí obsahovat pouze písmena, číslice a podtržítka. Název pluginu/souboru se píše podle vzoru typ.jmeno.php, název funkce jako takové se řídí vzorem smarty_typ_jmeno(), kde jméno a typ musí být shodné. Pokud je splněn požadavek na názvy, lze plugin použíy jednoduše, jako jiné funkce Smarty, tj. pouze napsáním jména funkce. Typy pluginů budou popsány níže v textu společně s příklady.
Pokud je potřeba v pluginu použít závislosti na jiném již hotovém pluginu, je třeba na počátku definice funkčnosti pluginu tuto závislost zapsat použitím require_once $smarty->_get_plugin_filepath(typ, název);.

Funkce

Funkce pro použití ve Smarty šablonách, téměř vše ve Smarty je funkce. Předepsaný typ pro jméno pluginu je function.jmeno.php a pro funkci jako takovou smarty_function_jmeno. Parametry funkce jsou dva:

• $params - Asociativní pole, vstupní parametry funkce
• &$smarty - Odkaz na objekt smarty, ze které je plugin použit.

Návratová hodnota funkce je vložena do místa, kde je funkce použita, nebo vložena do proměnné šablony (fe funkci je zápis return "\$this->assign($jmeno, $hodnota);";). Pro "rozložení" pole params na jednotlivé proměnné ve tvaru $klic = $hodnota je nejjednodušší použít PHP funkci extract, případně pokud je třeba dělat kontroly hodnot je možné použít cyklus foreach. Příklad vytvoření funkce je v dokumentaci.

Modifikátory

V kapitole o modifikátorech (II. díl Smarty) bylo vysvětleno, že to jsou funkce, které upravují textový, nebo číselný výstup ve stránce. Jméno pluginu je modifier.jmeno.php a funkce modifikátoru bude pojmenována smarty_modifier_jmeno. Počet parametrů je volitelný, je vhodné některé z nich mít předdefinovány ve vstupních hodnotách funkce. Příklad definice a použití modifikátorů je k nalezení v dokumentaci.

Blokové funkce

Příkladem blokových funkcí jsou cykly a větvení, tj. jedná se o funkce, které mají počáteční a koncový příkaz, mezi nimiž je uzavřen blok tagů, výstupů hodnot, případně dalších funkcí. Název pluginu je block.jmeno.php a funkce se jmenuje smarty_block_jmeno. Bloková funkce je volána dvakrát, na počátku bloku a na konci Při vytvoření funkce je třeba použít několik parametrů (pořadí je nutné dodržet!):

• $params - Asociativní pole, vstupní parametry funkce
• $content - výstupní hodnota blokové funkce.
• &$smarty - Odkaz na objekt smarty, ze které je plugin použit.
• &$repeat - Logická hodnota, která určuje, zda-li bude blok opakován. Proměnná je předávána odkazem, čili umožňuje její ovlivnění z těla funkce.

Příklad použití je opět v originální dokumentaci, nebo v blokové funkci block.textformat.php, která je součástí Smarty šablon.

Výstupní filtry

Funkce, které jsou vykonány mezi zpracováním šablony a jejím zobrazením (odchycením do proměnné), slouží například k zakódování emailů do podoby, kterou špatně uvidí spamovací roboti, zpracování všech tagů <code>...</code> na <div class="code">...</code>.  Plugin je pojmenován outputfilter.jmeno.php, funkce smarty_outputfilter_jmeno a má pouze tyto dva parametry:

• $input - výstup šablony ke zpracování (například pokud je obsah odchycen metodou fetch do proměnné $mypage, bude tento obsah pro zobrazení zpracován například jako {code2div input=$mypage} místo přímého výstupu {$mypage}
• &$smarty - Odkaz na objekt smarty, ze které je plugin použit

Příklad vytvoření výstupního filtru je v dokumentaci.

Insert pluginy

Pluginy, které jsou určeny pro vložení hodnoty na určené místo šablony. Jméno je tvořeno jako insert.jmeno.php a funkce je pojmenována jako smarty_insert_jmeno. Vstupní parametry jsou stejné jako u funkce, výstupem je vždy řetězec. Vhodným příkladem insert pluginu je výpis aktuálního času, který je opět v dokumentaci.

Funkce překladače, pre- & post- filtry

Pluginy, které jsou volány při před kompilací (prefilter), po kompilaci (postfilter), či během kompilace (compiler) šablon. Jelikož se jedná, s velkou pravděpodobností, o málo psané pluginy, je ponecháno prostudování jejich vytvoření a použití na čtenáři, protože dokumentace poskytuje dostatek informací.

trigger_error()

Nepříliž známá funkce PHP, která se používá pro chybový výstup, její přesný popis je v dokumentaci PHP. Pokud ve vstupních parametrech není očekávaná hodnota, například je mimo rozsah, lze touto funkcí vyvolat výstup chyby a zároveň zastaví další vykonávání kódu. Vystup chyby bude buď do laděné stránky, nebo do logu, podle nastavení httpd. Zmíněna je zde, jelikož je velmi často v orig. pluginech Smarty. Ve třídě Smarty.class.php je "dodefinována", aby bylo zřejmé, kde nastala chyba, proto se nevolá přímo, ale prostřednictvím $page->trigger_error(), její parametry se nemění.

Zdroje

Ve větším projektu je vhodné nemít všechny šablony v jediném adresáři, ale rozdělit je do několika podardesářů (například shop, admin, frontend, ...), camozřejmě, že u menšího projektu lze vystačit s předponami (ve struktuře předchozího: sh_, adm_, fe_, ...). Smarty samozřejmě počítají s obojím a existuje možnost, jak přistupovat k souborům i jinde, než přímo v adresáři uvedeném ve vlastnosti $template_dir, ale i v jeho podadresářích, adresářích přímo na disku, nebo pomocí pluginu lze definovat další zdroje (databáze, LDAP, ...).
Příklady (v horní sadě je metoda Smarty na straně PHP scriptu, v dolní sadě ekvivalenty pro vložení jedné šablony do druhé):

První příklad je již známé použití šablony přímo z $template_dir, druhý příklad použije šablonu z podadresáře shop, třetí je ekvivalentní druhému, rozšířený o nepovinné klíčové slovo file. Toto klíčové slovo se stává povinným, jakmile se nepoužívá relativní cesta vůči $template_dir, ale je použito adresování v rámci disku, v tomto případě k šabloně main.tpl, uložené v adresáři /home/marek/html/projekt/templates/cerne. Poslední příklad ukazuje použití zdroje, který je definován jako plugin, v tomto případě pojmenovaný tpldb (templates database :-)).

Zdrojový plugin

K použití posledního zdroje (tpldb) je nutné vytvořit plugin, který tento zdroj definuje a zpřístupní. Příklad takového pluginu je například zde .  První funkce pluginu slouží k výběru šablony (možno i PHP scriptu) z databáze, druhá zjistí datum poslední modifikace šablony (předpokladem je, že bude uloženo v databázi), aby se nekopmilovaly i neaktualizované šablony, třetí a čtvrtá funkce ověří, zda-li je šablona (kód) platná a je-li trusted, tj. bezpečné pro použití v include_php a insert. Soubor s definicí zdroje je uložen pod názvem resource.jmeno.php a jednotlivé funkce jsou nazvány po řadě:

Význam jednotlivých parametrů je následující:

• $tpl_name - jméno šablony (scriptu), kterou je třeba získat z databáze
• &$source - proměnná, do které bude vrácen zdrojový kód šablony/scriptu
• &$timestamp - proměnná do které bude vráceno aktuální datum modifikace souboru

Všechny funkce mají svou návratovou hodnotu logického typu.

Závěr

Tento díl byl posledním z řady o Smarty šablonách, jako takových. Pokusil jsem se v něm osvětlit alespoň základ tvoření vlastních pluginů a využití alternativních zdrojů kódů a šablon, což je zase výborně řiditelné pluginem. Po tomto díle bude následovat několik o zajímavých pluginách pro Smarty. Pokud znáte nějaké, upozorněte mě na ně prosím.