SMARTY – modifikátory

9. října 2003

•

Prvním krokem k prezentaci dat je jejich získání a zpracování. Takto získané hodnoty je ovšem často nutné pro správné zobrazení ještě nějakým způsobem upravit, například zkrátit text na přesně stanovenou délku. SMARTY nabízí možnost, jak takovéto úpravy hodnot proměnných provést v rámci šablony a udržet tak aplikační kód přehledný. Funkce provádějící tyto úpravy v rámci šablony se nazývají modifikátory.

Hned na začátek si uvedeme jednoduchý příklad zkrácení textu na určitou délku:

text:
$var = „Tento text je velmi, ale opravdu velmi dlouhý.“;
šablona:
…
{$var|truncate:30:“…“}
…
výsledek:
Tento text je velmi, ale opravdu…

Z programátorského hlediska jsou modifikátory běžné PHP funkce, které SMARTY zavolá a předá jim hodnotu proměnné. Ty ji následně upravenou vrátí.

Použití

Modifikátory, jak je patrné z výše uvedeného příkladu, jsou od proměnné odděleny svislítkem (|). Za ním následuje název modifikátoru a dvojtečkou oddělené parametry modifikátoru. Za těmito parametry může následovat další svislítkem oddělený modifikátor.

Pokud je proměnná polem, pak bude modifikátor aplikován na každou hodnotu pole. V některých případech možná budete chtít, aby modifikátor byl použit na pole jako celek. Pak je nutné před název modifikátoru předřadit zavináč (@). Pro ilustraci takového případu si vypůjčíme příklad z dokumentace k systému SMARTY, který zobrazí počet prvků v poli:

{$articleTitle|@count}

Modifikátory lze také použít spolu s funkcemi, které vrací nějaký text. Příklad použitý v minulém článku lze modifikovat následujícím způsobem:

šablona:
…
pro x = 12, y = 15:<br>
( x + y ) * 12 =
{math|string_format:“%.2f“ equation=“( x + y ) * 12″ x=12 y=15}
…
výsledek:
( x + y ) * 12 = 324.00

Jak už jsem zmiňoval, není problém použít více modifikátorů najednou (pozor, záleží na pořadí):

{„text, který JE NUTNÉ vytisknout“|lower|strip:“-„|truncate:18:“…“:true}
výsledek: text,-který-je-nut…

Přehled vestavěných modifikátorů

Nyní si probereme některé modifikátory, které jsou spolu se SMARTY distribuovány. V závorce jsou uvedeny parametry modifikátoru. V originální dokumentaci najdete, kromě seznamu všech modifikátorů, také informace o implicitních hodnotách jejich parametrů.

capitalize
Modifikátor capitalize použijeme v případě, že chceme, aby každé slovo textu začínalo velkým písmenem.
cat (string text)
Cat je jednoduchý modifikátor pro připojení specifikovaného textu na konec hodnoty proměnné.
count_characters, count_words, count_sentences, count_paragraphs
Jak názvy těchto modifikátorů napovídají, vytisknou počet znaků (slov, vět, odstavců) hodnoty proměnné.
šablona:
{„jedno slovo za druhym“|count_words}

výsledek:
4
date_format (string format, mixed implicitni_datum)
Date_format je často používaným modifikátorem, sloužícím k vytištění data v závislosti na hodnotě proměnné a použitém formátu. Hodnota proměnné může být jak počet sekund od roku 1970 (viz předchozí článek, proměnná $smarty.now), tak i jakýkoliv řetězec, který lze předat PHP funkci strtotime. Pro formátování řetězce jsou používány direktivy funkce strftime.
šablona:
{$smarty.now|date_format:“%d/%m“}

výsledek:
aktuální datum ve formátu den/měsíc (12/7)
default (string hodnota)
Jednoduchý modifikátor pro určení hodnoty proměnné, pokud proměnná není definovaná a nebo je prázdná.
escape (string co_prevest)
Tento modifikátor slouží k převedení speciálních znaků na HTML entity. Jako parametr může být použita jedna z hodnot: html, htmlall, url, quotes, hex, hexentity, javascript. Už sám jejich název dostatečně vysvětluje jejich význam, podrobný popis naleznete v manuálu.
lower, upper
Tyto modifikátory slouží k převedení všech znaků hodnoty proměnné na malá (respektive velká) písmena.
nl2br
Jako stejnojmenná funkce PHP i tento modifikátor zamění znaky konce řádek na HTML elementy br.
replace (string najit, string nahradit)
Modifikátor replace slouží k nahrazení řetězce najit za řetězec nahradit.
preg_replace (string regularni_vyraz, string text)
Podobně jako předcházející modifikátor funguje i preg_replace, ovšem s tím rozdílem, že hledaný text je dán regulárním výrazem. Syntaxe regulárního výrazu je totožná se syntaxí použitou ve stejnojmenné PHP funkci preg_replace.
string_format (string format)
Tento modifikátor slouží především k stanovení formátu čísel. Syntaxe formátu je totožná se syntaxí PHP příkazu sprintf (respektive printf).
strip (string retezec)
Modifikátor strip slouží k odstranění opakovaných mezer, tabulátorů a konců řádek a jejich nahrazení jedinou mezerou, popřípadě předaným řetězcem.
šablona:
{„text mezery text“|strip}

výsledek:
text mezery text

šablona:
{„text mezery text“|strip:“++“}

výsledek:
výsledek: text++mezery++text
strip_tags
Strip_tags slouží k odstranění HTML elementů z hodnoty proměnné.
truncate (int delka, string na_konec, boolean ukoncit_uprostred_slova)
Truncate je modifikátor, který asi využijete nejčastěji. Slouží ke zkrácení textu proměnné na určitý počet znaků (parametr delka). Po zkrácení lze na jeho konec připojit další znaky, například tři tečky (parametr na_konec). Pokud poslední parametr nastavíme na false (implicitní hodnota), bude text zkrácen tak, aby nekončil uprostřed slova.
šablona:
{„text, který bude zkrácen ve SMARTY“|truncate:14:“…“}

výsledek:
text, který bude…