Formuláře pomocí Smart

Šablonovací systém Smarty nabízí několik funkcí, které autorovi ušetří značné množství práce, ale především času, při vytváření formulářů. (Formuláře jsou jednou z nejdůležitějších součástí interaktivních WWW stránek, neřkuli internetových obchodů.) Jména všech těchto funkcí začínají řetězcem html_ (včetně koncového podtržíka). Bohužel možnosti tvorby formulářů pomocí Smarty šablon nejsou úplné a je výhodnější použít Smarty plugin, který bude popsán v pozdějších dílech.

html_checkboxes

Příkaz html_checkboxes slouží k vytvoření zaškrtávacích boxů. Korektní název by mohl být pole spínačů, protože každý lze nastavit bez ovlinění ostatních, výjimkou může být ovládání pomocí javascriptu. Vyžadovaná pole mohou být naplněna ještě na straně PHP scriptu, nebo dle aktuální situace na straně šablony. Výstup do zobrazované šablony je kompatibilní s požadavky normy XHTML. Parametry funkce jsou následující:

• name - nepovinný parametr,  řetězec, určuje jméno pro celý checkbox set. Pokud nebude použit, bude nastaven na defaultní checkbox
  
• values - povinný parametr, pokud není použit parametr options, typu pole. Určuje hodnoty k jednotlivým zaškrtávacím políčkům.
• output - povinný parametr, pokud není použit parametr options, typu pule. Určuje  popisy k jednotlivým zaškrtávacím políčkům.
• options - nepovinný parametr, kterým lze nahradit parametry values a options, je typu associativní pole ve tvaru array(value1=>output1[[,valuen=>outputn]]);
• selected - nepovinný parametr, typu řetězec (je-li vybrána jen jedna hodnota), nebo pole (při výběru jedné a více hodnot). Definuje, která políčka budou po startu zaškrtnuta. Zadávají se values, nikoliv outputs.
  
• separator - nepovinný parametr, typu řetězec. Určuje oddělovač jednotlivých zaškrtávacích políček, například odřádkování.
• labels - nepovinný parametr, logického typu, s výchozí hodnotou true. Určuje, zda-li bude k jednotlivým zaškrtávacím políčkům přidán obalovací tag <label>

html_radios

Tento příkaz slouží vytvoření přepínačů, na rozdíl od checkboxů může být vybrána pouze jedna hodnota.  Opět mohou být vyžadovaná pole naplněna jak na straně PHP scriptu, tak přímo v šabloně. Výstup je opět generován kompatibilní s normou XHTML. Parametry funkce jsou stejné jako u html_checkboxes, se dvěma vyjímkami:

• není definován parametr labels
• selected - je pouze řetězcem, protože v případě přepínačů lze mít zvolenu jen jednu hodnotu.

html_options

Příkaz ke generování rozbalovací nabídky select (option), který je opět generován 100% kompatibilní s XHML  standardem. Automaticky je řešen předvýběr zvolené hodnoty, případně více hodnot. Jestliže je místo kterékoliv ze vstupních hodnot v poli values vnořené pole, je udělán podvýběr (stejně jako při použití <optgroup> při ruční tvorbě). Parametry funkce jsou stejné jako v případě html_checkboxes, s několika výjimkami:

• Nejsou definovány parametry separator a labels.
• selected - může být definován jako pole i jako řetězec. Určuje, které hodnoty z options budou defaultně označené.

html_select_date

Funkce, která generuje do formuláře na www stránce výběr datumu. Funce má velké množství nepovinných parametrů, které definují pojmenování proměnných, rozsah zadávání, ... Parametry jsou následující:

• prefix - nepovinný parametr, typu řetězec. Určuje předponu jména pro nastavovaný datum. Například "od_", "do_", ... Pokud není použit je obtížné rozlišit ze kterého datumu jsou data čerpána.
• time - nepovinný parametr, ve formátu timestamp (unixový čas), nebo rrrr-mm-dd. Určuje datum, který bude v selectech přednastaven
• start_year - nepovinný parametr řetězcového typu, který určuje nejnižší vybíratelný rok. Lze jej uvést jako rok, nebo relativně k aktuálnímu roku. Výchozí hodnota je aktuální rok.
  
• end_year - stejné jako start_year, ale koncový rok výběru. Výchozí hodnota je stejná jako start_year.
  
• display_days, display_months, display_years - nepovinný parametr typu boolen, defaultně nastavený na true, který určuje zda bude zobrazené políčko po řadě pro den, měsíc, rok.
• month_format - nepovinný parametr, řetězcového typu, defaultně nastavený na '%B', který určuje formát jakým bude zobrazen měsíc
• day_format - nepovinný parametr, řetězcového typu, s výchozí hodnotou '%02d', který určuje v jakém formátu bude den vložen do zobrazovací části výběru
• day_value_format - nepovinný parametr, řetězcového typu, výchozí nastavení je '%d', určuje formát, v jakém budou dny vloženy do části value
• month_value_format - nepovinný parametr, řetěczového typu, výchozí nastavení '%m', určuje formát, v jakém budou dny vloženy do části value
• year_as_text - volitelný parametr, logického typu s defaultním nastavením na false, určující 
  
• reverse_years - volitelný parametr, logického typu s výchozím nastavením na false, určující, zda-li budou roky v sestupném, nebo vzestupném pořadí
• field_array - volitelný parametr řetězcového typu, určující jméno pole do jakého bude na straně PHP scriptu vrácen datum
• day_size, month_size, year_size - volitelný parametr řetězcového typu, určující parametr size select boxu výběrů dne, měsíce a roku
• all_extra, day_extra, month_extra, year_extra - volitelný parametr řetězcového typu, kterým se nastavují extra parametry výběru
• field_order - volitelný parametr řetězcového typu, defaultně nastavený na 'MDY', který určuje pořadí select boxů
• field_separator - volitelný parametr řetězcového typu, defaultně nastavený na '\n', který určuje oddělovač jednotlivých políček
• day_empty, month_empty, year_empty - Nepovinný parametr řetězcového typu,  pokud je použit, bude defaultně zobrazen vložený text a v parametru value bude hodnota ' ' (mezera)

html_select_time

Funkce ekvivalentí předchozí, ale sloužící pro vytvoření select boxů pro výběr času. Počáteční nastavení předvybraného času může být provedeno v několika formátech. může se jednat o Unixový timestamp, nebo jako řetězec obsahující i Y-M-D. Je podporovýn formát YYYY-MM-DD, ale je správně rozkódován i datum s jednociferným číslem pro měsíc a den, Pokud jedna z hodnot Y-M-D není nastavena, nebude proveden předvýběr hodnoty.  Funkce nemá žádné povinné paramety, které jsou následující:

• prefix - řetězec, určuje předponu jména
• time - timestamp, který určuje přednastavení času ve výběru, pokud není předán z PHP scriptu je nastaven aktuální čas
• display_seconds, display_minutes, display_hours, display_meridian - parametr logického typu, defaultně nastavený na true, který určuje, zda-li bude zobrazen výběr sekund, minut, hodin a meridianu (dopoledne, popoledne - AM/PM)
• use_24_hours - logický typ, defaultně nastavený na true, určuje zda-li bude bude použit 24 hodinový formát, či nikoliv
• second_interval, minute_interval - parametr číselného typu, která určuje krok v jakém budou ve výběru sekundy, nebo minuty
• field_array - parametr řetězcového typu, který určuje jméno pole, do nějž budou vráceny hodnoty z formuláře
• all_extra, second_extra, minute_extra, hour_extra, meridian_extra - přidává extra parametry,  do select/input boxu

Další důležité funkce

Smarty poskytují funkce pro vložení obrázku (html_image) a tabulky (html_table).

html_image

Funkce pro vložení obrázku do stránky.  Pokud nejsou zadány v šabloně výška a šířka, jsou tyto automaticky vypočítány při kompilování šablony. Pokud je použita tato funkce je k obrázku přistupováno při kažbém načítání šablony. Pokud nepoužíváte cacheování (bude probráno v příštím díle), je výhodnější nepoužívat tuto funkci a zadat tag pro vložení obrázku staticky. Při použití parametru href je tag pro vložení obrázku automaticky obalen odkazem (tag <a href="...">obrazek</a>. Cesta k obrázku může být zadána relativně, pokud tak není učiněno, je použita hodnota DOCUMENT_ROOT jako základ. Jestliže je použito zabezpečení, cesta musí vést mimo zabezpečený adresář. Parametry funkce jsou následující:

• file - povinný parametr řetězcového typu, který určuje název vloženého adresáře včetně cesty
• border - nepovinný parametr řetězcového typu, který určuje tloušťku rámečku kolem obrázku.
• height, width - nepovinný parametr typu řetězec, určuje výšku a šířku obrázku, není-li tento parametr použit, je výška a šířka nastavena podle skutečné velikosti obrázku.
• basedir - nepovinný parametr řetězcového typu, který určuje základní adresář cesty k obrázku.
• alt - nepovinný parametr řetězcového typu, který určuje alternativní text k obrázku. I když není použit, je alt do značky vložen s hodnotou, která je prázdný řetězec.
• href - nepovinný parametr řetězcového typu. Jestliže je použit, je obrázek použit jako odkaz na adresu obsaženou v tomto parametru.

html_table

Funkce pro vygenerování tabulky a její naplnění daty hodnotami ve vstupním poli. Parametry tr_attr a td_attr jsou používány cyklicky. Parametry funkce jsou následující:

• loop - povinný parametr typu pole, který udává vstupní data pro vytvoření tabulky
• cols - nepovinný parametr typu integer, defaultně nastavený na 3, který udává klik sloupců bude mít výsledná tabulka
• table_attr - nepovinný parametr typu řetězec, defaultně nastavený na 'border="1"'. Doplňkové informace pro vytvoření tabulky, jedinné místo, kde lze určit styl tabulky.
• tr_attr, td_attr - Nepovinný parametr typu řetězec, nebo pole určující parametry pro řádky, případně buňky, tabulky. Pokud je použito pole jsou jeho hodnoty používány cyklicky.
• traipad - Nepovinný parametr řetězcového typu, který je defaultně nastaven na hodnotu '&nbsp;'. Určuje výplňovou hodnotu pro prázdné buňky tabulky
• hdir, vdir - nepovinný parametr řetězcového typu, defautní nastavení je hdir="right" a vdir="down", určující směry, kterými bude plněna tabulka pro hdir jsou možné hodnoty right a left, pro vdir jsou povoleny hodnoty down a up.

mailto

Funkce pro automatizované vytváření odkazů na emailovou adresu se všemi možnými parametry tohoto odkazu. Samozřejmostí je možnost "schování" emailové adresy do hexadecimálního zápisu adresy, nebo do javascriptu. Parametry funkce jsou tyto:

• address - povinný parametr (jediný), řetězcového typu, do kterého je vložena adreca hlavního adresáta e-mailu.
• text - nepovinný parametr typu řetězec. Definuje text odkazu, není-li nastaven je zobrazen obsah parametru address
• encode - parametr typu řetězec, mající jednu z hodnot none (defaultní), hex, javascript. Určuje, jak bude zakódována emailová adresa,
• cc, bcc - řetězec, emailová adresa pro zaslání kopie a skryté kopie. Pokud je nutné odesílat kopie na více adres, jsou tyto adresy odděleny čárkou.
• subject - řetězec, který definuje předmět mailu
• newsgroups - řetězec, který definuje, na které newsgroups bude zpráva odeslána. Více hodnot se odděluje čárkou
  
• followupto - řetězec,
• extra - řetězec, přes který lze doplnit extra parametry k odkazu, jako například určení stylu.

cycle

Funkce funguje pro cyklické procházení hodnot, používá se například pro cyklické změny barev či stylů v buňkách, či řádcích tabulek.  Procházení několika různých polí tabulky je realizovatejné pomocí několika cyklů, přičemž každý z nich má unikátní jméno. Lze vynutit zakázání zobrazení některého z výstupů tabulky, kdy se nastaví parametr print='false'.  Parametry funkce jsou následující:

• values - povinný parametr typu pole, nebo řetězec, který určuje hodnoty, které budou střídány
• name - nepovinný parametr řetězcového typu, který určuje jméno cyklu pro možnost použití několika těchto cyklů, přečemž každý z nich musí mít unikátní jméno.
• print - nepovinný parametr logického typu, který určuje, zda bude hodnota vrácená cyklem zobrazená či nikoliv.
• advance - nepovinný parametr logického typu, který určuje, zda-li bude při příštím průchodu cyklem použita současná hodnota (advance="true"), či standardně další (advance="false")
• delimiter - nepovinný parametr řetězcového typu, defaultně nastavený na ',' (čárka), který určuje, jaký oddělovač bude použit v řetězci values pro oddělení hodnot
• assign - nepovinný parametr řetězcového typu, který určuje do jaké proměnné šablony bude předána hodnota z cycle místo jejího zobrazení.

counter

Counter je počítadlo pro zobrazení. Pamatuje si hodnotu poslední hodnotu iterace, lze určit směr a krokování cyklu. Lze použít několik počítadel, ale každé z nich musí mít unikátní pojmenování. Žádný parametr není povinný a pro tuto funkci jsou to tyto:

• name - řetězcového typu, výchozí hodnota je 'default', určuje jméno cyklu, pokud je třeba použít několik cyklů, každý musí mít unikátní jméno.
• start - celočíselného typu, výchozí hodnota je nastavena na '1', určuje počáteční hodnotu, použitou při první iteraci cyklu
• skip - celočíselného typu, výchozí hodnota je '1', určuje krok každé iterace cyklu
• direction - řětězcového typu, defaultně nastavený na 'up', určuje směr iterování cyklu. Možné hodnoty jsou 'up' a 'down'
• print - logického typu, defaultně 'true', který určuje, zda-li bude hodnota cyklu zobrazována, či nikoliv
• assign - řetězcového typu, který určuje proměnnou šablony, do které bude přiřazena hodnota cyklu místo jejího výstupu ke zobrazení.

math

Funkce math slouží ke zobrazení hodnoty výpočtu, případně k jejímu přiřazení do proměnné šablony k dalšímu použití. Podporované funkce jsou +, -, /, *,  abs, ceil, cos,  exp, floor, log, log10, max, min, pi, pow, rand, round, sin, sqrt,  srans a tan, které se používají stejným způsobem, jako jejich ekvivalenty v PHP.  Použití funkce math je mnohem náročnější, než zpracování výpočtu na straně PHP kódu a posléze pouze zobrazení hodnoty v šabloně! Parametry funkce jsou tyto:

• equation - řetězec bez výchozí hodnoty, popisuje rovnici, nebo výpočet z proměnných
• format - řetězec bez výchozí hodnoty, určuje formátování výstupu stejným způsobem, jak je to realizováno v PHP funkci sprintf
• assign - řetězec bez výchozí hodnoty, který učuje, do jaké proměnné bude přiřazen výstup výpočtu. Pokud není parametr použit je výsledek výpočtu zobrazen do stránky, je-li nastaven, bude do této proměnné přiřazen k dalšímu zpracování.
• [var ...] - proměnné vstupující do výpočtu. Mohou být přiřazeny z proměnných šablony, nebo konstanty.

Závěr

V tomto díle byly představeny funkce, které jsou použitelné při tvorbě šablon. Balíček s příklady za poslední 2 díly je ke stažení zde. Příští díl bude zaměřen na práci s cache, konfigurační soubory šablon a možnosti ladění, poté budou díly zaměřené na dosud nevysvětlené metody Smarty šablon na straně PHP scriptu,  tipy, triky, rozšířené funkce a možnosti použití hotových, případně tvorby vlastních pliginů.