1.1 Účel

Účelom tohoto šablónovacieho framework-u (ďalej len software) je poskytnúť autorom PHP aplikácií nástroj, pomocou ktorého budú môcť jednoducho a efektívne implementovať šablónovanie do svojich produktov.

Software by mal poskytovať rozhranie pre nastavovanie obsahu, vygenerovanie a zobrazovanie konečného obsahu a správy cache pamäte.

1.2 Rozsah projektu

Software sa bude skladať s viacerých funkčných častí a nastaviteľnej adresárovej štruktúry.

Hlavnými časťami software budú objekty pre:

• generovanie obsahu,
• preklad html šablón (kompilátor),
• správa cache pamäťe.

Adresárová štruktúra software-u bude zahrňovať toto:

• adresár šablón v html formáte,
• adresár skompilovaných šablón,
• adresár cache súborov,
• adresár systémových pluginov,
• adresár použivatelských pluginov.

2.1 Perspektíva projektu

Tento software bude framework-om pre šablónovanie, anglicky template engine. Jeho cieľom je umožniť generovanie html výstupu aplikácie z html predlohy, šablóny, opatrenej značkami majúcimi špeciálny význam pre tento software.

Autor PHP aplikácie využívajúci tento software bude môcť zadefinovať aké dáta, ktoré predá software-u na spracovanie a špecifikovať šablónu, ktorú software zoberie ako predlohu, na základe ktorej vytvorí výsledný html dokument.

Autor PHP aplikácie bude tiež schopný nastaviť cache pre generátor obsahu, teda zadefinovať či sa má alebo nemá pri generovaní obsahu použiť cache pamäť, bude vedieť zadefinovať životnosť cache či odstraňovať cache pre všetky alebo špecifické súbory šablón.

Autor PHP aplikácie, ak to bude považovať za potrebné, bude vedieť rozšíriť značkový jazyk tohoto software-u pomocou pluginov.

2.2 Vlastnosti produktu

Základnou vlastnosťou tohoto software-u je prekladanie vytvorenej html šablóny do hotového html dokumentu na základe dát z aplikácie, ktorá tento software používa. Tohoto bude dosiahnuté za pomoci špeciálnej značkovej reči vnorenej v html dokumente predstavujúcom šablónu, ktorá bude schopná popisovať kde sa má zobraziť aká informácia a za akých okolností. Niektorá značky budú slúžiť na riadenie toku programu, respektíve riadenie toku generovania výsledného dokumentu, ďalšie budú pomocné, napríklad na striedanie hodnôt podla definície v cykloch, vytváranie premenných počas behu generátora výstupu, vkladanie pomocných funkcií (napríklad na generovanie rôznych ucelených častí html dokumentu) a podobne.

Všetky špeciálne značky v html šablóne budú pluginmi pre software. Tieto pluginy budú sústredené v adresároch, ktoré software alebo programátor PHP aplikácie za pomoci metód objektu tohoto software pridá do include_path. Pluginy budú naviac zaradené do menných priestorov, systémové pluginy budú vo východzom mennom priestore bez nutnosti jeho špecifikácie v tele šablóny. Ostatné pluginy zaradené v inom ako východzom mennom priestore, budú v html šablóne musieť byť asociované s nejakým aliasom, tento bude potom tvoriť ich predponu.

Generovanie výsledného výstupu bude môcť využívať cache pamäť, teda sa autor PHP aplikácie bude vedieť rozhodnúť, či danú šablónu a všetky podšablóny v nej špecifikované, bude software generovať vždy nanovo alebo ich software prečíta a zobrazí. Bude sa dať určiť dĺžka životnosti cache pre daný strom šablón (šablóna a všetky jej podšablóny) a tiež klúč k šablóne (respektíve identifikátor cache pre šablónu, napríklad pre každého používateľa aplikácie môŽe byť identifikátor iný). V tele html šablóny bude tiež možné špecifikovať časť kódu, v ktorej sa cache nebude brať do úvahy a táto časť sa bude vždy generovať aj ked bude zbytok dokumentu čítaný z cache (napríklad ak bude niekde v šablóne zobrazený súčasný čas, tak bude táto informácia takto označená).

Software bude rovnako poskytovať niekoľko metód na vytvorenie zoznamu cache súborov, súborov šablón a skompilovaných súborov šablón.

2.3 Použivateľské triedy a charakteristika

Vo všeobecnosti budú dve triedy používateľov, ktoré budú pracovať s týmto software-om.

1. programátor PHP aplikácie - ktorý implementuje tento software do kódu svojej aplikácie aby tak umožnil 2. triede používateľov vytvárať vzhlad výstupu so svojej aplikácie,
2. dizajnér alebo programátor PHP aplikácie - ktorý vytvorí šablóny vzhladu aplikácie, ktoré tento software následne bude pretvárať do finálnej podoby na základe dát od 1. triedy používateľov.

2.4 Operačné prostredie

Tento software bude primárne určený pre prostredie PHP 5.x, server Apache a operačné systémy Windows, Linux a Mac OS X.

2.5 Používateľská dokumentácia

Dokumentácia tohoto software bude sprístupnená na webovej stránke tohoto software do konca 4. etapy predmetu Ročníkový projekt.

3.1 1. etapa (9.12.2011)

Základy návrhu objektov software-u, pravdepodobne už funkčná syntaktická analýza a rozpracovaný kompilátor.

3.2 2. etapa (20.1.2012)

Kompilátor a niekolko základných pluginov (značiek) pre riadenie toku generátora výstupu. Cachovanie rozpracované alebo už funkčné.

3.3 3. etapa (dátum neznámy)

Cachovanie funkčné, API na správu cache a skompilovaných šablón, zostávajúce základné pluginy.

3.4 4. etapa (dátum neznámy)

Používateľský manuál na webe projektu, prípadne ďalžie pluginy (považované za základné - dodávané so software-om).

4.1 Popis značiek šablón

Kompilátor bude rozpoznávať nasledujúce značky:

• {#inštrukcia} - inštrukcia preprocesora, napríklad na vloženie inej šablóny na dané miesto, zrušenie prekladu iných značiek medzi dvojicou takýchto značiek preprocesora, vyňatie časti kódu z cache a pod.,
• {- komentár -} - komentár kódu, môže obsahovať viacej úvodných aj uzatváracích pomlčiek, toto označuje silu komentára (teda je možné zakomentovať komentár ...),
• {~konštanta} - do šablóny vypíše hodnotu konštanty,
• {$premenna;s:modifikator(parameter1, parameter2, ...);...} - vypíše hodnotu premennej do šablóny, ktorú je pred samotným výstupom možné modifikovať rôznymi modifikátormi,
• {s:funkcia(parameter1=hodnota1 parameter2=hodnota2)} - spustí funkciu swiftu na danom zozname parametrov a do šablóny vypíše výsledok,
• {f:funkcia(parameter1=hodnota1 parameter2=hodnota2)} - spustí funkciu definovanú v šablóne na danom zozname parametrov a do šablóny vypíŠe výsledok,
• <s:značka parameter1=hodnota1 parameter2=hodnota2 /> - skompilovatelná značka, nepárova, vloží do tela šablóny php kód, ktorý sa bude vykonávať v run-time,
• <s:značka parameter1=hodnota1 parameter2=hodnota2></s:značka> - skompilovateľná značka, párová, vloží do tela šablóny php kód, ktorý sa bude vykonávať v run-time.

4.2 Popis možných hodnôt v parametroch

Hodnotou parametrov pre modifikátory, funkcie a značky môžu byť takéto:

• číselná hodnota,
• premenná, začínajúca znakom $, na ktorú môžu byť aplikované ďalšie modifikátory,
• textový reťazec, buď ohraničený jednoduchou alebo dvojitou úvodzovkou (tieto majú rovnaký význam ako v php).

Reťazcová hodnota naviac môže byť:

• obyčajný text,
• definícia pola, ak text začína a končí znakmi zložených zátvoriek "{}", napríklad: "{0:'text', 1:$premenná, 2:3.14}", kde zápis je vo formáte kľúč:hodnota,
• výraz, ak text začína a končí znakmi obyčajných zátvoriek "()", napríklad: "($cislo <= 5 && $meno == 'Jozef')", ktorý je prevedený na php výraz, v týchto výrazoch sa ale nedajú používať funkcie php, treba používať modifikátory,
• hodnotu z funkcie, ak text začína a končí znakmi hranatých zátvoriek "[]", napríklad "[s:html.options(...)]", kde zápis funkcie je totožný so značkou pre zobrazenie výstupu z funkcie.

4.3 Príklad značiek

Preloženie značky výpisu hodnoty premennej. V šablóne bude vyzerať napríklad takto:

{$adresa['meno']}

Výsledok po skompilovaní:

<?php echo @$this->tpl_vars['adresa']['meno']; ?>

Preloženie značky pre výpis hodnoty funkcie. V šablóne bude vyzerať napríklad takto:

{s:cycler(values="hodnota1,hodnota2")}

Výsledok po skompilovaní:

<?php echo Sp_Function_SwiftDefault_Cycler::Run($this, array(), "hodnota1,hodnota2", 'default_cycler', ',', '', false); ?>

Preloženie skompilovatelnej značky. V šablóne bude vyzerať napríklad takto:

<s:trimcontent>Text medzi párovou značkou.</s:trimcontent>

Výsledok po skompilovaní:

<?php ob_start(); ?>Text medzi párovou značkou.<?php $result = ob_get_clean(); echo trim($result); ?>

4.4 Spracovanie šablón

Html kód šablón bude spracovávať kompilátor lexikálnym skenovaním znakov s občasným využitím regulárných výrazov.

Takmer každá štruktúra v kóde značiek je rekurzívna, preto nie je možné použiť klasické regulárne výrazi. Kompilátor bude obsahovať niekoľko metód, ktoré budú analyzovať konkrétne časti kódu, aku sú značky, parametre, modifikátory a pod., všetko na základe skenovania znakov v jednoprechodových cykloch.

Kompilátor bude mať implementované rozoznávanie, či je potrebné kód šablóny opätovne kompilovať, na základe porovnávania dátumu poslednej modifikácie súborov.

V prípade zapnutia cache, bude valídnosť cache súboru zamietnutá, ak bude kompilátor nútení prekompilovať šablónu.

4.5 Pluginy

Budú existovať spolu tri druhy pluginov:

• modifikátor premennej - základná trieda swiftPluginModifierAbstract,
• funkcia - základná trieda swiftPluginFunctionAbstract,
• značka - základná trieda swiftPluginCompilerAbstract.

Modifikátor aj funkcia majú spoločný predpoklad existencie verejnej statickej metódy Run. Pokial sa jedná o modifikátor, metóda Run musí obsahovať tieto parametre: Swift &$swift, $variable; kde prvý je referenciou na objekt Swift a druhý je hodnota premennej, ktorá bude modifikovaná. V prípade, že ide o funkciu, sú povinné parametre nasledovné: Swift &$swift, $additional_arguments; kde prvý je opäť referencia na objekt Swift a druhý je pole dodatočných argumentov funkcie. Tieto argumenty musia mať takéto názvy a musia byť prvými argumentami svojich metód.

Značka má tri povinné verejné metódy:

• compile_single - pre nepárovú značku, vyžaduje prvý parameter pole $additional_arguments, význam rovnaký ako pri funkciách,
• compile_pair_open - pre otváraciu párovú značku, vyžaduje prvý parameter pole $additional_arguments, význam rovnaký ako pri funkciách,
• compile_pair_close - pre zatváraciu párovú značku, vyžaduje prvý parameter pole $additional_arguments, význam rovnaký ako pri funkciách.

Všetky ďalšie parametre v týchto piatich metódach sú považované za parametre nastavitelné v šablóne, naviac tie, ktoré nemajú nastavenú východziu hodnotu, sú považované za vyžadované parametre aj v šablóne.

Trieda swiftPluginCompilerAbstract navyše obsahuje tieto chránené metódy:

• protected function _($code) - ktorá slúži na správne prevedenie hodnoty z parametra značky do výsledného php kódu, ktorý sa stane súčasťou šablóny,
• protected function _l($code) - slúži na prepísanie stringovej hodnoty na názov lokálnej premennej, vráti fatal error pokial reťazec neobsahje správny názov a zastaví vykonávanie celého programu,
• protected function _lr($code, $vars = array()) - v kóde výrazu prepíše všetky globálne premenná tak s názvami lokálnych premenných na lokálne premenné,
• protected function _lc($code, $scope_name = "", $additional_path = array()) - vytvorí a vráti kód globálnej premennej na základe názvu lokálnej premennej v formáte $this->tpl_vars['swift']['lokalna_premenna'][... pridavna cesta v poli],
• protected function _i($path = array()) - vytvorí a vráti kód vnútornej premennej (táto nie je zobraziteľná pomocou značky zobrazenia hodnoty premenej) na základe cesty v poli,
• protected function _a($expression) - vrati hodnotu pola, ktorá je vložená ako string (php zápis pola), vždy vráti pole, ak expression neobsahuje kód pola, vráti prázdne pole,
• protected function e() - vráti prídavné parametre pre chybovú správu,
• protected function s() - vráti kód premennej, nesúcej v skompilovanej šablóne informáciu o triede Swift, (tj. vracia hodnotu buď $this alebo $swift),
• protected function isVariable($code) - vráti true, ak je vstupný kód kódom premennej, inak vráti false.