PageIdentification

Identifikátor stránky je typ objektu, který (zjednodušeně řečeno) pro publikační rozhraní systému jNetPublish reprezentuje určitou URL adresu.

Interní struktura identifikátoru může zahrnovat mimo jiné několik assetů ve specifických rolích (například prezentace, primární sekce, obsahový asset), specifikaci požadovaného jazyka a formátu odpovědi a další informace.

Vnější reprezentací identifikátoru je URL, případně s parametry. V principu různá URL mohou reprezentovat týž identifikátor, ale ke každému URL patří nejvýše jeden identifikátor.

Každý aktuálně zpracovávaný požadavek v publikačním rozhraní obsahuje svůj identifikátor stránky. Kromě toho se identifikátor používá i pro odkazy obsažené v generované stránce.

Identifikátor aktuálně zpracovávaného požadavku rozhoduje o vykonávaném pageletu a nepřímo o volbě vypisované šablony; kromě toho se z něj do prostředí šablon přebírají hodnoty několika globálních proměnných: _site, _primary, _main, _format, _language. Od verze 3.4.2 je dostupný samotný identifikátor jako proměnná _pageId. Od verze 3.5 je dostupný identifikátor rozšířený o request parametry jako proměnná _pageIdWParams.

Identifikátory stránek, na které vedou odkazy v generované stránce, se vytvářejí jednak pomocí speciálních funkcí TFS (například link, xlink, target), jednak vznikají při překladu referencí na připojené odkazy assetů obsažených v těle vypisovaných článků. (Viz dokumentaci k parametru jnprefs.)

Základní klasifikace

Z pohledu autora šablony nebo autora obsahu je možné vystačit s klasifikací na tři typy identifikátorů:

• interní odkaz,
• odkaz na soubor,
• externí odkaz.

Jednotlivé položky mají další podtypy, ale například vlastnosti identifikátorů, které lze číst v šabloně, jsou v rámci každé z těchto tří tříd shodné.

Poznámka: Při správě ortogonálních odkazů je také k dispozici volba nepřímý odkaz. Z pohledu autora šablon to ale není samostatný typ odkazu: ve výsledku by se měl každý nepřímý odkaz vyhodnotit jako jeden z předchozích typů a jako takový se objeví v TFS.

Výpis hodnoty

Při výpisu hodnoty probíhá převod na URL.

{let tgt := link(_primary, _main)}
<a href="{tgt}">{value(_main.title, _primary.title)}</a>
{/* ekvivalentně */}
<a href="{link(_primary, _main)}">{value(_main.title,
  _primary.title)}</a>

Parametry výpisu

Parametry příkazu pro výpis hodnoty se použijí jako dodatečné parametry URL.

<a href="{link(_primary, _main) a="b" c="d"}">
  {value(_main.title, _primary.title)}
</a>

<a href="/jnp/cz/index.html?a=b&amp;c=d">
  Novinky
</a>

Výjimkou jsou parametry, jejichž název začíná řetězcem link: – některé mají dále definovaný speciální význam, ostatní jsou rezervované pro případné budoucí použití a při výpisu se úplně ignorují.

Přepsání parametrů výpisu

Pokud identifikátor stránky už obsahuje parametry (např. dětský odkaz), lze je přepsat parametry příkazu pro výpis hodnoty.

<a href="{target(_primary, "odkaz") a="x"}">
  {_primary.title}
</a>

<a href="/jnp/cz/novinky/index.html?a=x&amp;c=d">
  Novinky
</a>

<a href="{linkTail(_pageId, _request.queryString) q="ADSL" page=2}">
  Hledat
</a>

<a href="/jnp/cz/vyhledavani/index.html?q=ADSL&amp;page=2&amp;category=all">
  Hledat
</a>

Potlačení escapování

Při výpisu se defaultně provádí nahrazení znaků '<', '>', '&', '"' referencemi k entitám podobně jako při výpisu řetězců. Potlačení tohoto nahrazování je možné dosáhnout použitím parametru link:raw (buď bez hodnoty, nebo s hodnotou, která se vyhodnotí jako true).

<script type="text/javascript"><![CDATA[
var linkTarget = '<? target(btn) link:raw ?>';
]]></script>

Výpis do WML

Existuje speciální verze parametru pro výpis identifikátoru stránky do WML: link:wml.

Přidání kotvy

V okamžiku výpisu je možné přidat k odkazu kotvu jako hodnotu parametru link:anchor.

Řetězec s parametry

Pokud je uvedený parametr výpisu link:parameters, předpokládá se, že je to řetězec, který se použije pro nastavení parametrů odkazu.

Verzování URL

V okamžiku výpisu lze výslednou URL verzovat: zajistit, aby se URL automaticky změnila pokaždé, když se změní obsah odkazovaného dokumentu.

Tímto způsobem lze značně vylepšit režim cachování odkazovaného dokumentu v prohlížeči: prohlížeč odkazovaný dokument načítá znovu ze serveru jen a právě tehdy, když se dokument změní. (V souvislosti s verzováním URL je pochopitelně třeba nastavit hlavičku Expires na dostatečně vzdálenou dobu.)

Různé verze URL, které se takto vytvářejí, se liší pouze přidaným parametrem URL, jehož hodnota je nějak svázaná s aktuálně platnou verzí dokumentu. Název parametru by měl být pochopitelně zvolený tak, aby neměl žádný vliv na výpis.

Autor šablony také má možnost ovlivnit volbu typu změny, která povede ke změně hodnoty parametru (a tedy URL). Aktuálně jsou tyto možnosti:

• URL se mění v okamžiku, kdy se změnil jeden konkrétní asset.
• URL se mění v okamžiku, kdy se změnil libovolný asset v celé databázi.

Lze použít tyto modifikátory výpisu:

link:version

Do vygenerovaného odkazu přidá speciální parametr vyjadřující verzi dat. Pokud není současně použit parametr link:version_asset nebo je jeho hodnota null, je to aktuální verze databáze, např. po publikaci – viz dále.

Pokud link:version nemá hodnotu, verze se přidá vždy. Pokud link:version má hodnotu, verze se přidá, pokud hodnota je true.

V případě, že je přítomný alespoň jeden z dalších modifikátorů a má hodnotu, není použití link:version nutné.

link:version_asset

Asset, na jehož změny je vázána změna URL. Hodnota parametru URL se tedy změní při každé změně tohoto assetu. Pokud je zadaný asset výčtový datový zdroj, pak se čas určuje jako maximum z času poslední změny jeho samotného a položek obsažených ve výčtu (platí od verze 3.6.12). Defaultně (asset není zadán, nebo je null) se použije poslední změna jakéhokoli assetu v aktuálním projektu.

link:version_param

String s názvem parametru URL, který se má přidat. Defaultní hodnota je "_linkv"; použije se, pokud je hodnota modifikátoru link:version_param prázdná nebo null.

<link rel="stylesheet" type="text/css" media="screen"
  href="{target(_template, "screen") link:version}" />

<link rel="stylesheet" type="text/css" media="screen"
  href="/static/3481-1-PUB/none/screen.css?_linkv=123456789" />

Svázání změn s jedním konkrétním assetem vede obecně k menšímu počtu verzí a tedy ke snížení zátěže serveru. Může tu ale být riziko, že se odkazovaný dokument změní, aniž by se změnil zvolený asset.

<link rel="stylesheet" type="text/css" media="screen"
  href="{link(_template.secCss, _template.cssTpl, "css", "none")
  link:version_asset=_template.cssTpl}" />

Absolutní a relativní URL

Převod na URL v okamžiku výpisu (a také převod pomocí funkce asString) vede na vytvoření relativního nebo absolutního URL. Volba typu URL se děje podle takových pravidel, aby bylo vždy jisté, že výsledný odkaz bude ve svém kontextu interpretovaný korektně; obecně proto není nikdy garantováno, že generované URL bude relativní. Lze však dosáhnout garantovaného generování absolutního URL pomocí volby options.

{options forceAbsoluteAddresses=1}
<link rel="self" href="{link(_primary, _main)}" />
{/options}

{options forceAbsoluteAddresses=1}
{let thisPage := asString(_pageId)}
{/options}

Pro vstup do této sekce je vyžadováno
<a href="{target(login) returnTo=thisPage}">přihlášení</a>.

Konkrétní tvar URL je popsaný u jednotlivých podtypů.

Selekce podhodnoty

V šabloně je vždy dostupná vlastnost addressKind, jejíž hodnota určuje typ identifikátoru. Hodnotou této vlastnosti je číslo; všechny možnosti definuje rozhraní com.etnetera.jnp.publish.PageIdentification (od verze Vetis, dříve com.etnetera.publish.PageIdentification), proto doporučený postup testování předpokládá import této třídy do šablony. Pak jsou k dispozici symbolická označení jednotlivých typů:

Hodnota AK_INCOMPLETE by se neměla v prostředí šablony vyskytnout: Interně se používá v systému jNetPublish po dobu, kdy nejsou známy všechny povinné složky.

V naší méně podrobné klasifikaci jsou:

• AK_NORMAL, AK_PREVIEW a AK_STATIC interní odkazy,
• AK_UNSTABLE a AK_FILE odkazy na soubor,
• AK_EXTERNAL externí odkaz.

Testování vlastnosti addressKind se hodí zejména v případech, kdy vypisujeme odkaz, jehož typ vybírá klient.

{import com.etnetera.jnp.publish.PageIdentification}

{let tgt := target(_asset, "target")}
<a href="{tgt}">
  {if or(tgt.addressKind == PageIdentification.AK_UNSTABLE,
		 tgt.addressKind == PageIdentification.AK_FILE)}
	stáhnout
  {else}
	více
  {/if}
</a>

Další existující podhodnoty závisejí na podtypu identifikátoru. Jsou proto zdokumentovány na příslušných místech:

• interní odkaz,
• odkaz na soubor,
• externí odkaz.

Mapování

Probíhá stejně jako selekce podhodnoty.

Sekvenční zpracování

Chová se jako prázdná sekvence.

Převod na logickou hodnotu

V podmínce se jakýkoli identifikátor stránky vyhodnotí jako true.

Lze tak tedy například testovat, zda asset má ortogonální odkaz daného jména pro aktuální jazyk, segment a prezentaci.

{let tgt := target(_asset, "more")}
{if tgt}
  <a href="{tgt}">další informace</a>
{/if}

Pozor: Když odkaz existuje, ale není možné ho korektně doplnit (například má primární sekci, která nepatří k zadané prezentaci), vrátí funkce target do šablony chybový objekt, jehož konverze na boolean zatím není ošetřena.