Šablonovací systém

Použitý šablonovací systém využívá upravený RainTPL 3 a CMS nadstavbu pro engine. Třída Template dědí z třídy BaseTemplate.

RainTPL

RainTPL je jednoduchý a snadno rozšiřitelný template engine. V našem CMS ho používáme pro: - Přiřazování proměnných do šablon ({$variable}) - Parsování .tpl souborů - Řetězení šablon a partiálů

Detailní popis všech RainTPL tagů a příkazů je v sekci RainTPL.

use Petrovo\Template\Template;

$tpl = new Template();
echo $tpl->draw(__DIR__ . '/templates.tpl', true);

Veřejné metody

• data() - přijímá název proměnné a její hodnotu, využívá interní metodu rainAssign() pro přiřazení této hodnoty proměnné
• draw() - bere název souboru šablony a určuje, zda je posledním krokem v řadě vykreslování
• drawString() - shodné s metodou draw(), ale místo názvu souboru šablony přijímá samotný řetězec šablony

Třídu je možné volat jen s přísnými typy, protože na začátku souboru se používá deklarace declare(strict_types=1);.

Metoda after

Lze ji rozšířit o další činnosti pro změnu výsledné šablony.

private function after(string $code, bool $last): string
{
    if ($last) {
        $code = HtmlBlock::make($code);
        $code = Translate::make($code);
        $code = Url::make($code);
        if (!defined('ADMIN') || !ADMIN) {
            $code = Image::make($code);
        }
        //$code = Conversion::back($code);
        if ($this->calls) {
            bdump($this->calls, 'Called tags ' . $this->handle);
        }
    }

    return $code;
}

Syntax tagů

Bloky {+ ...}

Přidá do šablony částečný kus kódu bloku (podšablonu).

{+ templates/_first-block}
{+ templates/_second-partial}

Pozn.: Bloky se načítají rekurzivně najednou, nezáleží na parametru step. Cesta je relativní k šabloně, která je vkládána do metody draw().

Nezobrazení {- ...}

K nezobrazení prvku šablony použijte znak mínus.

{- templates/second-partial}

Kostky {C ...}

HTML bloky nahradí zobrazení konkrétní kostky.

{C id:41 !page="page2" debug step="3" development}

Tento prvek zavolá tag T cubes/one id="41".

Překlady {S ...}

Prvek překladový řetězec (string). Spouští se až v konečné fázi parsování v metodě after(). Vše řeší core/Template/Translate.php.

{S Good Morning}
{S Testovací překladový | text}

Plurální překlady

{$piv=3;$alcohol='zelenou';}
{S Vypil ## a ### piv|{$alcohol}|{$piv}}

• ## - běžná náhrada
• ### - plurální varianta

Adresy {U ...}

Prvek (url) formátuje či konvertuje adresy URL. Spouští se až v konečné fázi parsování v metodě after().

{U /templates/second-partial}
{U /}
{U home}
{U /catalog}

Modifikátory stavu {@ ...}

Během vývoje byl požadavek na nekompilování. Např. při zobrazení šablony v administraci.

{@ NO_COMPILE_START}
{@ NO_COMPILE_END}

Má vazbu i na třídu Form, která používá a automaticky obaluje textarea dle yaml no_compile: 1.

Tagy {T ...}

PHP skripty (tagy). Běží každý sám za sebe a neovlivňují další tagy. Nesdílí s nimi proměnné.

{T directory/file}
{T languages/hreflangs step="2" parameter="value"}

Podmíněné parametry (Conditional Parameters)

Tagy podporují parametry, které řídí, kdy se tag spustí:

Pagační parametry: - page="page1,page2" - Tag se spustí POUZE na specifikovaných stránkách - !page="page1,page2" - Tag se NESPUSTÍ na specifikovaných stránkách - Priorita: page má přednost před !page

Prostředí parametry: - production - Tag se spustí POUZE v produkčním prostředí (APP_ENV=prod) - development - Tag se spustí POUZE ve vývojovém prostředí (APP_ENV=dev) - !production - Negace production - !development - Negace development

Krokování (Compilation Steps): - step="2" - Tag se spustí až v kroku kompilace #2 (defaultně krok 0)

Ostatní: - iff="functionName('arg')" - Tag se spustí POUZE pokud vrátí funkce true - debug - Tag se zobrazí v HTML komentáři i v produkci (pro debugging)

Příklady:

{T my-tag page="home"}                          <!-- Pouze na home -->
{T my-tag !page="admin,settings"}               <!-- Všude MIMO admin a settings -->
{T my-tag production}                           <!-- Pouze v produkci -->
{T my-tag development}                          <!-- Pouze ve vývoji -->
{T my-tag step="2"}                             <!-- V kroku #2 a později -->
{T my-tag page="home" development step="1"}     <!-- Kombinace: home STRÁNKA + VÝVOJ + krok 1+ -->
{T my-tag iff="isAdmin()"}                      <!-- Pokud isAdmin() vrátí true -->

Logika zpracování (viz BaseTemplate::isValidPageParams()):

1. Pokud je page="" a !page="" → tag se spustí
2. Pokud je page vyplněn → musí obsahovat aktuální PAGE konstantu
3. Pokud je !page vyplněn a page="" → PAGE NESMÍ obsahovat
4. Pokud production/development nesedí → tag se nespustí
5. Pokud iff="func()" vrátí false → tag se nespustí

Proměnné vstupující do tagu

• $handle (string) - cesta k tagu
• $params (array) - parametry tagu (zadané ve složených závorkách v šablonách)
• $BOX (object) - sdílený kontejner mezi tagy
• $calls (array) - pole spuštěných tagů (jen při vývoji)

Pokud je třeba proměnná $_CMS, je třeba ji definoval globálně v tagu pomocí global $_CMS.

Základ tagu s výpisem pomocí šablony

declare(strict_types=1);

use Petrovo\Template\Template;

$params = $params ?? [];
$BOX = $BOX ?? (object)[];

$tpl = new Template();
$tpl->data('variable', 'value');
echo $tpl->draw(__DIR__ . '/tagTemplate.tpl');

Metody draw() a drawString()

Do draw() vstupuje cesta tpl šabloně a do drawString() textový obsah šablony. Obě mají druhý parametr (bool) $last, určující, zda-li je to poslední výstup z kompilování šablony a je třeba spustit metodu after().

• true - nastaveno v základním spuštění v bootstrap.php a pak všude, kde se požaduje finální výstup
• false - v tagu třeba, vyřeší ho globální šablona

Dočasné prvky (deprecation)

• H (HTML bloky) - bude odstraněno, používejte {+ partial}
• B (bloky) - nahrazeno {+ partial}
• V (proměnné) - odstraněno

Assets

Systém bude dále řešit vkládání obrázků a souborů.