Page tree
Skip to end of metadata
Go to start of metadata

View je aplikační vrstva, která zajišťuje ve Vivu vyrenderování HTML šablon (twig, smarty, phtml) na výstup. Od verze Vivo 2.0 je doporučeno, aby se pro generování výstupu používal šablonovací systém. Ve Vivu je podpora pro tyto šablonovací systémy:

Jací hráči jsou při renderování view ve hře?

  • UI komponenta [Vivo\UI\Component]
    • klasická Vivo UI komponenta, jejíž šablona se má vyrenderovat na výstup
  • viewTemplate [Vivo\View\AbstractViewTemplate]
    • objekt, který zobecňuje šablonovací systém
  • helperLoader [Vivo\View\AbstractHelperLoader]
    • objekt, který umožňuje globální deklaraci "view helperů"

Vivo\UI\Component::$view

Zpracování šablony má na starosti metoda Vivo\UI\Component::view(), jejíž chování silně závisí na obsahu proměnné Vivo\UI\Component::$view.
Tato proměnná může obsahovat buď:

  • callback (funkce, která vypisuje výstup)
  • absolutní cestu k šabloně
    • s uvedenou příponou
    • bez uvedené přípony DD + TED
  • relativní cestu k šabloně bez uvedené přípony (vůči APP_DIR/view nebo MODULE_DIR/viewDD + TED
  • null (z namespace UI komponenty se vytvoří relativní cesta a ta použije pro hledání souboru šablony - viz. předchozí případ) DD + TED

Zkratky (DD a TED) jsou vysvětleny v následujícím textu.

Detekce zařízení (Device detection) DD

Pomocí mechanismu detekce zařízení Vivo automaticky použije soubor šablony templatePath[-<DEVICE_NAME>]. Aby tento mechanismus zafungoval musí Vivo\UI\Component::$view obsahovat cestu bez uvedené přípony nebo null. Zařízení je definováno v proměnné Vivo\Http\Request.

Detekce šablonovacího systému (Template engine detection) TED

Pomocí tohoto mechanismu je možné řídit prioritu jednotlivých šablonovacích systémů. Tento mechanismus dovoluje daný šablonovací systém i úplně zakázat. Ve Vivu je konfiguračně definována výchozí priorita následovně:

  1. Twig (šablony s příponou .twig)
  2. Smarty (šablony s příponou .tpl)
  3. Phtml (šablony s příponou .phtml)

Pokud je ve uvedena cesta bez uvedené přípony, Vivo se pokusí na uvedené cestě nalézt soubory šablon s příponami v uvedeném pořadí. Pokud je soubor nalezen, je pro danou příponu (potažmo šablonovací systém) nejprve vytvořen objekt viewTemplate a poté zavolána metoda Vivo\View\AbstractViewTemplate::display(), což způsobí vyrenderování šablony na výstup. Pokud není soubor šablony nalezen nebo dojde-li při renderování výstupu k výjimce, pokusí se Vivo “fallbackout” na další šablonovací systém, který je v pořadí.

Co je viewTemplate?

ViewTemplate je objekt - wrapper nad konkrétním šablonovacím systémem.

Fakta o viewTemplate

  • je potomkem třídy Vivo\View\AbstractViewTemplate
  • instance viewTemplate je k dispozici v každé UI komponentě
  • odstiňuje programátora od konkrétní implementace šablonovacího systému a unifikuje přístup k němu
  • k šablonovacímu systému se při renderování přistupuje výhradně skrze object viewTemplate
  • o instanciaci viewTemplate se stará aplikační objekt se jménem viewTemplateFactory [Vivo\View\ViewTemplateFactory] na žádost UI komponenty ve view fázi Vivo requestu

Vytváření viewTemplate

Vytvoření instance viewTemplate je poněkud složitější proces, proto se o jeho vytvoření stará factory třída. Solution developer je od vytváření viewTemplate zcela odstíněn. Vytvoření viewTemplate je pevnou součástí životního cyklu Vivo requestu. Vytvoření viewTemplate obnáší (informativně):

  • instanciaci šablonovacího systému
  • nastavení include path pro šablonovací systém (aplikace + všechny Vivo moduly)
  • nastavení cache adresáře

Klíčové public API viewTemplate

  • Vivo\View\AbstractViewTemplate::addFilter($name, $callable)
    • registrace filteru
    • typické použití v šabloně přes “pípu”: {$var|myFilter}
  • Vivo\View\AbstractViewTemplate::addFunction($name, $callable)
    • registrace funkce, která generuje nějaký výstup
    • typické použití v šabloně: {myFunction($param1, $param2)}
  • Vivo\View\AbstractViewTemplate::addProperties(array $properties)
    • registrace seznamu proměnných, které jsou dostupné v šabloně
    • typické použití: {$myProperty}

Jak viewTemplate používat?

Solution developer potřebuje interagovat s viewTemplate objektem, potřebuje-li v šabloně UI komponenty použít:

  • custom filter
  • custom funkci
  • custom property

Přístupový bod k objektu viewTemplate je prostřednictvím metody Vivo\UI\Component::beforeView($viewTemplate):

 

class MyComponent extends Vivo\UI\Component 
{
    public function beforeView(AbstractViewTemplate $viewTemplate) 
    {
        parent::beforeView($viewTemplate); // always call parent!!
        $viewTemplate->addFunction('myFunction', $myFunction); // function 'myFunction' will be available in component's template
    }
}

 

Metoda beforeView tedy umožňuje definovat filtry, funkce a property (proměnné) na úrovni konkrétní UI komponenty. Častěji je ale potřeba definovat “globální” filtry, funkce a property, které jsou k dispozici v šabloně všech UI komponent. Toho lze docílít pomocí mechanismu helperLoaderů.

Co je helperLoader?

Helper loader je objekt, pomocí kterého lze definovat “globální” filtry, funkce a property, které budou dostupné v šablonách všech UI komponent. Ve Vivu může být registrováno neomezené množství helperLoaderů.

Fakta o helperLoaderech

  • helperLoader komunikuje s objektem viewTemplate pomocí tří metod
    • getFilters()
    • getFunctions()
    • getProperties()
  • každá z výše uvedených metod musí vracet VŽDY jednodimenzionální asociativní pole ve tvaru [<name> => <helperEntity>]
    • kde <name> je jméno, pod kterým bude daná <helperEntity>, tedy filtr, funkce či property k dispozici v šabloně
  • helperLoader je implementován vždy pro konkrétní šablonovací systém
  • všechny helperLoadery jsou instanciovány až při konstrukci viewTemplate
  • v jádru Viva je implementován helperLoader (jménem ‘vivo’), který obsahuje výchozí sadu filtrů, funkcí a properties

Výchozí nastavení

Aniž by bylo nutné registrovat jakýkoliv helperLoader, je možné využívat funkcionality vivo helperLoaderu:

  • filtry
    • format
  • funkce
    • entityLink
    • dump
    • message (alternativně __)
  • properties
    • config
    • request
    • principal

Příklad v Twigu

 

{{dump(myVar)}}

 

Příklad ve Smarty

 

{dump value=$myVar}

 

Konfigurace View

 

view:
    helper_loaders: # helper loader declaration
        twig: # template engine
            vivo: Vivo\View\Twig\HelperLoader # registration of 'vivo' template loader for Twig (taken from module.yml)
            demo: Demo\View\Twig\HelperLoader # registration of custom 'demo' helper loader
        smarty:
            vivo: null # removing of default 'vivo' helper loader for Smarty (do not do that)
    order: [twig, tpl, phtml] # order of template engines (first Twig, second Smarty, ...)
    throw_exceptions: false # false is default
Example

Implementace helperLoaderu pro project VivoDemo:

// in APP_DIR/src/VivoDemo/View/Twig/HelperLoader.php
namespace VivoDemo\View\Twig;

use Vivo;

class HelperLoader extends Vivo\View\AbstractHelperLoader
{

    public function getProperties() 
    {
        return ['fooVar' => 'text'];
    }

    public function getFilters() 
    {
        return ['fooFilter' => [$this, 'fooFilterInTwig']];
    }

    public function fooFilterInTwig($value) 
    {
        return sha1($value);
    }
}

a jeho registrace v globálním konfiguračním souboru aplikace

 

# in APP_DIR/config/global.yml
view:
    helper_loaders:
        twig:
            demo: VivoDemo\View\Twig\HelperLoader

použití filtru v šabloně:

# in template of UI component

{{ahoj|fooFilter}}

 

 

Tipy a doporučení

  • seznam všech registrovaných helperLoaderů je možné zjistit po rozkliknutí aplikačního objektu s názvem viewTemplateFactory v DI panelu pro Tracy
  • pro lepší odhalování chyb v šablonách (např. syntaktických) někdy pomůže zapnutí vyhazování výjimek
view:
    throw_exceptions: true

  • No labels