Definice rozložení a osazení stránky (layout)

Pro tyto účely je datový slovník rozšířený o následující typy assetů:

Definice rozložení stránky

Definice rozložení stránky specifikuje možná rozložení obsahu, která budou nabídnuta správci obsahu. Touto definicí se pak řídí jedno nebo několik osazení stránky. Assety tohoto typu vytváří a spravuje autor prezentační logiky.

Osazení stránky

Samotná data jsou obsažena z části v osazení stránky, z části v jeho dětských assetech, kterými jsou datové zdroje pro osazení. Assety tohoto typu spravuje, nebo i vytváří autor obsahu.

Datový zdroj pro osazení

Tyto datové zdroje jsou doplňky rodičovského osazení. Editace těchto assetů je za normálních okolností před autorem obsahu skrytá, spravuje je prostřednictvím rodičovského osazení stránky.

Osazení stránky je z pohledu autora prezentační logiky stromová struktura. Uzly této struktury jsou čtyř typů:

Kořen

Je v každém osazení jeden. Je to typický vstupní bod pro výpis osazení. Při práci s assetem osazení v šabloně je dostupný jako jeho podhodnota root.

Oblast

Je obecný region, typicky funguje jako kontejner pro další uzly; lze ho také ale použít jako koncovou "značku", například pro výpis nějaké pevně dané šablony.

Alternativa

Je bod, ve kterém autor obsahu může zvolit jeden z dětských uzlů, který se má skutečně vypsat do stránky. Alternativa tedy umožňuje přepínání mezi různými způsoby rozložení obsahu ve stránce.

Placeholder

Je bod, který slouží primárně pro vložení seznamu libovolných assetů.

V definici layoutu jsou každému uzlu nastavené určité pevně dané vlastnosti: například ideální rozměry.

Každý typ vyjma placeholder může mít dětské uzly.

• V případě kořene je to vždy jeden dětský uzel.
• Dětské uzly oblasti se vypisují současně do jedné stránky, proto má u oblasti smysl mluvit o orientaci: vertikální (dětské uzly se v prezentaci řadí shora dolů), nebo horizontální (řadí se zleva doprava).

Každý typ může mít volně definovatelné parametry asociované s hodnotami.

Osazení stránky v principu kopíruje strukturu předepisovanou defincí rozložení stránky, nicméně je obohacené o další informace vložené autorem obsahu: hodnoty parametrů uzlů, assetový obsah placeholderů, zvolená dětská položka každé alternativy.

Rozložení stránky definuje XML dokument, který svou strukturou reprezentuje strukturu odpovídajících osazení, tzn. dětské uzly v osazení jsou v XML definici reprezentované dětskými elementy.

Kořenem dokumentu, reprezentujícím kořen osazení, je element LayoutDefinition v oboru http://www.etnetera.cz/jnp/layoutDefinition. Základní struktura definice je tedy následující:

<?xml version="1.0" encoding="UTF-8"?>
<LayoutDefinition
  xmlns="http://www.etnetera.cz/jnp/layoutDefinition">
    definice uzlu
</LayoutDefinition>

Oblast reprezentuje element Region:

<Region
    id="identifikátor uzlu"
  [ insite="(true | false)" ]
>
    vlastnosti a parametry uzlu
    definice jednotlivých potomků uzlu
</Region>

Alternativu reprezentuje element Alternative:

<Alternative
    id="identifikátor uzlu"
  [ insite="(true | false)" ]
>
    vlastnosti a parametry uzlu
    definice jednotlivých potomků uzlu
</Alternative>

Placeholder nemůže mít dětské uzly.

<Placeholder
    id="identifikátor uzlu"
  [ insite="(true | false)" ]
  [ dataId="identifikátor datového zdroje" ]
>
      vlastnosti a parametry uzlu
</Placeholder>

Hodnota atributu dataId se použije při generování názvu datového zdroje s obsahem placeholderu. Pokud není uvedena, použije se místo ní identifikátor uzlu.

Zatímco identifikátor uzlu musí být v celé definici unikátní, identifikátory datových zdrojů se mohou mezi placeholdery sdílet. Je tedy možné mít dva placeholdery, jejichž obsah definuje jeden a týž datový zdroj.

• Toto je užitečné zejména v případě, že jsou placeholdery obsažené v různých dětských uzlech jedné alternativy, tzn. alternativní rozložení mají týž assetový obsah.
• Další možné využití je v případech, kdy různé placeholdery používají různé prvky jednoho a téhož datového zdroje.

Každá z následujících vlastností se definuje XML elementem téhož jména:

title

Klíč do lokalizační mapy osazení nebo definice. Použije se v editoru osazení jako popis uzlu.

mode

Režim, ve kterém se uzel osazení vypíše při zpracování šablonou rozložení stránky.

css

CSS třídy pro prezentaci uzlu. Hodnota je dostupná při výpisu osazení, a je zcela na autorovi prezentační logiky, jak s ní naloží.

orientation

Hodnota horizontal nebo vertical. Rozhoduje o tom, jak se oblast bude prezentovat při editaci osazení stránky. Výpis by pochopitelně měl být postavený tak, aby tuto hodnotu respektoval.

width

Šířka prezentace uzlu; zapisuje se jako v CSS s tím, že jednotka je volitelná. Použije se primárně v prezentaci uzlu při editaci, ale je možné se na ni odvolávat i při výpisu.

height

Výška prezentace uzlu; zapisuje se jako v CSS s tím, že jednotka je volitelná.

multi

Může být uvedeno u placeholderu, udává maximální počet prvků.

V předchozí verzi se používala také vlastnost target umožňující definovat část šablony použitou při výpisu osazení formátovačem. Od verze 3.5 je sice tato funkčnost zachována, ale doporučuje se raději používat vlastní šablony definice rozložení a s tím související vlastnost mode.

Dále je možné definovat libovolné množství vlastních parametrů, syntax jejich definice je:

<parameter
  name="name"
  visible="( true | false )"
  editable="( true | false )"
  type="fqcn"
>default</parameter>

Hodnota name je jméno parametru, pod kterým je potom dostupný v šabloně při výpisu osazení. Viditelnost a editovatelnost parametru se vztahují k jeho chování při editaci osazení stránky. Hodnota fqcn je jméno třídy, jejíž insatncí má být hodnota parametru; defaultně je to java.lang.String. Hodnota default je serializovaná reprezentace defaultní hodnoty, pro Boolean například true nebo false.

Od verze 3.5 je preferovaný výpis osazení šablonami definovanými v definici rozložení stránky. Tyto šablony tvoří seznam pravidel podobný pravidlům formátovače; jen podmínky pravidla obsahují místo typu assetu typ vypisovaného uzlu. Podstatnou odlišností je volba režimu výpisu jednotlivých uzlů, která je jako vlastnost mode přímo součástí definice uzlu.

V každé aplikaci pravidla je aktuálně zpracovávaný uzel dostupný v proměnné _node; vedle toho je definovaná i proměnná _asset, jejíž hodnotou je asset osazení layoutu.

Vstup do zpracování osazení těmito šablonami začíná příkazem na výpis kořene osazení. Například z pravidla formátovače pro výpis osazení stránky voláním {_asset.root}.

root

Kořen osazení.

node$id

Uzel s identifikátorem id.

nodes

Kolekce všech uzlů osazení.

nodeType

Typ uzlu.

parent

Rodičovský uzel.

root

Pro kořen je toto uzel, který je v něm obsažený (typicky oblast nebo alternativa).

children

Uzly obsažené v uzlu. Výpis oblasti typicky zahrnuje iteraci přes tento seznam.

childCount

Počet dětských uzlů.

selectedChild

Aktuálně zvolený dětský uzel alternativy.

content

Pro placeholder je toto jeho obsah. S touto hodnotou je možné dále pracovat takto:

• Výpisem hodnoty content se zavolá formátovač pro datový zdroj obsahující položky placeholderu.
• Iterací přes content se přistupuje přímo k assetům obsaženým v placeholderu.
• content.next vrací následující prvek seznamu, nebo nic, pokud je datový zdroj vyčerpán; takto lze v šabloně postupně vybírat assety, pokud pořadí ve zdroji odpovídá pořadí v renderované stránce. Iterátor se resetuje vždy před začátkem renderování stromu osazení. Samozřejmě se předpokládá, že osazení nevolá samo sebe.
• content.list vrací seznam obsažených assetů, který lze dále zpracovávat funkcemi TFS.
• content[n] vrací n-tý prvek seznamu.
• content.asset vrací přímo datový zdroj, tedy obsahující asset. Zápis je možné použít, pokud je potřeba přístup k referenci (např. když je prvkem zdroje modul s parametry).

parameters

Uživatelsky definované parametry uzlu. Přístup k hodnotě parametru s názvem jméno_parametru je zápisem parameters.jméno_parametru.value.

width

height

orientation

css

Hodnoty převzaté ze shodně pojmenovaných vlastností uzlu.