Úvod » Vlastnosti systému jNetPublish

Symbolické odkazy v řetězcích

Řetězce, které obsahují HTML značky, mohou obsahovat symbolické reprezentace fragmentů, které je třeba generovat dynamicky. Nejčastěji jsou to URL odkazů na jiné assety v rámci jedné instance systému jNetPublish.

Tyto symbolické reprezentace se vytvářejí z části pomocí vizuálního editoru, z části se dogenerovávají automaticky při uložení assetu, který řetězec obsahuje. Je možné je také vytvořit manuálně (spolu s příslušnými vlastnostmi a ortogonálními odkazy assetu); pro běžného autora obsahu by ale takový postup byl příliš obtížný.

Při výpisu takových řetězců šablonou je potřeba použít hodnotový parametr výpisu jnprefs. Hodnotou parametru musí být asset. Smysl jeho použití bude popsán dále.

Co se v řetězci nahrazuje

Symbolické reprezentace URL: URL odkazů na assetový obsah v rámci jedné instance systému jNetPublish (jiné stránky, obrázky, soubory) jsou reprezentované symbolicky, aby se vždy generovala platná URL bez ohledu na změnu umístění cíle apod. Jde o výrazy tvaru jnpx:odkaz v hodnotě HTML atributů href a src. Ve starších verzích systému jNetPublish se tyto reference zapisují ve tvaru jnp:odkaz a platí pro ně poněkud odlišná pravidla.
Reference na moduly: Modul je šablona nebo jiný fragment složitější prezentační logiky, jejíž výstup se má vložit na dané místo v řetězci. V řetězci jsou reference na modul reprezentované speciálním elementem <module/>. Ve verzi 3.4 se pro ně používal HTML element <img/>, v jehož atributu src je výraz tvaru jnpm:modul a v atributu class je hodnota jnp_module. Před verzí 3.4 tato vlastnost nebyla k dispozici.
Reference na assety k naformátování: Někdy je užitečné vkládat do článku obsah vybraného assetu naformátovaný vždy stejným způsobem. V řetězci je v tom případě speciální element <asset/>. Je dostupné od verze systému jNetPublish 3.5.

Jak se nahrazuje

Symbolické reprezentace URL

jnpx:odkaz

Výsledné URL je výsledkem zpracování identifikátoru stránky, který se získává z assetu, který byl předán jako parametr výpisu. Předpokládejme, že výpis byl volán s parametrem jnprefs=a.

Nalezne se odkaz assetu a s názvem odkaz. Při vyhledání odkazu se zohledňuje aktuální jazyk, prezentace apod. Tento odkaz se použije pro sestavení URL.
Ve starších verzích systému jNetPublish může být odkaz také název vlastnosti assetu a, případně řetězec ve tvaru "sekce/data". V prvním případě je vlastnost referencí na asset a cíl této reference se použije k sestavení odkazu jako při použití funkce link. Ve druhém případě musí být sekce název vlastnosti assetu a, která je referencí na sekci, a data název vlastnosti assetu a, která je referencí na obsahový asset (typicky: článek); opět se sestaví odkaz jako s použitím funkce link.

Reference na moduly

Verze 3.5:

<module type="block" property="reference" />

<module type="inline" property="reference" />

Verze 3.4:

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

Řetězec reference se bere jako název vlastnosti typu reference assetu a. Tento asset (šablona, pagelet apod.) musí definovat modul. Kód, který je výsledkem zpracování modulu, nahrazuje celý element <module/> nebo <img/>.

Poznámka: Novější kód má dvě varianty podle toho, zda je výsledkem formátování řádkový, nebo blokový obsah. Toto je podstatné pro vizuální editor; samotné zpracování při výpisu probíhá v obou případech stejně.

Pozor: Ve verzi 3.4 se při vkládání modulu z vizuálního editoru kolem elementu <img/> ještě musí generovat blokový element. Tento blokový element není při výpisu nahrazen.

Reference na assety k naformátování

<asset type="block" property="reference" mode="mode" />

<asset type="inline" property="reference" mode="mode" />

Řetězec reference se bere jako název vlastnosti typu reference assetu a. Může jít o asset libovolného typu.

Asset se pak formátuje v režimu mode pomocí formátovače, který se dohledá od primární sekce akvizicí vlastnosti articleFormatter. Může tedy obecně jít o jiný formátovač, než který se používá pro běžné formátování výpisu assetů v prezentaci. Navíc se v tomto případě použije jen jeden (první nalezený) formátovač, ne celá hierarchie.

Výsledek formátování nahradí celý element <asset/>.

Poznámka: Kód má dvě varianty podle toho, zda je výsledkem formátování řádkový, nebo blokový obsah. Toto je podstatné pro vizuální editor; samotné zpracování při výpisu probíhá v obou případech stejně.

Příklad: Výpis odkazu s ikonou podle typu souboru

Konfigurace WYSIWYGu

<jnp>
<wysiwyg>
  <formatted-asset-modes>
    <type id="com.etnetera.jnp.data.AclAwareAssetData">
      <mode>link</mode>
    </type>
  </formatted-asset-modes>
</wysiwyg>
</jnp>

Pravidlo ve formátovači článků

{_asset
    mode=_mode
    asset:formatter=_template.main_formatter}

Výpis velikosti souboru

{with ((_asset.data.length + 1023) div 1024)}
  <span class="link-size"
        title="Velikost souboru: {_}&nbsp;KB">
      ({_}&nbsp;KB)
  </span>
{/with}

Výpis ikony souboru

{with split(_asset.data.filename, ".")}
  {if _.length}
    {with toLowerCase(list(_, _.length - 1))}
      {if (ico := _template.file_types[_])}
        {<img src=ico
              class="link-icon"
              alt=_template.file_types["{_}_name"]
              title=_template.file_types["{_}_name"]
        />}
      {else}
        {<img src=_template.file_types.file
              class="link-icon"
              alt=_template.file_types.file_name
              title=_template.file_types.file_name
        />}
      {/if}
    {/with}
  {/if}
{/with}

Řešený problém

Chceme ke každému odkazu na soubor vygenerovat automaticky ikonu a informaci o velikosti souboru.

Požadujeme, aby formátování bylo stejné jak v seznamech, které jsou generované automaticky (např. sekce se všemi soubory ke stažení), tak v případech, kdy odkaz na soubor vkládá autor obsahu do článku.

Postup

Zobrazení ikony v automaticky generovaných seznamech je poměrně snadná věc. Zvolíme nějaký název režimu (v tomto příkladu je to "link") a v hlavním formátovači prezentace se definuje pravidlo pro asset typu Soubor, ve kterém se vypisují údaje o blobu obsaženém v souboru.

Výpis ikony souboru může vypadat například takto:

Předpokládá se tu existence složky, která obsahuje ikony. Vazba na ikony není podle jména dětského assetu, ale podle jména vlastnosti této složky (je efektivnější, a navíc umožňuje použít jednu ikonu pro více přípon souborů). Zároveň má složka vlastnosti s pojmenováním jednotlivých typů; názvy vlastností mají suffix "_name".

Výpis informace o velikosti souboru by měl používat nějakou rozumnou jednotku; zde pro jednoduchost předpokládáme, že vždycky bude stačit zobrazovat velikost v KB:

Tento režim výpisu je pak třeba volat ve všech šablonách vypisujících odkazy na nějaké soubory.

Zpřístupnit tento režim výpisu pro použití v obsahu článků editovaném vizuálním editorem je pak jen otázka další konfigurace. Použije se možnosti vkládat do článků reference na formátované assety. Je potřeba:

definovat, které typy assetů se mohou používat v takových referencích a jaké jsou povolené režimy výpisu;
definovat formátovač, který se použije při výpisu pro nahrazení takových referencí.

První krok se týká obsahu, druhý jeho prezentace.

Pro obsah se musí do konfigurace složky, která takový obsah obsahuje, doplnit pravidlo povolující režim "link" pro assety příslušného typu:

Takový krok je potřeba podniknout s rozmyslem: vzniká jím kontrakt pro prezentační logiku všech prezentací, ve kterých se tento obsah může používat. Správce prezentační logiky každé takové prezentace musí definovat, který formátovač se použije pro takový výpis, a musí zaručit, že bude obsahovat pravidlo pro režim "link" každé takové položky.

Tento formátovač se nastavuje referencí articleFormatter; nejlépe pro kořenovou sekci příslušné prezentace. V našem případě bychom mohli prostě použít hlavní formátovač. S ohledem na budoucí rozšiřování je ale vhodné tuto část prezentační logiky oddělit do samostatného assetu:

Z tohoto nového formátovače se bude hlavní formátovač volat:

Omezení

Informace o typu se odvozuje z přípony souboru. Je to jednodušší, než používat typ blobu.
Pokud se odkaz na soubor vkládá do těla článku, není možné nahradit titulek assetu se souborem vlastním názvem, který by se lišil článek od článku. Toto by bylo možné obejít použitím modulu, kdy by ale výsledný postup byl pro autora obsahu o něco málo komplikovanější.

Poznámky k různým verzím systému jNetPublish

Některé postupy použité v tomto příkladu jsou dostupné až od verze 3.5. V předchozích verzích je možné použít modul s assetem souboru jako parametrem.

Poznámky k verzi ke stažení

Tato verze se v několika bodech liší od předchozího popisu:

V pravidlech formátovače nejsou zalomené řádky a jsou odstraněné přebytečné mezery. To proto, aby ve výstupu nevznikaly mezery tam, kde je autor obsahu mít nechtěl.
Hlavní formátovač má další pravidla: pro typ Upoutávka (poradí si s běžným odkazem i s odkazem na soubor) a obecné pravidlo, kde lze předpokládat, že cílem je HTML dokument, o jehož velikosti není nic známo.

Potlačení escapování

Expanze je použitelná jedině pro mark-up ve stylu SGML nebo XML, optimálně pro HTML. Jedním z efektů použití parametru jnprefs proto je potlačení escapovaní znaků "<", ">", "&".

Příklad: Parametr jnprefs potlačuje escapování znaků

Šablona

{"&"}
{"&" raw}
{"&" jnprefs=_template}

Výstup

&amp;
&
&

Typické použití

V typickém případě je takto vypisovaný řetězec hodnotou atributu assetu. Tento asset sám při tom nese příslušné odkazy nebo vlastnosti.

(Uživatelské rozhraní systému jNetPublish usnadňuje vytváření přesně takových odkazů.)

Příklad: Parametr jnprefs ve výpisu těla článku ve formátovači

Fragment pravidla formátovače

{_asset.body jnprefs=_asset}

Při výpisu v těle cyklu přes assetový datový zdroj je třeba mít na paměti, že aktuální hodnotou cyklu je assetová obálka, nikoli samotný asset.

Příklad: Parametr jnprefs v cyklu přes datový zdroj