Skip to content

RainTPL - Template Engine

RainTPL již není vyvíjen! Proto je vložen do core systému přímo a je upravovaný v rámci CMS pro vlastní potřebu.

Je to skvělý a hlavně jednoduchý systém šablon, který lze krásně ohýbat pro potřeby CMS, na rozdíl od vynikajícího Latte.

Základní příklad

Šablona index.tpl:

<!DOCTYPE html>
<html>
<head>
    <title>{$title}</title>
</head>
<body>
    {$content}
</body>
</html>

PHP kód:

$tpl = new Template();
$tpl->data('title', 'Moje stránka');
$tpl->data('content', '<h1>Vítej!</h1>');
echo $tpl->draw(__DIR__ . '/index.tpl');

Tagy a příkazy

{$proměnná} - Proměnné

Výstup dynamického obsahu šablony. Proměnné se nastavují metodou data().

Příklad: 

{$name}, jsem tvůj otec!

Výstup: 

Luke, jsem tvůj otec!

Přístup k polím a vlastnostem

{$array.key}         {* Prvek pole *}
{$object->element}   {* Vlastnost objektu *}

Modifikátory a operace

Matematické operace a funkce na proměnné:

{$a=1}
{$b=2}
{$sum=$a+$b}

{$title|cut:10}              {* Ořízne na 10 znaků *}
{$title|touppercase|cut:7}   {* Velká písmena, pak ořízne *}
{$value|Petrovo\String\cut:100}  {* Vlastní funkce *}
{$value|noescape}            {* Neuniká HTML *}

{#konstanta#} - Konstanty

Přístup ke konstantám definovaným v PHP:

{#URL#}
{#date('Y')#}
{#CONFIG['version']#}

{if="výraz"} - Podmínky

Kontrola výrazu a podmíněný výstup:

{if="$age<18"}
    Jsi mladistvý
{else}
    Jsi dospělý
{/if}

{loop="$pole"} - Cykly

Smyčka přes prvky pole nebo objektu:

<ul>
{loop="$weekday"}
    <li>{$key}, {$value}</li>
{/loop}
</ul>

Výstup: 

<ul>
    <li>0, Neděle</li>
    <li>1, Pondělí</li>
    ...
</ul>

Speciální proměnné v cyklu

{loop="$items"}
    {$key}      {* Klíč prvku *}
    {$value}    {* Hodnota prvku *}
    {$counter}  {* Počet iterací (od 0) *}

    {if="$counter == 5"} {break} {/if}     {* Ukončit cyklus *}
    {if="$counter == 3"} {continue} {/if}  {* Přeskočit iteraci *}
{/loop}

{function="funkce()"} - Funkce

Volání PHP funkce a výpis výsledku:

{function="date('Y-m-d')"}
{function="strlen($text)"}

Výstup: 

2024-10-16
42

{* komentář *} - Komentáře

Vše mezi {* a *} se ignoruje:

Ahoj {* {$name} co se děje? *} kamaráde?

Výstup: 

Ahoj kamaráde?

Alternativa s {ignore}: 

Text mimo ignorování
{ignore}
Tady se ignoruje {$var}
{/ignore}
Zase viditelné

{noparse} - Bez parsování

Obsah mezi {noparse} a {/noparse} se nekompiluje:

{noparse}
Toto je {$title} - nebude zpracováno
{/noparse}

Výstup: 

Toto je {$title} - nebude zpracováno

{autoescape="off"} - Escapování HTML

Standardně se HTML escapuje. Vypnout escapování:

{autoescape="off"}{$safe_variable}{/autoescape}
{$safe_variable|noescape}

Příklad: 

{autoescape="off"}<script>console.log('bezpečné')</script>{/autoescape}

Výstup: 

<script>console.log('bezpečné')</script>

Bez vypnutí escapování by výstup byl: 

&lt;script&gt;console.log('bezpečné')&lt;/script&gt;

Bezpečnost a ochrana

RainTPL v Petrovo CMS má zabudovanou ochranu proti nebezpečným operacím v šablonách.

Blocklist validátor

Všechny šablony jsou kontrolovány v průběhu kompilace prostřednictvím BlocklistValidator třídy. Blokovány jsou PHP funkce, které by mohly:

  • Provádět kód – eval, exec, system, shell_exec, atd.
  • Manipulovat souborovým systémem – unlink, rmdir, mkdir, file_put_contents, atd.
  • Přistupovat k síti – curl_exec, fsockopen, ftp_*, atd.
  • Odhalovat informace – phpinfo, php_uname, posix_getpwuid, atd.
  • Dynamicky volat funkce – call_user_func, call_user_func_array, forward_static_call, atd.
  • Manipulovat konfigurací – ini_alter, ini_get_all, parse_ini_file, atd.

Pokud se pokusíte použít blokovanou funkci, kompilace šablony selže s chybou:

Syntax eval not allowed in template: /path/to/template.tpl at line 42

Automatické escapování

RainTPL automaticky escapuje všechny proměnné pro bezpečnost proti XSS útokům. K escapování se používá ENT_QUOTES, což chrání i před útoky na HTML atributech.

Příklad:

{$user_input}

Pokud $user_input obsahuje <script>alert('XSS')</script>, bude vypsáno:

&lt;script&gt;alert('XSS')&lt;/script&gt;

Vypnutí escapování

Sometimes you need to allow safe HTML. Use |noescape modifier or {autoescape="off"} block:

{$html_safe|noescape}

{autoescape="off"}
{$html_safe}
{/autoescape}

⚠️ UPOZORNĚNÍ: Vypněte escapování POUZE pro obsah, kterému 100% věříte! Nikdy ne pro user input.

Bezpečné vs nebezpečné vzory

Bezpečné – automatické escapování: 

<h1>{$page_title}</h1>
<div class="{$css_class}">{$content}</div>

Bezpečné – explicitní noescape pro zařízené HTML: 

{$rendered_html|noescape}

Nebezpečné – dynamické generování kódu: 

{* ❌ NEVĚNUJTE SE TOMU – Blokováno! *}
{function="eval($code)"}
{function="call_user_func($callback)"}

Kontextové escapování

Důležité: HTML escapování není vhodné pro všechny kontexty. Pro JavaScript, URL nebo CSS buďte extra opatrní:

{* ✅ HTML kontext – bezpečné *}
<div title="{$user_title}">{$user_name}</div>

{* ⚠️ JavaScript kontext – escapování nestačí! *}
<script>
  var username = "{$user_name}";  {* Potřeba JSON escapování! *}
</script>

{* ⚠️ URL kontext – escapování nestačí! *}
<a href="search?q={$query}">Search</a>  {* Potřeba urlencode! *}

Doporučené řešení pro specifické kontexty:

{* JavaScript – použijte json_encode v PHP *}
<script>
  var userData = {function="json_encode($user_data)"};
</script>

{* URL – escapujte v PHP *}
{* Nastavte v controlleru: $tpl->data('safe_query', urlencode($query)) *}
<a href="search?q={$safe_query}">Search</a>

{* Atribut – HTML escapování stačí *}
<div data-config="{$config|noescape}">

Konfigurace

RainTPL se v CMS konfiguruje v metodě rainInit() v core/Template/BaseTemplate.php:

$config = [
    'tpl_dir'   => DIR . '/app/templates/',
    'cache_dir' => DIR . '/var/rain/',
    'tpl_ext'   => 'tpl',
];
Tpl::configure($config);

Poznámky

  • Proměnné jsou case-sensitive
  • RainTPL je součást CMS a je upravován pro vlastní potřebu
  • V moderních šablonách CMS se preferují vlastní tagy {T}, {+}, {S} nad RainTPL tagy
  • RainTPL slouží jako podklad pro finální renderování šablon