Stránkování dat - Jet\Data_Paginator

Třída pomáhá řešit klasický (a mnohdy "oblíbený") problém se stránkováním seznamu položek. Pozor aby nedošlo k nedorozumění. Třída vůbec neřeší vykreslování UI. Pro snadnou implementaci celého rozhraní práce se seznamem včetně filtrů má Jet jinou sadu tříd stejně tak jako pro vykreslení seznamu samotného. Tato třída řeší model - tedy logiku a algoritmus stránkování dat.

Stránkovat je možné jak seznam v běžném poli, tak instanci nějakého iterátoru, který musí implementovat třídu Jet\Data_Paginator_DataSource.

Stránkovač počítá s tím, že údaje o počtu položek na stránku a také o aktuálním čísle stránky dostane na vstupu - přímo jako parametry konstruktoru. To znamená, že třída se ani nestará o zachycení vstupu (například části URL, GET parametru a podobně). To je v kompetenci vašeho kontroleru. Třída tedy opravdu řeší "pouze" příslušný algoritmus stránkování a díky tomu je naprosto univerzální, všestranně použitelná a velice užitečná.

Přehled metod

Metoda Význam
public __construct(
int $current_page_no,
int $items_per_page,
callable $URL_creator
)		 Již při vytvoření instance musí být stránkovač správně inicializován. Pojďme si rozebrat parametry:
  • $current_page_no
    Aktuální číslo stránky. To musí ze vstupu zachytit a předat kontroler, který instanci stránkovače vytváří.

  • $items_per_page
    Počet položek na stránku. Pozor! Nesmí být větší než limit určený systémovou konfigurací - SysConf_Jet_Data_Paginator.

  • $URL_creator
    Stránkovač má za úkol i vygenerovat URL stránek seznamu. Ovšem sám o sobě neví jak má URL stránky vypadat - to je stále záležitostí kontroleru. Potřebuje tedy generátor / vytvářeč URL, kterému předá číslo stránky a ten se již postará o vygenerování URL.

    Prototyp anonymní funkce generátoru: function( int $page_no ) : string
    {
        return     '...some url ...'.$page_no;     
    };
public setURLCreator(
callable $URL_creator
) : void		 Pokud by to bylo nutné, tak je možné generátor / vytvářeč (viz konstruktor třídy) vyměnit i po vytvoření instance třídy.
public setData(
array|Data_Paginator_DataSource $data
) : void		 Metoda slouží k předání dat, která jsou určena ke stránkování - tedy celého seznamu. Může jít o prosté pol, ale i datový zdroj. Tedy instanci třídy implementující potřebné rozhraní.

V praxi je častější druhá možnost a například DataModel se spoluprací se stránkovačem přímo podporuje.
public setDataSource(
Data_Paginator_DataSource $data
) : void		 Viz metoda setData. Metoda setDataSource má ten rozdíl, že neakceptuje prosté pole, ale pouze instanci iterátoru.
public getData(
) : iterable		 Vrátí výsledek. Tedy:
  • Pokud jsou vstupní data pole, pak je vrácen jeho příslušný úsek - část pole odpovídající dané stránce
  • Pokud je na vstupu iterátor, tak je nastaven - je zavolána jeho příslušná metoda setPagination a pro pořádek je jeho instance vrácena jako návratová hodnota.
public getDataItemsCount(
) : int		 Vrátí celkový počet záznamů v původním seznamu položek.
public getPagesCount(
) : int		 Vrátí počet stránek.
public getCurrentPageNo(
) : int		 Vrátí aktuální číslo stránky.
public getPrevPageNo(
) : int|null		 Vrátí číslo předchozí stránku. Pokud žádná předchozí stránka není (aktuální je první), pak vrací null.
public getNextPageNo(
) : int|null		 Vrátí číslo následující stránky. Pokud žádná následující stránka není (aktuální je poslední), pak vrátí null.
public getDataIndexStart(
) : int		 Vrátí počáteční index dat aktuální stránky - ve smyslu práce s polem.
public getDataIndexEnd(
) : int		 Vrátí konečný index dat aktuální stránky - ve smyslu práce s polem.
public getShowFrom(
) : int		 Vrátí údaj určený pro uživatele: Zobrazena položka od: X (vrátí hodnotu X)
public getShowTo(
) : int		 Vrátí údaj určený pro uživatele: Zobrazena položka do: X (vrátí hodnotu X)
public getCurrentPageNoIsInRange(
) : bool		 Indikuje zda je předané platné číslo stráneky v rozsahu.

Může se stát, že bylo předáno číslo stránky 11, ale stránek je reálně pouze 10. V takovém případě metoda vrátí false, jinak true.
public getPrevPageURL(
) : null|string		 Vrátí URL předchozí stránku. Pokud žádná předchozí stránka není (aktuální je první), pak vrací null.
public getNextPageURL(
) : null|string		 Vrátí URL následující stránky. Pokud žádná následující stránka není (aktuální je poslední), pak vrátí null.
public getLastPageURL(
) : null|string		 Vrátí URL poslední stránky.
public getFirstPageURL(
) : null|string		 Vrátí URL první stránky.
public getPagesURL(
) : array		 Vrátí URL všech stránek.
public toJSON(
) : string		 Převede informace o stránkování do formátu JSON.
public jsonSerialize(
) : array		 Instanci stránkovače je možné předat funkci json_encode.
Předchozí kapitola
Jet\Data_Forest
Další kapitola
Jet\Data_Paginator_DataSource
GitHub