paging

Generuje seznam odkazů potřebných pro výpis stránkovacího prvku.

Zadání aktuální pozice:

Pagination paging ( 
    Integer count [ , 
    Integer pos [ , 
    Map options [ ,
    Boolean runover [ ,
    PageIdentification addr ] ] ] ]
)

Zadání názvu parametru obsahujícího aktuální pozici:

Pagination paging ( 
    Integer count [ , 
    String param [ , 
    Map options [ ,
    Boolean runover [ ,
    PageIdentification addr ] ] ] ]
)
count
Počet prvků stránkovaného seznamu. Tedy nikoli počet stránek, ten závisí na počtu prvků na jedné stránce.
pos
Aktuální pozice stránkovače; tedy (defaultně) aktuální offset.
param
Název parametru URL, jehož hodnotou je aktuální pozice, tedy (defaultně) aktuální offset.
options

Mapa parametrů ovlivňujících chování stránkovače.

param
(String) Název HTTP parametru označujícího aktuální pozici. Použito pouze tehdy, pokud není zadáno do funkce jiné jméno. Default: "pos".
omitFirstPageParam
(Boolean) Nepřidávat poziční parametr do adresy, pokud odkazuje na první stránku výpisu. Default: true.
indexByPage
(Boolean) Používat jako hodnotu pozičního parametru index stránky místo indexu položky. Default: false.
pageSize
(Integer) Velikost stránky. Default: 20
forwardCnt
(Integer) Počet stránek ve vicinity následujících po aktuální. Default: 4
backwardCnt
(Integer) Počet stránek ve vicinity předcházejících aktuální. Default: forwardCnt
independentVicinity
(Boolean) I když není dostatek předcházejících stránek, nepoužívej místo nich následující (a naopak). Pokud je false, snaží se vždy mít ve vicinity celkem backwardCnt+1+forwardCnt stránek. Default: false
headCnt
(Integer) Počet stránek na začátku, tj. v seznamu head. Default: 3
tailCnt
(Integer) Počet stránek na konci, tj. v seznamu tail. Default: headCnt
duplicateEnds
(Boolean) Stránka bude v head a tail přítomna i tehdy, když je zároveň ve vicinity. Default: false
consoleEnds
(Boolean) Přidat první a poslední stránky (head a tail) do seznamu console. Default: false
pageSizeParam
(String) Název HTTP parametru, kterým lze přenastavit počet položek na stránku. Default: žádný
pageSizeMin
(Integer) Minimální nastavitelný počet položek na stránku. Platí pro zadaní jakýmkoli způsobem. Default: 2
pageSizeMax
(Integer) Maximální nastavitelný počet položek na stránku. Pozor, platí pro zadaní jakýmkoli způsobem! Default: 500
paramsDiscard
(String) String se interpretuje jako regulární výraz stanovující, jaké HTTP parametry se nemají zachovávat v odkazech. Default: žádný.
paramsKeep
(String) String se interpretuje jako regulární výraz stanovující výjimky – HTTP parametry, které se mají zachovávat v odkazech. Má přednost před paramsDiscard. Default: žádný.
runover
Pokud je nastaveno na true, předpokládá se, že ve skutečnosti je záznamů více než count. Místo odkazu na poslední stránku má být generován přechod na další záznamy.
addr
Výchozí identifikátor stránky pro generované odkazy. Není li zadáno, použije se identifikátor aktuální stránky.

Všimněte si, že význam volání funkce kriticky závisí na typu hodnoty druhého argumentu. Nejste-li si jistí, použijte asInt, popřípadě asString pro explicitní přetypování.

Objekt Pagination

Návratová hodnota funkce je struktura, z níž je možné získat různé podhodnoty.

first
(Page) První stránka výpisu. Existuje vždy, pokud je počet položek nenulový.
prev
(Page) Předchozí stránka výpisu. Neexistuje, pokud je zobrazená stránka první.
current
(Page) Aktuálně zobrazená stránka. Existuje vždy, pokud je počet položek nenulový.
next
(Page) Další stránka výpisu. Neexistuje, pokud je zobrazená stránka poslední.
last
(Page) Poslední stránka výpisu. Neexistuje, pokud je celkový počet položek nulový nebo není znám.
pageSize
(Integer) Použitá velikost jedné stránky. V některých případech se může lišit od požadované.
runover
(Boolean) True, pokud byl použit vstupní parametr stejného jména.
head
(List<Page>) Seznam stránek na začátku výpisu. Jejich počet závisí na konfiguraci a také na pozici aktuální stránky.
tail
(List<Page>) Seznam stránek na konci výpisu. Jejich počet závisí na konfiguraci a také na pozici aktuální stránky.
vicinity
(List<Page>) Odkazy na stránky v okolí aktuálně zobrazené. Jejich počet závisí na konfiguraci.
console
(List<Page>) Ovládací panel stránkovače. Lineární seznam (potenciálně prázdný) všech stránek, na které má vést přímý odkaz. Součástí seznamu mohou být případně i další objekty pro zobrazení navigace. Viz též atribut stránky special.

Předpokládá se, že autor šablony bude primárně pracovat s podhodnotou console (pro výpis číslovaného seznamu stránek) a s podhodnotami first, prev, next a last.

Objekt Page

Objekt obsahuje údaje o jedné konkrétní stránce výpisu seznamu.

prev
(Page) Stránka předcházející této. Neexistuje, pokud je tato stránka první.
next
(Page) Stránka následující za touto. Neexistuje, pokud je tato stránka poslední.
shown
(Boolean) Příznak, zda jde o aktuálně zobrazenou stránku. (Libovolný objekt, který se správně vyhodnotí v podmínce.)
count
(Integer) Počet skutečných položek na této stránce. Vždy má (nezápornou) hodnotu.
index
(Integer) Index této stránky (počítáno od nuly).
number
(Integer) Číslo této stránky (počítáno od jedné).
pos
(Integer) Parametr, který po zadání v URL směřuje na tuto stránku (standardně totéž jako firstIndex).
addr
(PageIdentification) Adresa směřující na tuto stránku, má vyplněn správný parametr s číslem záznamu.
firstIndex
(Integer) Index první položky na stránce (počítáno od nuly). Null, pokud neobsahuje žádné položky.
firstNumber
(Integer) Číslo první položky na stránce (počítáno od jedné). Null, pokud neobsahuje žádné položky.
lastIndex
(Integer) Index poslední položky na stránce (počítáno od nuly). Null, pokud neobsahuje žádné položky.
lastNumber
(Integer) Číslo poslední položky na stránce (počítáno od jedné). Null, pokud neobsahuje žádné položky.
special
(String) Pokud je nastaveno, nejedná se o skutečnou stránku, ale o jiný objekt či ovládací prvek. Všechny ostatní atributy pak nemusí být přítomny. Typickým příkladem jsou oddělovače reprezentující vynechané stránky v seznamu stránkovače.
output
(String) Obvyklá řetězcová podoba výstupu. Pro normální stránky obsahuje jejich číslo, pro pseudo-stránky (special) pak doporučený obsah výstupu.

Motivace

Funkce by ve výsledném stavu měla sjednotit způsob definování prezentační logiky, která stojí za generováním stránkovacího prvku.

Ze šablony by díky ní měly zmizet všechny netriviální výpočty, jako je určení počtu zobrazených stránek, ale také generování odkazů s parametry pomocí funkce linkTail, nebo dokonce jejich přímým vyjmenováním.

Příklad: Defaultní výpis seznamu stránek
Vstup
{let pocetPolozek := 1000}
{while paging(pocetPolozek).console}
	{if shown}
		<strong>{_.number}</strong>
	{else}
		<a href="{_.addr}">{_.number}</a>
	{/if}
	{if not _last} | {/if}
{/while}
Výstup
<strong>1</strong> | 
<a href="/cz/?pos=20">2</a> | 
<a href="/cz/?pos=40">3</a> | 
<a href="/cz/?pos=60">4</a> | 
<a href="/cz/?pos=80">5</a> | 
<a href="/cz/?pos=100">6</a> | 
<a href="/cz/?pos=120">7</a> | 
<a href="/cz/?pos=140">8</a> | 
<a href="/cz/?pos=160">9</a>

Příklad ilustruje základní použití funkce paging s vynecháním všech volitelných parametrů.

Funkce je navržená tak, aby ji bylo možné pomocí parametrů integrovat s existujícími komponentami systému jNetPublish, jako je třeba zobrazení seznamu výsledků fulltextového vyhledávání.

Příklad: Funkce paging nad výsledky fulltextu
Defaultní režim šablony pageletu
{while result}
{whilefirst}
  {let p := paging(result.count, "startPos", asMap(
    "pageSize", 15,
    "pageSizeParam", "perPage"
  ))}
  {with p _template mode="paging" p=_ /with}
{/whilefirst}
  ... výpis položky ...
{whilelast}
  {with p _template mode="paging" p=_ /with}
{/whilelast}
{/while}
Režim "paging" šablony pageletu
{with p.prev}
  <a href="{p.first.addr}">první</a> | 
  <a href="{_.addr}">předchozí</a> | 
{/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}
  | <a href="{_.addr}">následující</a>
  | <a href="{p.last.addr}">poslední</a>
{/with}

Pracuje se s hodnotou result.count, do které pagelet zveřejňuje počet nalezených výsledků.

Funkci je samozřejmě možné použít i pro výpis stránkovače nad seznamem výsledků JDO dotazového datového zdroje. Prvním vstupem funkce bude proměnná _count, dostupná v blocích whilefirst a whilelast. Pak je ovšem třeba dát pozor na následující:

  • I tady je potřeba zdůraznit, že pokud v samotném cyklu while používáte volbu forceCount=1, může to mít nezanedbatelný vliv na výkon.
  • Pokud použijete volbu s omezením na nějaký maximální počet položek, například forceCount=sum(_request.params.pos, 100), pak byste při volání funkce paging měli použít parametr runover.
Pro vložení příspěvku do diskuse se přihlašte.