Syntaxe šablon

Syntaxe je způsob, jakým píšete v běžném, nebo programovacím jazyce slova, či příkazy, tak, aby jste docílili významu, nebo činnosti, jaké chcete, potřebujete.

Smarty šablony jsou standardní html kód, ve kterém se objevují příkazy šablon, práce s konstantami, proměnnými a poli. Párové příkazy Smarty se píší pomocí páru {prikaz} a {/prikaz}, kde složené závorky představují oddělovače definované ve tříde Smarty. Mezi párové příkazy se nejčastěji uzavírají bloky cyklů a podmínek.

Oddělovače (delimiters)

Smarty šablony, jak bylo napsáno minule, se kompilují do PHP scriptů a to tak, že vše co je nějaký modifikátor, nebo příkaz Smarty je nahrazeno ekvivalentem v PHP. Aby třída Smarty_Compiler.class.php poznala které části má nahradit/zkompilovat, musíme použít oddělovače. Oddělovače si můžete sami nadefinovat nastavením proměnných $left_delimiter a $right_delimiter (ve verzi 2.6.6 se jedná o řádky 251 a 258) na libovolnou Vaší hodnotu. Defaultní nastavení je na pár závorek { a } (motýlci).

Oddělovače se Vám nesmí v šabloně už nikde objevit, protože vše co je mezi nimi je považováno za příkazy/proměnné Smarty a překladač by se je pokoušel zpracovat, což by vedlo k chybovým hláškám. Problém by se mohl vyskytnout, pokud používáte při tvorbě WWW stránek i JavaScripty. To můžete obejít tím, že do šablony vložíte místo levého oodělovače příkaz {ldelim} a místo pravého {rdelim}, případně celý blok uzavřete mezi příkazy/modifikátory {literal} a {literal}.

Ukázka JavaScriptu vloženého oběma způsoby (kód je vložen preXML způsobem):

<script language="JavaScript"><!--
function setWidth{ldelim}
  tabWidth=(document.body.clientWidth||window.innerWidth)-380;
  if(tabWidth>500){ldelim}
    tabWidth=500;
  {rdelim}
  document.getElementById('mainTab').style.width=tabWidth;
{rdelim}
--></script>

<script language="JavaScript"><!--
{literal}
function setWidth{
  tabWidth=(document.body.clientWidth||window.innerWidth)-380;
  if(tabWidth>500){
    tabWidth=500;
  }
  document.getElementById('mainTab').style.width=tabWidth;
}
{/literal}
--></script>

Druhý způsob zápisu je 100% přehlednější. Oddělovače nemusí být nutně jeden jediný znak, takže lze použít například předefinování na var $left_delimiter = '<smarty'; var $right_delimiter = 'smarty>';, ale programátor by měl trochu šetřit své ruce a klávesnici, přičemž programátorům bude asi nejbližší defaultní nastavení na pár {}.

Příkazy, proměnné a komentáře v šablonách

Příkazy ve Smarty šablonách se píší mezi oddělovače, {prikaz atribut1='hodnota'} je obecným příkladem a {include file='head.html'} je konkrétní příkaz, pomocí něhož vložím do výsledné stránky soubor head.html. Mezi příkazy patří i funkce z pluginů a řídící příkazy.

Proměnné k zobrazení pomocí Smarty šablon je třeba definovat na hodnotu, kterou potřebujete zobrazit. Obvykle na WWW stránkách zobrazujete data z databáze, případně i ty dále zpracované. K přiřazení hodnoty do proměnné ve Smarty slouží v PHP funkce assign a přímo v šalboně příkaz assign. PHP funkce má zápis $trida->assign('nazev',$hodnota), kde třída je autorem vytvořený třída Smarty (v příkladě z předchozího dílu je to $page), nazev je řetězec, pod kterým uvidíme proměnnou/pole/objekt v šabloně a $hodnota je proměnná, pole, nebo objekt, jehož hodnotu chceme přiřadit. Pokud je třeba definovat proměnnou přímo v šabloně, slouží k tomu příkaz {assign var=nazev value=hodnota}, ve které je var název proměnné, pod kterým bude tato přístupná dále v šabloně a value je hodnota, jakou bude mít.

Proměnné se zapisují stejným stylem, jako v "čistém" PHP, tj. uvozene znakem $ (string), vložení do stránky tedy provedete tedy pomocí {$nazev}. Pokud máme do $nazev přiřazeno pole, přistupujeme k jeho složkám přes "tečkovou notaci", například $nazev.clanek1.title, pokud se jedná o asociativní pole, nebo přes indexy v případě pole indexovaného $nazev[1][5] a nakonec k objektovým vlastnostem je stejný přístup, jako v PHP přes šipku, pomocí $nazev->prvni.

Smarty vývojářům poskytuje speciální asociativní pole $smarty, ve které jsou uloženy hodnoty superglobálních polí $_POST ($smarty.post), $_GET ($smarty.get), $_REQUEST, $_ENV, $_COOKIE ($smart.cookies), $_SESSION a $_SERVER, konstanty, které v PHP definujeme pomocí funkce define, několik dalších konstant definovaných přímo Smarty, mezi něž patří $smarty.now pro aktuální čas v unixovém formátu, $smarty.template s názvem aktuálně zpracovávané šablony, $smarty.version ve které uložená verze používaného Smarty a mnohé další související s některými funkcemi.

Smarty umí zpracovat i vložené proměnné v řetězcích. Pro tento případ platí stejná pravidla jako v PHP, tj. proměnné nesmí být v apostrofech (''), ale v normálních uvozovkách (""), pokud pouzijete hodnotu z asociativniho pole, musite celou "cestu" polem uzavrit do zpetnych apostrofu (na anglicke klavesnici pod klavesou Esc). Hodnota vkládané proměnné musí být známe před jejím vložením. Níže uvedený kód je ukázkou definování proměnné v šabloně, jejího vložení do nové proměnné a zobrazení této nově definované proměnné. Zároveň je do vkládané proměnné vložena nová hodnota, aby bylo zřejmé, že ta se nevkládá při zobrazení a zobrazena verze Smarty.

{assign var='number' value='prvni'}
{assign var='prom' value="Moje $number embeded promenna"}
{assign var='number' value='druha'}
{$prom}

Smarty engine version: {$smarty.version}

Vložená (embeded) proměnná může být definována nejen ve Vaší šabloně, ale i v PHP scriptu. Vložení hodnoty z pole se realizuje pomocí {assign var='nova' value="Moje `$pole.jmeno` pojmenovaná proměnná"}.

Při programování rozsáhlejších aplikací a ve větších šablonách jsou užitečným pomocníkem komentáře. Protože šablona je běžný html kód, lze použít HTML komentáře ve tvaru <!-- komentar -->, nebo komentáře poskytované Smarty systémem, které se zapisují {* smarty komentar *}

Smarty a EZ_SQL

Na serveru LinuxSoft.cz byl publikován popis objektového wraperu pro přístup k SQL databázím EZ_SQL. Kombinace těchto dvou knihoven funguje velice snadno. V níže uvedeném příkladě vybereme z článků podstatná data (id, datum zveřejnění, název, abstrakt a vlastní obsah), ale jen z těch článků, které mají povolené zobrazení. Následné zobrazení se realizuje v šabloně pomocí cyklu, které patří k řídícím strukturám probíraným později (nebude zde teď uvedena).

$page->assign('articles', $db->get_results('SELECT id, datum, title, '.
  'abstract, description FROM '.DBPREFIX. 'articles WHERE visible=\'yes\'',
  ARRAY_A));

Modifikátory

Smarty jsou nástrojem určeným primárně pro zobrazení již zpracovaných dat, které je ale občas nutné ještě přispůsobit k zobrazení, tzn. nahradit některé znaky, ostranit backslashe, zkrátit řetězce, upravit formát datumu, ... Modifikátory budou popsány abecedně, podobné modifikátory sloučím do jednoho bodu.

Způsob použití modifikátorů bude velice blízký lidem používajícím alespoň občas terminál v UN*Xových systémech. Zapisují se pomocí pipe (roury) stylem co|modifikator, například {$article.description|strip} znamená, že hodnota z pole $article['description'] je poslána ke zpracování příkazu strip a teprve výstup z této fenkce je poslán na výstup, který uvidí návštěvník v prohlížeči. V případě potřeby funguje u mofikátorů rozšířená syntaxe, kdy za dojtečku napíšete další, volitelné, parametry, zápis potom vypadá následujícím způsobem: {article.title|capitalize:true}. Pochopitelně lze modifikátory řetězit za sebe, kdy data z levé strany pipe jsou zpracována modifikátorem vpravo.

• capitalize - převede první písmena na verzálky (velká), přidáním true za modifikátor budou převedena na verzálky i první písmena skupin znaků obsahujících číslici.
• cat - připojení řetězce za původní, v tomto případě je parametr v podstatě povinný, protože udává obsah připojeného řetězce.
• count_characters - spočítá počet znaků ve vstupním řetězci. True hodnotou ve volitelném parametru je nastaveno počítání včetně tzv. bílých znaků (mezery, tabulátory, ...). Počítání znaků se neřídí jazykem, proto v českých/slovenských podmínkách bude 'ch' započítáno jako 2 znaky, ne jako jeden.
• count_paragraphs, count_sentences, count_words - počet odstavců, vět a slov, nemají volitelný parametr, oddělovač odstavce je '\n', neboli přechod na nový řádek.
• date_format - Nastavíte formát datumu a času. Nejčastěji bude vstupem údaj z databáze, nebo proměnné $smarty.now. Volitelné parametry by měly být dva. Prvním je formát datumu, udávaný stejným způsobem, jako u PHP funkce strftime(), druhým parametrem by měl být datum/čas, který bude jako defaultní pokud vlevo od pipe žádný nebude. Píšu měl by být, protože toto je věc, kterou snad každý trochu inteligentní programátor ošetří výchozí hodnotou již v databázi.
• default - pokud napravo od pipe nebude hodnota (proměnná je NULL), na výstup bude poslán obsah volitelného parametru
• escape - převedení do tvaru "bezpečného" pro výstup do WWW stránky, volitelný parametr má několik variant:
  • html - převod & " ' < >
  • htmlall - převod všech html entit
  • url
  • quotes - převod uvozovek a apostrofů
  • hex, hexentity - Převod nebezpečných znaků hexakódy znaků, ve druhém případě psané jako html entity. V tomto případě jsem se setkal s problémy, pokud bylo kódování modifikovaných dat v UTF-8
  • javascript - zapsání řetězce pomocí javascriptu, vhodné pro emaily
• indent - odsazení prvního řádku věty, modifikátor má dva volitelné parametry, první je počet znaků o které se odsadí (defaultně 4) a druhý udává znak, kterým bude provedeno odsasení (defaultně mezera, můžete zadat \t pro tabulátor, nebo například _ (podtržítko))
• lower, upper - převede text na minusky (malá písmena), nebo verzálky, bez volitelných parametrů
• nl2br - modifikátor ekvivalentní PHP funkci NL2BR(), sloužící k převodu znaku nového řádku (\n) na html tag <br />. Modifikátor nemá žádné parametry.
• replace - nahrazení jednoho řetězce druhým, volitelné parametry jsou dva - co nahrazujete a čím to nahrazujete
• regex_replace - nahrazení vzorku vyjádřeného v regulárním výrazu druhým volitelným parameetrem. Modifikátor je ekvivalentní PHP funkci preg_replace();
• spacify - Vložení znaku/řetězce mezi všechny znaky modifikovaného řetězce, volitelným parametrem můžete nastavit, jaký znak bude vkládán.
• string_format - formátování výstupu, používané typicky pro výstup desetinných čísel. Formátování se provádí stejným způsobem, jako u PHP funkce sprintf
• strip - nahrazení opakujících se mezer, odřádkování a tabulátorů jednou mezerou, případně znakem, který vložíme jako volitelný parametr
• strip_tags - vynechání všech html tagů, má jeden volitelný parametr, kterým je logická hodnota, defaultně nastavená na true. Pokud je ponechána ve výchozím nastavení je tag nahrazený mezerou, pokud je nastavena na false, je tag nahrazen prázdným znakem
• truncate - zkrácení textu na požadovaný počet znaků, který uvedete jako druhý volitelný parametr, jeho možné doplnění je realizovatelné pomocí druhého volitelného parametru, kde uvedete řetězec, kterým bude doplněn oříznutý text (například oblíbené ...) a poslední volitelný parametr je logická hodnota (defaultně false), kterou když nastavíte na true, povolíte zkrácení bez ohledu na pozici ve slově. Při false poslední slovo, do kterého vychází zkrácení, bude ponecháno celé
• wordwrap - zalámání řádků do výstupu, prvním volitelným parametrem nastavíte na kolikátem znaku má být řádek zlomen (výchozí je 80), druhým určíte řetězec, kterým bude zalámání provedeno, defaultní je \n a třetím zakážete (false), nebo povolíte (true) zalomení ve slově.

Několik příkladů na použití modifikátorů:

{* Definovani retezcu *}
{assign var='retez1' value='Toto je prvni retezec urceny pro'.
  ' priklad modifikatoru ve Smarty sablonach, x5'}
{assign var='retez2' value="'retezec' obsahujici i nejake nebezpecne znaky, napriklad <>"}
{assign var='retez3' value="<a href='http://www.linuxsoft.cz'>linuxsoft.cz</a>"}
{assign var='mail' value='ja@doma.server.cz'}

{* zpracovani pomoci modifikatoru *}
{$retez1}

{$retez1|capitalize}

{$retez1|capitalize:true}

{$retez1|cat:' a to je vse'}

{$retez1|count_characters}

{$retez1|count_characters:true}

{$retez4|default:'Tady nic neni'}

{$retez2|escape:html}

<a href="mailto:{$mail|escape:hex}">{$mail|escape:hexentity}</a>

{$retez1|replace:'Toto':'Hento'|upper}

{$mail|spacify:'_'}

{$retez1|truncate:15:'...':true}

{$retez1|truncate:15:'...'}

Výstupy z výše uvedených příkladů:

Toto je prvni retezec urceny pro priklad modifikatoru ve Smarty sablonach, x5

Toto Je Prvni Retezec Urceny Pro Priklad Modifikatoru Ve Smarty Sablonach, x5

Toto Je Prvni Retezec Urceny Pro Priklad Modifikatoru Ve Smarty Sablonach, X5

Toto je prvni retezec urceny pro priklad modifikatoru ve Smarty sablonach, x5 a to je vse

66

77

Tady nic neni

'retezec' obsahujici i nejake nebezpecne znaky, napriklad <>


<a href="mailto:%6a%61%40%64%6f%6d%61%2e%73%65%72%76%65%72%2e%63%7a">
&#x6a;&#x61;&#x40;&#x64;&#x6f;&#x6d;&#x61;&#x2e;
&#x73;&#x65;&#x72;&#x76;&#x65;&#x72;&#x2e;&#x63;&#x7a;
</a>

HENTO JE PRVNI RETEZEC URCENY PRO PRIKLAD MODIFIKATORU VE SMARTY SABLONACH, X5

j_a_@_d_o_m_a_._s_e_r_v_e_r_._c_z

Toto je prvn...

Toto je...

Závěrem

V tomto díle jsme se seznámili se syntaxí Smarty a s modifikací dat pro jejich výstup. Zároveň jsme si ukázali propojení Smarty a EZ_SQL, respektive jeho první polovinu, protože zobrazení dat přiřazených do pole budete moci udělat, až budete umět cykly. Příště se zaměříme na řídící struktury a právě zmíněné cykly a budete umět vše, co potřebujete pro základní použití Smarty šablon při vývoji Vašich WWW aplikací.