Výběr assetů dotazovým zdrojem
Assety je možné filtrovat na základě jejich typu, rodičovské složky a dalších kritérií. Toho se využívá při tvorbě stránkovaných seznamů obsahu v kategorii apod.
Výběr a výpisy seznamů assetů jsou typickým výstupem speciálních šablon sekcí. Ukážeme, jak může vypadat typická šablona, která v režimu detail vypisuje seznam článků v aktuální sekci.
Vytvoření zdroje
Zdroj je asset typu Dotazový datový zdroj JDO. Tyto assety se obyčejně vytvářejí v podsložce složky logic.
Kritéria výběru assetů
Nastavíme základní kritéria pro výběr assetů, které má zdroj vracet:
- Typ položek nastavíme na typ assetů, které chceme získat. V našem případě to budou Články ve výchozí obsahové variantě.
- Počáteční složku bychom mohli zadat, pokud by zdroj měl vracet výsledky z pevně dané složky. To ale není náš případ – zdroj musí vracet výsledky vždy z aktuální sekce. Proto tento atribut necháváme nenastavený; volba složky se provede až šablonou při výpisu.
- Zaškrtneme volbu Pouze daná složka (bez vnořených) – předpokládáme pro náš příklad, že nechceme mít v seznamech články z podsekcí aktuální sekce.
- JDOQL dotaz umožňuje dále omezit seznam výsledků, především podle hodnot atributů assetů, ale také například podle jejich názvu. Protože používáme konvenci, podle které asset s názvem
indexmá speciální roli (slouží jako úvodní obsah sekce), vyloučíme ho ze seznamu. Tento dotaz se zapisujename != "index".
Řazení assetů ve výsledku
Řazení se nastavuje řetězcem, který uvádí systémové názvy atributů pro řazení, vždy s prefixem určujícím, zda má být řazení vzestupné nebo sestupné. Nejběžnější příklady:
a:title | Abecedně podle titulku, vzestupně, nerozlišují se velká a malá písmena. |
A:ord | Vzestupně podle hodnoty atributu Pořadí. |
D:articleDate | Sestupně podle data článku (nejnovější na začátku). |
A:ord,a:title | Vzestupně podle Pořadí, při stejném pořadí podle titulku. |
Nastavení cache
Doporučuje se prakticky vždy zvolit možnost Ukládat do vyrovnávací paměti (cache).
U běžných dotazů jsou výsledky pro všechny uživatel shodné, proto se Režim vyrovnávací paměti nastavuje na Cache je společná pro všechny uživatele.
Režim validace
Validací je možné omezit seznam podle nastavené časové platnosti jednotlivých assetů.
Validace by se měla provádět jen v případech, kdy je skutečně potřeba (protože ověřování platnosti assetů je výpočetně náročné a komplikuje ukládání výsledků do cache). Je proto vždy třeba se domluvit se správcem obsahu, zda se této vlastnosti bude využívat.
Iterace přes výsledky zdroje
Zdroj je třeba k šabloně, ve které se bude používat, připojit referencí; volíme tu pro ni název source (na jméně nezáleží a nějaká striktní konvence není nutná). Pro iteraci se použije příkaz while.
Zopakujeme: při iteraci přes assetové zdroje se nastavuje v rámci cyklu hodnota proměnné _ na assetovou obálku. Tento objekt zpřístupňuje tytéž podhodnoty jako samotný asset a lze z něj tedy číst atributy i vlastnosti assetu. Pokud ale má být asset použitý jako argument funkce, je ho třeba získat z assetové obálky jako podhodnotu asset.
Parametrizace zdroje
Zdroji lze ze šablony předat parametry. Těmito parametry je možné jednak změnit nebo doplnit hodnoty nastavované přímo v assetu zdroje, jednak je možné je použít v komplikovanějším dotazu.
V našem příkladu si vystačíme s možností doplnit hodnotu Počáteční složka. Tato se předává zdroji jako parametr folder. Nastavíme ji vždy na aktuální primární sekci.
{while _template.source folder=_primary}
{whilefirst}
<ul>
{/whilefirst}
<li>
<a href="{value(target(_.asset), link(_.asset))}">{_.title}</a>
<div>{_.perex}</div>
</li>
{whilelast}
</ul>
{/whilelast}
{/while}Dotazový datový zdroj je připojený k ajktuální šabloně vlastností source.
Parametr folder nastaví složku, ze které se mají vybírat assety. V příkladu se předává aktuální primární sekce. Šablona tedy může fungovat jako výpis seznamu položek v libovolné sekci.
Stránkování seznamu
Další parametry slouží pro stránkování seznamu:
limit- Hodnota tohoto parametru určuje, kolik má zdroj (maximálně) vrátit výsledků. Nastavuje se sem tedy velikost stránky – počet prvků na stránce.
offset- Určuje, kolik prvků se má přeskočit. To znamená, že pokud je například 20 prvků na stránku, nastavuje se zde nic nebo 0 pro první stránku, 20 pro druhou stránku, 40 pro třetí stránku atd.
Hodnotu offset obyčejně předáváme jako parametr požadavku. Při výpisu se tedy musí načíst z parametrů. Mapa parametrů je v šabloně dostupná jako _request.params. Můžeme z ní tedy například číst hodnotu parametru offset jako _request.params.offset. Je vhodné provést vždy konverzi na celé číslo pomocí funkce asInt.
Navigace stránkovaným seznamem
Navigace stránkovaným seznamem předpokládá konstrukci řady odkazů na různé stránky seznamu. K tomu slouží funkce paging.
Abychom dosáhli uniformního výpisu stránkovače, je vhodné ho vydělit do samostatné šablony. Této šabloně budeme vždy předávat objekt stránkovače.
<div class="paging">
{with p.prev}
<a href="{p.first.addr}">první</a><span class="sep"> | </span>
<a href="{_.addr}">předchozí</a><span class="sep"> | </span>
{/with}
{while p.console}
{if _.shown}
<strong>{_.number}</strong>
{else}
<a href="{_.addr}">{_.number}</a>
{/if}
{if not _last}<span class="sep"> | </span>{/if}
{/while}
{with p.next}
<span class="sep"> | </span><a href="{_.addr}">následující</a>
{if not p.runover}<span class="sep"> | </span><a href="{p.last.addr}">poslední</a>{/if}
{/with}
</div>Je vhodné mít sdílenou šablonu obsahující výpis stránkování. Výpis abstrahuje od způsobu vytvoření stránkovače.
Stránkovač standardně vytváří funkce paging pokaždé jiným způsobem, a to ve volající šabloně. Volající šablona objekt předává této sdílené šabloně jako parametr p.
Všimněte si, že v některých případech stránkovač nemusí obsahovat odkaz na poslední stránku; zda tomu tak je, se ověřuje testem podhodnoty runover.
Stránkovač se konstruuje v šabloně generující stránkovaný seznam. Abychom ho mohli zkonstruovat, je třeba zjistit celkový počet položek. Celkový počet je hodnotou proměnné _count; aby tato proměnná skutečně obsahovala celkový počet, je však potřeba zadat příkazu while parametr forceCount s hodnotou 1.
{let limit := value(asInt(_request.params.limit), 10)}
{let offset := asInt(_request.params.offset)}
{while _template.source forceCount=1 folder=_primary limit=limit offset=offset}
{whilefirst}
{let p := paging(_count, "offset", asMap("pageSize", limit, "forwardCnt", 2))}
{_template.pg_template p=p}
<ul>
{/whilefirst}
<li>
<a href="{value(target(_.asset), link(_.asset))}">{_.title}</a>
<div>{_.perex}</div>
</li>
{whilelast}
</ul>
{_template.pg_template}
{/whilelast}
{/while}Používá se obecná šablona stránkovače připojená k aktuální šabloně vlastností pg_template. Této šabloně se stránkovač předává jako hodnota parametru p.
Iterace používá dotazový datový zdroj připojený k ajktuální šabloně vlastností source.
Použití forceCount=1 s dotazovým zdrojem je někdy zdrojem výkonových problémů. Jeden ze způsobů, jak je eliminovat, je generování neúplného stránkovače, bez odkazu na poslední stránku. Toto je pospáno dále.
{let limit := value(asInt(_request.params.limit), 10)}
{let offset := asInt(_request.params.offset)}
{while _template.source forceCount=1 folder=_primary limit=limit offset=offset}
{whilefirst}
{let p := paging(
_count,
"offset",
asMap("pageSize", limit, "forwardCnt", 2),
true /* runover */
)}
{_template.pg_template p=p}
<ul>
{/whilefirst}
<li>
<a href="{value(target(_.asset), link(_.asset))}">{_.title}</a>
<div>{_.perex}</div>
</li>
{whilelast}
</ul>
{_template.pg_template}
{/whilelast}
{/while}Příklad se od příkladu s úplným stránkováním liší použitím parametru runover. Díky němu se vytvoří stránkovač bez odkazu na konec.
Šablona stránkovače s touto možností počítá, není tedy třeba ji modifikovat.
Problematika výkonové optimalizace prezentační logiky v systému jNetPublish je pokryta v samostatném přehledu.
Shrnutí
Vytvořili jsme jednu typickou speciální šablonu sekce a jednu komponentu, kterou budou šablony sekcí běžně využívat. Malé prezentace se mohou omezit na logiku, která byla dosud popsaná. Pro větší prezentace je ale žádoucí vytvořit prostředky modularizace, popsané v následujících kapitolách.