SMARTY – konfigurace, filtry, zdroje

Tentokrát se zaměříme na ty vlastnosti systému SMARTY, které využijeme zejména v případě rozsáhlejších projektů. Konkrétně se budeme věnovat vytváření konfiguračních souborů a použití filtrů. Na závěr si také řekneme pár slov o tom, odkud můžeme šablony do našich aplikací načítat.

Konfigurace

Většina webových stránek a aplikací používá různých druhů konfiguračních souborů pro nastavení takových informací, jako jsou například heslo a jméno pro připojení k databázi, název stránek, položky menu, a podobně. Součástí systému SMARTY je také několik funkcí, které nám umožňují pracovat s konfiguračními soubory jak v rámci šablon, tak uvnitř našich skriptů.

Princip konfiguračních souborů je velmi jednoduchý. Do určeného adresáře (standardně se jedná o adresář configs – viz nastavení proměnné $config_dir třídy Smarty) uložíme soubory obsahující definice konfiguračních proměnných, které budeme chtít v šablonách využívat. Na následujícím příkladu si ukážeme syntaxi konfiguračního souboru:

# — toto je komentář —
# definice jednotlivých proměnných
pageTitle = „Strana s.r.o. – webpages“
menuHome = Domů
menuProds = Produkty
menuMail = Kontakt
menuLogin = Přihlásit
# verze aplikace
.appVersion = 1.0.33
# nastavení specifická pro stránku Produkty
[Produkty]
pageTitle = „Strana s.r.o. – Produkty“
# nastaveni specifická pro stránku Přihlásit se
[Login]
pageTitle = „Strana s.r.o. – Přihlaste se“
warn = „““Pokud si přejete použít bezpečné přihlášení, využijte
   našeho klientského programu, který si můžete stáhnout z našich
   stránek“““
# ukázka skryté sekce
[.rootUser]
host=my.domain.com
db=ADDRESSBOOK
user=php-user
pass=foobar

Nejdůležitějším prvkem souborů jsou definice proměnných, které se zapisují ve formě proměnná=hodnota. Kromě řetězců a číselných hodnot můžou proměnné obsahovat i boolean hodnoty (true/yes/on nebo false/no/off). V souvislosti s těmito hodnotami je zajímavá proměnná $config_booleanize třídy Smarty definující, zda se mají tyto hodnoty převést na řetězce, nebo na boolean hodnoty známé z PHP.

Jak si můžete na výše uvedeném příkladu všimnout, řetězce nemusí být uzavřeny do uvozovek. Pokud však budeme chtít vložit do proměnné text přes více řádek (viz proměnná warn), musíme jej uzavřít do trojitých uvozovek („““). Pokud vám v příkladu chybí definice pole, pak vás zklamu. Prozatím nelze pole hodnot do konfiguračních souborů vkládat.

Dalším důležitým prvkem konfiguračních souborů jsou sekce. Zapisují se vždy na novou řádku ve formě [Nazev_sekce]. Proměnné pak můžeme umisťovat do jednotlivých sekcí. Při načítání konfigurací do šablon (viz funkce config_load níže) pak můžeme specifikovat, která sekce a tím i proměnné se mají načíst. Ty proměnné, které nepatří do žádné sekce (v našem příkladě menuHome, menuProds…) jsou implicitně zařazeny do takzvané globální sekce, která je načtena do šablony vždy.

Je-li v konfiguračním souboru uvedena jedna proměnná několikrát (v našem případě se jedná o proměnnou pageTitle), pak má vždy přednost ta hodnota, která je uvedena v sekci, kterou jsme určili při načítání konfiguračního souboru.

Pokud uvedeme jako první znak proměnné tečku (.), bude tato proměnná považována za skrytou proměnnou, což znamená, že ji není možné v šabloně používat. Naopak je možné ji používat v obslužných skriptech. To samé platí i pro sekce, které mohou být také skryté, čímž skryjí i všechny v ní obsažené proměnné.

Použití skrytých sekcí v rámci šablon lze však ovlivnit proměnnou $config_read_hidden třídy Smarty. Změnou hodnoty této proměnné můžeme ovlivnit možnost načtení skrytých sekcí do šablon.

Vložení konfigurace do šablony

K účelu načítání konfiguračních souborů do šablon máme k dispozici vestavěnou funkci config_load. Její použití je jednoduché. Na začátek šablony vložíme tuto funkci, která načte soubor určený atributem file. Nyní již můžeme v šabloně konfigurační proměnné libovolně používat.

Ovšem pozor! Proměnná načtená z konfigurace je vkládána do šablony jiným zápisem než jsme byli dosud při vkládání proměnných do šablony zvyklí. Konfigurační proměnné se do šablon vkládají ve formě {#promenna#}, přičemž použití tohoto typu proměnných se od běžných nijak neliší. Nyní ještě malá ukázka použití konfiguračního souboru ze začátku tohoto článku:

{config_load file=“config.conf“}
<html>
<head>
   {* titulek stranky *}
   <title>{#pageTitle#}</title>
</head>
<body>
   <h1>MENU</h1>
   <strong>{#menuHome#}</strong> | …
   …
</body>
</html>

Vložení konfigurace do skriptu

Konfigurační soubory nemusíme používat jen v šablonách, ale také v aplikační části webové prezentace. Existují dva způsoby, jak načíst konfigurační proměnné do skriptu. První je v podstatě totožný s tím, jak se načítají proměnné do šablon:

<?php
   require_once( „libs/Smarty.class.php“ );
   $smarty = new Smarty();
   $smarty->config_load( „config.conf“, „Produkty“ );
   // nacteni jedne promenne z konfigurace
   echo $smarty->get_config_vars( „pageTitle“ );
   // funkce vraci asociativni pole nactenych promennych
   print_r( $smarty->get_config_vars() );
?>

Druhý způsob spočívá v použití třídy Config_File a její metody get:

<?php
   require_once( „libs/Config_File.class.php“ );
   $c = new Config_File( „./configs“ );
   // nacteni promenne host z sekce rootUser
   echo $c->get( „config.conf“, „rootUser“, „host“ );
   print_r( $c->get( „config.conf“ ) );
?>

Zásadním rozdílem mezi těmito dvěma postupy pro načtení konfigurace je způsob načtení skrytých sekcí a proměnných. V prvním případě nebudou skryté sekce ani proměnné do skriptu načteny. Naopak v druhém případě budou načteny i skryté proměnné.

Pozn. autora: Smarty 2.6.1 obsahuje nepříjemnou chybu, která způsobuje, že skryté sekce jsou do šablon a do skriptů (při použití prvního postupu) načteny vždy, nehledě na nastavení proměnné $config_read_hidden. Doporučuji použít buď verzi 2.6.0 nebo nejnovější verzi z CVSka.

Dříve než opustíme téma konfigurací, ukážeme si ještě přehled atributů funkce config_load spolu s jejich popisem:

Filtry

Velká část naší pozornosti byla dosud zaměřena mimo jiné na funkce, které můžeme v šablonách využívat. Mezi ně bychom mohli s jistými výhradami počítat i filtry. Hlavní rozdíl spočívá v tom, že filtry nelze zavolat vložením příkazu do šablony, a dále také to, že jsou filtry aplikovány na celou šablonu a nikoli, jako funkce, pouze na její část.

Z výše uvedených charakteristik plyne, že filtry jsou funkce, které v určitý okamžik zpracovávání šablon SMARTY zavolá, předá jim celou šablonu a dostane od nich výsledek zpracování.

Možnosti použití filtrů jsou dány tím, o jaký typ filtru se jedná. První typ (takzvané prefilters) je aplikován na šablonu ještě před jejím zkompilování. Tyto filtry se hodí k dodatečné úpravě šablon, vymazání určitých částí z šablon, a podobně. Druhý typ filtrů (takzvané postfilters) je volán po zkompilování šablon do podoby PHP skriptů a před jejich uložením na disk. Poslední typ filtrů (takzvané output filters) je vyvolán vždy, když se prostřednictvím SMARTY pokusíte šablonu zobrazit (standardně metodou display).

Zdroje

Ve všech dosud uvedených příkladech jsme umisťovali soubory šablon do adresáře určeného proměnnou $template_dir. Ukládání šablon do jediného adresáře by mohlo být v případě rozsáhlejších projektů poněkud svazující, a proto si nyní na příkladech ukážeme, jak nastavit cestu k šablonám uložených na různých místech.

// PHP skript
$smarty->display( „index.tpl“ );
$smarty->display( „produkty/index.tpl“ );
$smarty->display( „file:produkty/index.tpl“ );
{* šablona *}
{include file=“menu.tpl“}
{insert file=“file:administrace/menu.tpl“}

První příklad ukazuje standardní použití umístění šablon. Ve všech případech jsou šablony načítány z adresáře specifikovaném v proměnné $template_dir. Všimněte si klíčového slova file v určení cesty. Toto slovo říká SMARTY, že šablona je uložena v souboru na disku a není nutné jej v těchto případech využívat.

// PHP skript
$smarty->display( „file:/home/kouba/help/templates/index.tpl“ );
$smarty->display( „file:C:/Sites/help/templates/index.tpl“ );
{* šablona *}
{include file=“file:/home/kouba/help/temlpates/index.tpl“}
{include file=“file:C:/Sites/help/templates/index.tpl“}

V dalším příkladě jsme si ukázali určení šablony absolutní cestou. Při tomto způsobu určení názvu a umístění šablony je nutné vždy zadat klíčové slovo file.

Výhodou SMARTY je, že umožňuje používat i jiné zdroje šablon, než jsou soubory uložené na disku. Nejjednodušším příkladem mohou být databáze. K tomu stačí zaregistrovat nový název pro zdroj (například db) a vytvořit funkce, které SMARTY zavolá, kdykoli bude nutné získat šablonu z tohoto zdroje. Zápis cesty i názvu šablony zůstává stále stejný. Jediné, co se mění, je klíčové slovo.

// PHP skript
$smarty->display( „db:index.tpl“ );
{* šablona *}
{include file=“db:produkty/prehled/index.tpl“}

Konkrétní způsob vytvoření nového zdroje a jeho zaregistrování si ukážeme v příštích dílech, které již nebudeme věnovat šablonám samotným, ale vytváření uživatelských funkcí, modifikátorů a podobně.

Odkazy, zdroje

• domovská stránka projektu SMARTY
• dokumentace k projektu SMARTY
• aktuální verze projektu SMARTY ke stáhnutí