Dokumentace aktualizována pro verzi 1.2
JoresTemplate je PHP třída, umožňující správu, zpracování a zobrazení šablon. Myšlenka je založena na zkušenostech s jinými šablonovacími systémy, zejména FastTemplate. FastTemplate se oproti jiným, rozsáhlým šablonovacím systémům (jako například Smarty) zaměřuje na jednoduchost a rychlost zpracování.
Má však i nevýhody: jeho možnosti jsou někdy až příliš omezené; i u jednodušších šablon lze narazit na problémy, které je třeba nepohodlně obcházet a věci, které by se daly elegantně vyřešit v šabloně, je třeba generovat pomocí PHP. Další nevýhoda je, že kód není udržován a poslední aktualizace je z roku 1999.
Vznikla tedy myšlenka napsat nový šablonovací systém, podobně jednoduchý a rychlý jako FastTemplate, ale s většími možnostmi.
Výsledkem je JoresTemplate. Je založen na jediném PHP skriptu, obsahujícím jedinou třídu. Samotný kód je dokonce ještě menší, než FastTemplate (soubor je sice větší, ale to je způsobené rozsáhlým komentářem s popisem protokolu třídy), přesto nabízí větší možnosti- na rozdíl od FastTemplate lze například v šabloně direktivou vložit jinou šablonu, velice užitečný je podmíněný blok (blok, který se zobrazí podle hodnoty určité proměnné), je možné si do šablony psát komentáře, které nebudou ve výsledné stránce vidět, a další věci.
Celkově je třída JoresTemplate postavená na myšlence co největšího oddělení prezentační logiky (samotného obsahu stránky) a aplikační logiky (PHP skriptů)
I přes rozšíření možnosti si JoresTemplate zachovává dobrou rychlost generování: podle autorových vlastních testů je pro jednoduché šablony (prosté nahrazování proměnných) mírně pomalejší než FastTemplate, ale pro složitější šablony (dynamické bloky apod.) rychlost neklesá tolik jako u FastTemplate, takže pro složité šablony je naopak JoresTemplate výrazně rychlejší.
Použití v šablonách
JoresTemplates zpracovává následující konstrukce:
- {PROMENNA} Proměnná v šabloně. Voláním metody assign("PROMENNA","text") je možné proměnnou nahradit libovolným textem.
Nepřiřazené proměnné šablonovací systém ignoruje, neodstraňuje. Pokud tedy nemá na daném místě výsledné stránky být nic, je třeba proměnné přiřadit prázdný řetězec: assign("PROMENNA","") - Tato konstrukce vloží do šablony jinou šablonu ze souboru daného jména. V případě chyby (například neexistující soubor) systém uloží chybovou hlášku do $this->errors a v režimu ladění i vypíše na obrazovku.
Šablona se také nevloží, pokud by to způsobilo nekonečný cyklus, tj. nelze vložit šablonu, do které by se při jejím zpracování měla vložit aktuální šablona. - <!-- JTPL: COMMENT: (...) --> Komentář.
Direktiva bude při zpracování odstraněna a nebude viditelná na výsledné stránce.
Komentář je užitečný například pro poznámky k čemu daná šablona slouží a podobně. Na rozdíl od použití klasických HTML komentářů není tento komentář viditelný ve zdrojovém kódu výsledné stránky. - <!-- JTPL: IF PROMENNA [[NOT] EMPTY] ID: id_bloku --> anebo <!-- JTPL: IF PROMENNA [NOT] = "řetězec" ID: id_bloku --> (kód při splnění podmínky) <!-- JTPL: ELSE: id_bloku --> (kód při nesplnění podmínky- volitelný blok) <!-- JTPL: ENDIF: id_bloku --> Podmíněný blok.
Kód uvnitř podmíněného bloku se zpracuje a přidá do výsledné stránky pouze v případě, že je splněna zadaná podmínka. Část ELSE byla přidána ve verzi 1.2 a zpracuje se v případě, že podmínka splněna není. Část ELSE je volitelná, tzn. blok ji nemusí obsahovat. Podmínka obsahuje proměnnou šablony (jako všechny ostatní proměnné je možné její hodnotu použít i jinde v šabloně přes {PROMENNA} a nastavuje se metodou assign). Konstrukce podmínky je následující:
IF PROMENNA EMPTY je splněno v případě, kdy se proměnná v PHP považuje za prázdnou, tj. funkce empty() vrátí hodnotu true.
IF PROMENNA je totéž jako IF PROMENNA NOT EMPTY a je splněno v případě, kdy pro danou proměnnou PHP funkce empty() vrátí false.
IF PROMENNA = "řetězec" je splněno v případě, že hodnota určené proměnné se rovná danému řetězci (bere v úvahu i velikost písmen).
IF PROMENNA NOT = "řetězec" je splněno v případě, že hodnota určené proměnné není rovná danému řetězci (bere v úvahu i velikost písmen).
Hodnota ID: může být libovolný řetězec obsahující písmena bez diakritiky, čísla, pomlčky a podtržítka. Slouží ke spárování počátku a konce podmíněného bloku.
Každý podmíněný blok musí být ukončen direktivou ENDIF s ID bloku odpovídajícím počáteční direktivě. Od verze 1.2 v případě, že JoresTemplate narazí na direktivu IF, kterou nedokáže zpracovat zapíše chybu do seznamu chyb a direktivu IF nahradí textem: <!-- JTPL ERROR --> (pouze samotnou direktivu, žádný další obsah).
Podmíněné bloky je možné vnořovat do sebe navzájem i do dynamických bloků (viz níže). - <!-- JTPL: START BLOCK: id_bloku --> (...) <!-- JTPL: END BLOCK: id_bloku --> Dynamický blok.
Slouží pro části kódu, které opakují, například při generování seznamů nebo tabulek. Blok je třeba nejdříve registrovat metodou register_block. Poté se přiřadí proměnné a blok se zpracuje metodou parse_block(). Po zpracování bloku lze proměnným znovu přiřadit hodnoty a blok opět zpracovat, což výsledný kód připojí k předchozímu.
Protokol třídy
- JoresTemplate($tpldir) konstruktor. Parametrem je adresář se šablonami
- debug([$debug]) Nastaví režim ladění. true = zapnuto, false = vypnuto. Výchozí hodnota parametru je true.
Při vypnutém režimu ladění se chybové hlášky pouze ukládají do pole $this->errors, při zapnutém ladění se hlášky také vypisují do výstupu.
Ve výchozím nastavení je režim ladění vypnutý. - tpl_exists($name) Od verze 1.2. Zjistí, zda šablona daného jména existuje. Vrací true, pokud šablona existuje, false pokud neexistuje.
- flush_errors() Od verze 1.2. Smaže zaznamenané chyby.
- register_tpl($templates) zaregistruje šablonu/šablony.
Parametrem metody je pole ve tvaru název=>soubor, kde soubor je jméno souboru se šablonou a název je zvolený název šablony, přes který se pak lze na šablonu odkazovat Metodu register_tpl je třeba volat před začátkem práce se šablonou. Při úspěšném nastavení vrací metoda true, jinak false - register_block($tpl_name,$block_name) zaregistruje blok v šabloně. Parametry jsou název šablony a název bloku.
Blok musí být v šabloně ohraničen těmito zápisy:
- začátek bloku: <!-- JTPL: START BLOCK: nazev_bloku -->
- konec bloku: <!-- JTPL: END BLOCK: nazev_bloku -->
nazev_bloku lze nahradit libovolným názvem, který může obsahovat písmena bez diakritiky, čísla a podtržítko
Podařilo-li se blok zaregistrovat, vrátí metoda true, v opačném případě false a přidá chybu do $this->errors. V režimu ladění se hláška i vypíše.
Při zpracování šablony metodou parse je neregistrovaný blok zpracován jako běžný kód stránky: počáteční a koncová značka bloku se objeví ve výstupu, proměnné s přiřazenou hodnotou budou nahrazeny.
U registrovaného bloku jsou z výstupu odstraněny značky počátku a konce bloku; samotný obsah bloku lze ovlivnit voláním remove_block a parse_block.
Není-li ani jedna z těchto metod pro daný blok před zpracováním celé šablony zavolána, vypíše se obsah bloku jako běžný kód s nahrazením proměnných s přiřazenou hodnotou.
Metoda vrací true při úspěšné registraci bloku, v opačném případě vrací false a nastavuje (v režimu ladění i vypisuje) chybovou hlášku do $this->errors - remove_block($tpl_name,$block_name,[$text])Vymaže veškerý obsah zaregistrovaného bloku v příslušné šabloně anebo ho nahradí zadaným textem.
Parametry jsou název šablony a název bloku. Pokud je vyplněn parametr $text, bude obsah bloku nahrazen tímto textem.
Voláním této metody se smaže výstup případných dřívějších volání metody parse_block() pro tento blok.
Metoda nezjišťuje chyby (jako například neexistenci zadaného bloku) a nevrací hodnotu. - assign($varname,$text)Přiřadí hodnotu proměnné. Parametry jsou jméno proměnné (bez složených závorek) a hodnota.
Proměnné s přiřazenou hodnotou se při zpracování šablony metodou parse nebo parse_block ze šablony odstraní a na jejich místo se dosadí přiřazená hodnota.
Přiřazení se vztahuje na všechna následující volání parse a parse_block pro jakoukoliv šablonu či blok, obsahující proměnnou daného jména! - multi_assign($var_array)Přiřazení hodnot více proměnným. Parametrem je pole položek proměnná=>hodnota.
Tuto metodu lze s výhodou použít, jestliže by bylo nutné volat vícekrát za sebou assign() - parse_block($tpl_name,$block_name)Zpracuje zadaný blok. Parametry jsou název šablony a název bloku.
Metoda zpracuje zadaný blok v šabloně (nahradí proměnné a provede direktivy) na HTML kód. Tento kód se vloží do šablony na místo bloku.
Při volání metody vícekrát pro tentýž blok se šablona vždy znovu zpracuje a výstup se připojí na konec předcházejícího výstupu.
Opakovaným voláním lze vytvořit opakující se výstup, například řádky tabulky. Nejdříve naplníme proměnné pomocí assign(), následně zavoláme parse_block(), v další iteraci opět assign() s novými hodnotami a opět parse_block()
V případě chyby uloží hlášku do $this->errors (v režimu ladění i vypíše) a vrací false, v případě úspěšného zpracování vrací true - parse($name)Zpracuje šablonu. Parametrem je název šablony.
Tato metoda se volá po nastavení všech hodnot v šabloně a provede závěrečné zpracování dané šablony na HTML kód.
Výstupem metody je výsledný HTML kód. Tento kód lze případně voláním assign() přiřadit nadřízené šabloně.
Metoda vrací výsledný HTML kód; v případě chyby uloží hlášku do $this->errors (v režimu ladění i vypíše), ale pokusí se pokračovat ve zpracování šablony