Interní odkaz

Jeden z podtypů AK_NORMAL, AK_PREVIEW, AK_STATIC identifikátoru stránky.

Interní odkaz je takový identifikátor, který na vstupu vede ke standardnímu použití publikačního rozhraní.

• Z pohledu autora obsahu to může být v nejjednodušším případě prostě odkaz na obsahový asset nebo sekci.
• Z pohledu kodéra je to pevně daná struktura: prezentace, primární sekce, hlavní asset, volaný pagelet, akce pageletu, formát, jazyk, příznak zabezpečení (http/https), parametry URL, kotva (identifikátor fragmentu dokumentu) – viz dále podrobnější specifikaci.

Při zpracování interních odkazů se podle určitých pravidel doplňují položky, které autor odkazu explicitně neuvedl (pro podrobný popis viz dále).

• Před autorem obsahu může být tato skutečnost do jisté míry skrytá. Bez této informace se ale většinou neobejde ve složitějších případech: například když má vytvářet odkazy mezi jazykovými verzemi nesymetrické prezentace.
• Před kodérem by měla být do značné míry skrytá skutečnost, že struktura interního odkazu obsahuje klič pravidla prezentace, identifikátor zvoleného projektu nebo sezení a segment.

Podrobnější klasifikace

AK_NORMAL

běžný (jnp) odkaz,

AK_STATIC

odkaz na statické stránky,

AK_PREVIEW

odkaz pro náhled a insite editaci.

Běžný odkaz má ve vnější reprezentaci defaultně tvar /jnp/*; v typických případech však bude tento prefix odstraněn s ohledem na SEO. Reprezentuje URL, pod kterým budou stránku požadovat běžní návštěvníci webu.

Odkaz na statické stránky má tvar /static/*. Také toto je reprezentace URL, pod kterým budou stránku požadovat běžní návštěvníci webu. Od běžného odkazu se liší tím, že stránka se vygeneruje jen jednou a na všechny následující požadavky se bude vracet její statická verze uložená na disku.

Odkaz pro náhled a insite editaci má tvar /preview/*. Specifikem tohoto typu odkazu je, že výsledné URL přímo obsahuje identifikátor projektu, do kterého patří. Při zadání odpovídajícího URL do prohlížeče se pak zobrazují assety z daného projektu (proto „náhled“). Jeho typickým využitím je insite editace. Neměl by se nikdy vyskytnout ve veřejné prezentaci nebo v cizím odkazu na web.

Podhodnoty interního odkazu

site

(Site) Prezentace. V prezentaci v systému jNetPublish reprezentuje asset typu konfigurace prezentace, musí tedy jít o položku tohoto typu. Je to povinná položka.

segment

(Integer) Číslo identifikující segment. Existující segmenty jsou dané konfigurací dané instalace systému jNetPublish. Je to relativně nová vlastnost, pro většinu existujících nasazení systému jNetPublish nemá žádný význam. Prozatím nelze formulovat kontrakt, na který se bude možné spolehnout i v budoucnu.

primary

(Sekce) Primární sekce. Musí to být asset typu sekce nebo nějakého podtypu. Možná volba sekce je omezená požadavkem příslušnosti sekce k prezentaci. Je to povinná položka.

main

(Asset) Hlavní obsahový asset. Může to být asset libovolného typu.3) Ve struktuře složek může být umístěný libovolně. Je to nepovinná položka.

format

(String) Požadovaný výstupní formát. Je to řetězec reprezentující výstupní formát; příklady hodnot jsou „html“, „css“. Možné hodnoty jsou dané konfigurací v jnp.xml. Je to povinná položka.

language

(String) Požadovaný jazyk výstupu. Je to řetězec reprezentující výstupní jazyk, například „cz“ pro češtinu, „en“ pro angličtinu, případně řetězec „none“ (žádný jazyk). Možné hodnoty jsou dané konfigurací v jnp.xml. Je to povinná položka.

pagelet

(Pagelet) Vykonávaný pagelet. Je to asset typu PageletData (pagelet). Je to nepovinná položka. Viz podrobnější vysvětlení.

method

(String) Metoda (akce) pageletu. Možné hodnoty jsou omezené (1) výskytem znaků, které se mohou vyskytovat v URL a nemají speciální význam, a (2) výskytem znaků, které nemají speciální roli při parsování URL v systému jNetPublish (viz dále). Smysluplně se pochopitelně dají použít jen hodnoty, se kterými počítá logika daná třídou pageletu. Hodnota může být nastavená, jen pokud je nastavený vykonávaný pagelet. I v tom případě je to nepovinná položka. Viz podrobnější vysvětlení.

secure

(Logická hodnota) Příznak zabezpečení. Je to boolovská hodnota: true pro https, false pro http.

urlParameters

(String) Parametry URL. Popis formátu následuje. Je to nepovinná položka.

urlAnchor

(String) Kotva (identifikátor fragmentu dokumentu). Je to řetězec. (Pro jednoduchost: kotva neobsahuje úvodní “#“: toto je oddělovací znak a jNetPublish ho automaticky doplní při skládání URL.)

projectId

(Integer) Identifikátor projektu nebo sezení.

siteKey

(String) Klíč pravidla prezentace.

Příslušnost sekce k prezentaci

Asset konfigurace prezentace (site) obsažený v identifikátoru musí mít nastavený atribut kořenová sekce (rootSection) a dále má booleovský atribut symetrická vícejazyčnost (symetricalyMultilingual). Jejich hodnoty určují, která sekce se může v identifikátoru objevit jako primary.

• primary musí být obsažená v podstromu assetů, jehož kořenem je rootSection assetu site.
• Všechny assety na cestě od rootSection k primary musejí být typu sekce nebo tento typ rozšiřovat.
• Pokud je prezentace nesymetrická (tzn. atribut symetricalyMultilingual assetu site má hodnotu false), platí další omezení pro první prvek na cestě od rootSection k primary: pokud je aktuální jazyk jiný než „none“, pak název této první sekce musí být shodný s hodnotou language.

Porušení omezujících podmínek kladených na sekci vede k výjimce „Section does not belong to site“. (Od verze 3.4.0 je tato výjimka zachycena, pokud ji způsobí odkaz odkazovaný z těla článku jnpx referencí. Zmenšuje se tak pravděpodobnost, že autor obsahu způsobí chybným nastavením odkazu nedostupnost celé stránky.)

Formát parametrů URL

Parametry reprezentuje řetězec stejného tvaru jako v běžném URL:

parametr1=hodnota1&parametr2=hodnota2&parametr3=hodnota3...

Všimněte si, že

• řetězec neobsahuje úvodní “?“;
• znak “&“ není zakódovaný jako reference k entitě “&“;
• jména parametrů a hodnoty jsou zakódované pro použití v URL, tzn. například „spaceChar=%20“ je korektně zapsaný řetězec.

Volání pageletu

Je potřeba rozlišovat mezi vykonáním pageletu a vypsáním šablony pageletu.

• Pokud je položka vykonávaný pagelet neprázdná ve vstupním identifikátoru stránky, dojde k jeho vykonání (metoda execute).
• Vykreslení šablony pageletu (metoda render) je na tom zcela nezávislé. Dojde k němu tam, kde si autor šablony vyžádá vypsání assetu pageletu.

"Metoda" ("akce") pageletu je libovolný řetězec, který se předává obslužnému kódu pageletu při vykonání. Je na autorovi programového kódu, aby určil, zda a jakým způsobem se tato hodnota využije.

Přístup k podhodnotě

Kodér může z identifikátoru stránky zjistit všechny jeho složky. Testování těchto položek se hodí zejména v případě, kdy identifikátor stránky bude vytvářet autor obsahu jako dětský odkaz assetu.

{let tgt := target(_asset, "target")}
<a href="{tgt}">{if tgt.pagelet}
  provést
{else}
  zobrazit
{/if}</a>

Neveřejné položky

Identifikátor stránky obsahuje také data, která je možné v šabloně vypsat nebo použít pro testování. Logika šablony by na ně nicméně neměla spoléhat v produkčním prostředí; není také garantováno zachování jejich funkčnosti mezi verzemi systému jNetPublish.

siteKey

(String) klíčové slovo pravidla konfigurace prezentace.

projectId

(Integer) identifikátor projektu nebo sezení.

{if link(_primary).projectId == 1}
  Zobrazuje se obsah potvrzený do kořenového projektu.
{else}
  Zobrazují se data z projektu/sezení
  {link(_primary).projectId}
{/if}

Doplnění podhodnot neuvedených explicitně

Jak v šabloně při použití funkce link, tak při správě ortogonálních odkazů je možné uvést jen některé z položek odkazu. V tom případě se používají následující pravidla pro doplnění neuvedených položek.

Uplatnění těchto pravidel může poměrně snadno vést k porušení podmínek kladených na dvojici primary – main. Proto by je měl autor šablon znát a dokumentace pro autora obsahu by měla obsahovat pravidla, jak se tomuto problému vyhnout.

Položky přebírané z aktuální stránky

Pokud nejsou explicitně uvedeny, site, format, language a secure se zkopírují z aktuální stránky.

Nepovinné položky

Položky main, pagelet, method, urlParameters a urlAnchor jsou nepovinné. To znamená, že se nedoplňují, pokud nejsou při vytváření odkazu explicitně uvedeny.

Doplnění sekce

Pokud není určená primární sekce a je určený hlavní asset, uplatní se při dohledání sekce jedna ze strategií definovaných v konfiguraci systému jNetPublish. Aktuálně je možné použít následující dvě strategie:

• Uplatnění konfigurace náhledu: Pravidla pro výběr sekce jsou definovaná v samostatném assetu. Pro určitou pracnost nastavování se od této možnosti v novějších projektech upouští.
• Použití rodičovské sekce: Pokud je rodičem hlavního assetu asset typu sekce nebo typu od sekce odvozeného, nastaví se tato sekce jako primární.

Další strategie může do projektu doplnit programátor.

Dohledání klíčového slova prezentace

K dohledání klíčového slova prezentace se použijí pravidla obsažená v assetu site výstupního identifikátoru. Asset site je typu konfigurace prezentace. Obsahuje tedy seznam pravidel prezentace. Každé pravidlo obsahuje seznam klíčových slov odkazujících prezentací.

Ošetření chyb:

• Pokud je klíčové slovo ze vstupního identifikátoru obsažené ve více než jednom pravidle, není definováno, jaké klíčové slovo bude mít výstupní identifikátor.
• Pokud není klíčové slovo ze vstupního identifikátoru obsažené v žádném pravidle, povede pokus o vytvoření odkazu k chybě.

Oba druhy chyb znamenají, že je třeba opravit pravidla v konfiguraci prezentace.

Volba podtypu (addressKind)

Pokud má být na výstupu interní odkaz platí pro určení přesného typu následující postup:

1. Pokud má primary ve výstupním identifikátoru nastavený příznak Generovat statickou podobu (staticContent), je výsledný identifikátor typu AK_STATIC.
2. Pokud je vstupní identifikátor typu AK_PREVIEW, pak i výstupní identifikátor je typu AK_PREVIEW.
3. V ostatních případech se generuje typ AK_NORMAL.

Mapování na URL

Podoba absolutního URL

Pokud se má vygenerovat absolutní URL, přebírají se údaje o jménu serveru a portu z pravidel konfigurace prezentace, která je u daného identifikátoru nastavená jako site. Vybírají se z pravidla, jehož klíčové slovo je shodné s hodnotou siteKey nastavenou pro identifikátor.

Prezentace, klíčové slovo a projekt v relativním URL

Pro typy AK_PREVIEW a AK_STATIC je třeba předávat v relativním URL hodnoty site, siteKey, projectId.

Tyto hodnoty reprezentuje řetězec následující v URL bezprostředně za "/static/" nebo "/preview/". Tvar tohoto řetězce je:

site "-" projectID "-" siteKey

Site reprezentuje identifikátor assetu. To znamená, že URL mohou být například:

/static/590-1-PUB/none/css/screen.css
/preview/590-4096-EDIT/cz/home/index.html

Kořenová sekce a datová složka, cesty k assetům

V URL bývají obsažené reprezentace dvou cest v assetovém stromu:

• cesta od kořenové sekce prezentace k primární sekci,
• cesta od datové složky k hlavnímu assetu.

Cesta k primární sekci začíná prvním dětským assetem sekce, která je nastavená jako atribut rootSection assetu site identifikátoru. Pokud je prezentace nastavená jako nesymetrická, je prvním dětským assetem sekce s názvem reprezentujícím aktuální jazyk; název této sekce by duplikoval označení jazyka a v cestě proto není obsažený. Cesta končí primární sekcí. Defaultní oddělovač je “/“.

Cesta od datové složky k hlavnímu assetu začíná od dětského assetu datové složky a končí hlavním obsahovým assetem. Protože hlavní asset nemusí být potomkem datové složky, může být cesta absolutní; její reprezentace pak začíná oddělovačem a první položka je dětský asset kořenové složky. Defaultní oddělovač je “-“.

Datová složka může být nastavená buď u prezentace (site) nebo u primární sekce (primary). Hodnota nastavená u primární sekce má přednost.

• Datovou složku prezentace určuje atribut Kořenová datová složka (rootDataFolder).
• Datovou složku sekce určuje atribut Datová složka (defaultDataFolder).

Hodnota defaultDataFolder se dědí.

Sekce jako vlastní datová složka

Často je užitečné, aby sekce fungovala jako vlastní datová složka: v kombinaci se strategií pro dohledání sekce, která bere k článku defaultně rodičovskou sekci, to vede ke krátkým URL a současně jednoduchému linkování článků v šablonách bez nutnosti definovat konfigurace náhledu. Před verzí 3.4.0 je třeba explicitně nastavovat v atributu sekce tuto referenci na sebe sama.

Od verze 3.4.0 je možné nakonfigurovat zvolený podstrom sekcí tak, že jako datová složka každé sekce v  podstromu se bude brát ona sekce sama, aniž by bylo třeba nastavovat každé sekci atribut defaultDataFolder. Je k tomu třeba nastavit kořenové sekci zvoleného podstromu:

• hodnotu atributu Datová složka (defaultDataFolder) jako referenci na sebe sama,
• řídící slovo data_folder_self.

URL typu AK_NORMAL

"/jnp/" language "/" primary "/"
main [ "$" pagelet [ "-" method ] ] "." format

Pokud je main rovno null, reprezentuje ho řetězec „index“; jinak je to cesta k hlavnímu assetu.

Primary je cesta k primární sekci.

Dvojice site, siteKey může být reprezentovaná v absolutním URL.

Vlastnost projectId není v URL nijak reprezentovaná, ale může být obsažená v session. Pokud to tak není, bere se projectId rovno 1 (kořenový projekt).

URL typu AK_STATIC

"/static/" site "-" projectId "-" siteKey "/"
 language "/" primary "/" main "." format

Pokud je main rovno null, reprezentuje ho řetězec „index“; jinak je to cesta k hlavnímu assetu.

Primary je cesta k primární sekci.

V URL site reprezentuje identifikátor assetu konfigurace prezentace.

V principu nemá smysl vytvářet statické stránky volající pagelet.

URL typu AK_PREVIEW

"/preview/" site "-" projectId "-" siteKey "/"
language "/" primary "/"
main [ "$" pagelet [ "-" method ] ] "." format

Pokud je main rovno null, reprezentuje ho řetězec „index“; jinak je to cesta k hlavnímu assetu.

Primary je cesta k primární sekci.

V URL site reprezentuje identifikátor assetu konfigurace prezentace.