Moduly

Modul je tedy zejména užitečný v situaci, kdy je třeba umožnit autorům obsahu vkládat fragmenty výpisu generované dynamicky (šablonou, pageletem) do textového materiálu, který spravují. Může to být proto, že modul zpřístupňuje nějaký externí obsah (z databáze apod.) nebo proto, že kód bude ve výsledku složitý a jeho správa by neměla být ponechána na autorech obsahu (například přehrávač videa).

Moduly mohou být definované buď programově (tedy programátorem), nebo dynamicky (assetem, který vytváří správce prezentační logiky). K druhé možnosti se váže většina následujícího popisu.

Modul může být v principu definovaný libovolným assetem, který může mít řídící třídu. V praxi půjde skoro vždycky o šablonu nebo pagelet.

Je třeba určit, že daný asset definuje modul a nastavit základní vlastnosti tohoto modulu.

• Že šablona nebo pagelet definuje modul, určuje řídící slovo jnp_module u příslušného assetu.
• Vlastnosti modulu definuje jeho desktriptor. Deskriptor je XML dokument, který se vkládá do nastavení Ovládácích tříd jako hodnota pole Společné parametry.

Minimální podoba deskriptoru má následující tvar:

<?xml version="1.0" encoding="UTF-8"?>
<ControlDescriptor xmlns="http://www.etnetera.cz/schemas/jnp/ControlDescriptor">
  <Description>
    <Name>module_name</Name>
    <Desc>module_desc</Desc>
    <Icon>module_icon</Icon>
  </Description>

  definice parametrů

</ControlDescriptor>

V tomto zápisu module_name je klíč pro překladové mapy, pod kterým je uložený název modulu; module_desc je klíč pro popis modulu; module_icon je název vlastnosti typu reference, jejímž cílem je asset s obrázkem zastupujícím modul.

Modul nemusí žádné parametry definovat, definice parametrů tedy může být prázdná

Od verze 3.5 je možné (a doporučuje se) používat rozšířený tvar XML dokumentu, který rozlišuje mezi moduly generujícími řádkový a blokový obsah. Specifikace je obsahem elementu DisplayMode.

Rozlišení je pro vizuální editor zásadní. Pokud má XML dokument zjednodušený tvar, předpokládá se, že modul generuje blokový výstup.

<?xml version="1.0" encoding="UTF-8"?>
<Module xmlns="http://www.etnetera.cz/schemas/jnp/ControlDescriptor">
  <DisplayMode>(inline|block)</DisplayMode>
  <ControlDescriptor>
    <Description>
      <Name>module_name</Name>
      <Desc>module_desc</Desc>
      <Icon>module_icon</Icon>
    </Description>

    definice parametrů

  </ControlDescriptor>
</Module>

Každý parametr modulu se definuje elementem TraitDefinition.

<?xml version="1.0" encoding="UTF-8"?>
<ControlDescriptor xmlns="http://www.etnetera.cz/schemas/jnp/ControlDescriptor">
  <Description>
	…
  </Description>
  <TraitDefinition>
	obsah definice prvního parametru
  </TraitDefinition>
  <TraitDefinition>
	obsah definice druhého parametru
  </TraitDefinition>
  …
</ControlDescriptor>

Každý parametr má unikátní identifikátor a jméno, popis a ikonu podobně jako samotný modul.

<TraitDefinition>
  <Id>param</Id>
  <Description>
	<Name>param_name</Name>
	<Desc>param_desc</Desc>
	<Icon>param_icon</Icon>
  </Description>

  popis možných hodnot parametru

</TraitDefinition>

Pro popis možných hodnot parametru je klíčový element Literalizer: definuje základní typ hodnoty. V šabloně pak je možné spoléhat na to, že hodnota je tohoto typu (pokud je nastavená). Pro některé typy určuje literalizér i prvek uživatelského rozhraní pro výběr hodnoty: například pro assety je to standardní pop-up používaný všude jinde v administraci.

Dalším elementem definice může být validátor – element Validator. Validátorů může být v jedné definici více – pak hodnota zadávaná autorem obsahu musí splňovat podmínky, které na ni klade každý z nich.

Pro text se správci obsahu nabídne jednořádkové vstupní pole. Pokud je potřeba víceřádkový vstup, lze toho docílit následujícím parametrem:

<Parameter name="area">true</Parameter>

Pro referenci a multireferenci lze přidat parametr omezující možný typ assetu uvedením názvu datové třídy; názvy datových tříd lze najít v datovém slovníku.

<Parameter name="assetType">název datové třídy</Parameter>

Definice parametru může obsahovat element Structure s jednou ze dvou různých hodnot: SCALAR (jednoduchá hodnota daného typu) a VECTOR (seznam hodnot výchozího typu).

Hodnota VECTOR není kompatibilní s literalizérem pro multireferenci.

Jednoduchá multireference a vektor jednoduchých referencí jsou datově reprezentovány stejně, liší se jen uživatelské rozhraní.

Výchozí hodnotu je možné uvést jako hodnotu elementu DefaultValue. Obsahem elementu je řetězcová reprezentace výchozí hodnoty (například pro číslo: jeho desítkový zápis).

Pokud je hodnota vektor, pak výchozí nastavení může být více hodnot; jejich řetězcové reprezentace se oddělují mezerou.

Pokud je třeba, aby autor obsahu vždy nastavil hodnotu parametru, lze toho docílit validátorem org.twinstone.tvm.validators.MandatoryValidator. S tímto validátorem je třeba vždy uvést element DefaultValue.

Zejména řetězce a čísla je často užitečné omezit na konkrétní výčet hodnot. Toto zajišťuje element DomainValues, který obsahuje seznam dětských elementů Value – každý reprezentuje jednu konkrétní hodnotu. Obsahem elementu je řetězcová reprezentace hodnoty; element má dále atribut name, jehož hodnotou je klíč pro překladové mapy, který se použije jako reprezentace hodnoty pro uživatele.

Seznam se správci obsahu reprezentuje jako HTML element select. S následujícím parametrem se bude prezentovat jako radio button:

<Parameter name="radio">true</Parameter>

Nabídku modulů je vhodné strukturovat jejich rozdělením do složek. Každá takové složka musí být v obsahové variantě systémová a mít nastavené řídící slovo jnp_module; v nabídce modulů se bude uvozovat svým titulkem; ten je tedy vhodné nastavit.

Pro připojení modulů se primárně používá vizuální editor. Ten sám zajistí vložení potřebného mark-upu, vytvoření referencí a nastavení jejich parametrů.

Lze ho také vložit manuálně. Reprezentace modulu v textu má odlišný tvar podle verze systému jNetPublish:

Verze 3.4:

<img class="jnp_module" src="jnpm:propname"/>

Verze 3.5:

<module type="(inline|block)" property="propname"/>

V obou případech propname je název vlastnosti typu reference, která odkazuje na asset definující modul. Verze 3.5 navíc obsahuje specifikaci typu generovaného obsahu.

(Vizuální editor tento mark-up někdy ještě obaluje jedním elementem div navíc. Této konvence je užitečné se držet i při manuálním vkládání, pokud je nějaká možnost, že text bude někdo někdy editovat také vizuálním editorem.)

Hodnoty vlastností modulu se nastavují buď z vizuálního editoru, nebo pomocí samostatného editačního rozhraní. Nastavení vlastností se provádí v editaci assetu s referencí na asset definující modul – bude to asset, který se při výpisu použije jako hodnota parametru jnprefs.

Tato akce je jedním z efektů použití parametru jnprefs.

Pokud má asset x vlastnost s názvem propname, jejímž cílem je asset definující modul, je možné v šabloně použít operátor ^; tedy psát x^propname pro přístup k referenci. Výsledkem vyhodnocení tohoto výrazu je reference na modul, kterou lze použít k vypsání modulu s nasatvenými parametry.

Assety definující moduly mohou být prvky seznamu definovaného výčtovým datovým zdrojem. V takovém případě jsou hodnoty jejich parametrů nastavitelné při editaci tohoto zdroje. Moduly je pak možné vypsat přístupem k vlastnosti reference, kterou mají assetové obálky dostupné v jednotlivých krocích iterace.

Vyhodnocuje se šablona modulu zcela standardním způsobem; jediný rozdíl je, že hodnoty parametrů nastavené pro daný výskyt modulu jsou v šabloně dostupné jako proměnné. Každý parametr je dostupný jako proměnná, jejíž název je daný hodnotou elementu Id v definici parametru.