Skip to content

Š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(string $handle, bool $last = false, ?string $lang = null) – Vyrenderuje šablonu ze souboru

  • $handle - cesta k .tpl souboru
  • $last - true pokud je to poslední krok v řadě vykreslování (spustí after() s post-processing)

  • $lang - (volitelně) jazyk pro renderování šablony. Pokud není zadán, použije se LANG konstanta

  • drawString(string $handle, bool $last = false, ?string $lang = null) – Stejné jako draw(), ale místo názvu souboru přijímá řetězec šablony

  • $lang - (volitelně) jazyk pro renderování

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);.

Dynamický jazyk ($lang parametr)

Parametr $lang umožňuje vyrenderovat šablonu v libovolném jazyce, aniž by se změnila globální konstanta LANG. Výchozí chování zůstává zachováno – pokud není parametr zadán, použije se LANG.

Příklady:

use Petrovo\Template\Template;

$tpl = new Template();
$tpl->data('user_name', 'John');

// Použije výchozí LANG (např. 'cs')
echo $tpl->draw('/app/templates/email.tpl', true);

// Vyrenderuje v německém jazyce, i když LANG='cs'
echo $tpl->draw('/app/templates/email.tpl', true, 'de');

// Vyrenderuje šablonu jako řetězec v angličtině
echo $tpl->drawString('{S Hello}, {$user_name}!', true, 'en');

Praktické použití – email v cizím jazyce:

// V controlleru máte aktuálně nastaveno LANG='cs',
// ale potřebujete poslat email uživateli s jazykem 'de'
$tpl = new Template();
$tpl->data('user_name', $user['name']);
$tpl->data('action_url', $actionUrl);

// Vyrenderuje email v němčině
$emailContent = $tpl->draw('/app/templates/email/notification.tpl', true, 'de');

// Pošle email
mail($user['email'], $emailSubject, $emailContent);

Jak to funguje na pozadí:

$lang se propaguje skrz všechny post-processing etapy:

  • HtmlBlock::make() – používá $lang pro filtrování bloků podle jazyka
  • Translate::make() – používá $lang pro překladový cache a získávání překladů
  • Url::make() – používá $lang pro generování URL s jazykovým prefixem

Backward compatibility:

Všechny existující volání zůstávají funkční – $lang je zcela volitelný:

// Stará volání fungují jako dřív (fallback na LANG)
$tpl->draw($file, true);                    // Funguje
$tpl->drawString($str, false);              // Funguje

// Nová volání s $lang parametrem
$tpl->draw($file, true, 'de');              // Nové
$tpl->drawString($str, true, 'en');         // Nové

Metoda after

Lze ji rozšířit o další činnosti pro změnu výsledné šablony. Metoda se volá v draw() / drawString() s parametrem $lang, který se propaguje do všech post-processoru.

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

    return $code;
}

Parametr $lang je optional – pokud není zadán, všechny post-procesory použijí globální LANG konstantu.

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ů.