Jet\MVC_Page

Už jsme si vysvětlili co je to báze a stránka a jakou roli plní v Jet MVC.

Nyní se koukneme podrobně na třídu Jet\MVC_Page a tedy také na rozhraní Jet\MVC_Page_Interface

I tato třída je instancována zásadně pomocí příslušné továrny.

Třída Jet\MVC_Page je jednou z největších co v Jet vůbec jsou. Proto je rozdělená na části, tedy na jednotlivé traity. A obdobně rozdělím i popis této třídy.

Obecné - trait Jet\MVC_Page_Trait_Main

Tento trait řeší základní a obecné věci.

Metoda Význam
public getBaseId(
): string		 Vrátí ID báze ke které stránka náleží.
public setBaseId(
string $base_id
): void		 Nastaví ID báze ke které stránka náleží.

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public getBase(
): MVC_Base		 Vrátí instanci báze ke které stránka náleží.
public setBase(
MVC_Base $base
): void		 Nastaví bázi ke které stránka náleží.

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public getLocale(
): Locale		 Vrátí lokalizaci ke které stránka náleží.
public setLocale(
Locale $locale
): void		 Nastaví lokalizaci ke které stránka náleží.

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public getId(
): string		 Vrátí ID stránky.
public setId(
string $id
): void		 Nastaví ID stránky.

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public setSourceModuleName(
string $source_module_name
): void		 Nastaví název modulu, který stránku definuje (pokud se jedná o stránku definovanou modulem)

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public getSourceModuleName(
): void		 Vrátí název modulu, který stránku definuje (pokud se jedná o stránku definovanou modulem)

Tato metoda je určená primárně pro nástroje (např. Jet Studio)
public getKey(
): string		 Vrátí klíč stránky.

Klíč je textový řetězec složený takto: ID_stránky:kód_lokalizace:ID_báze
public getName(
): string		 Vrátí interní název.

Interní název je určený pro věci jako je Jet Studio, nebo administrace. 
Údaj není určen k použití pro zobrazení koncovému uživateli (běžnému návštěvníkovi).
public setName(
string $name
): void		 Nastaví interní jméno. Viz metoda getName()
public getIsActive(
): bool		 Indikuje zda stránka je / není aktivní. 

Stránka má svůj vlastní příznak zda je aktivní, ovšem tato metoda nezohledňuje pouze ten. Nejprve pomocí metody getIsDeactivatedByDefault zjistí, zda náhodou není neaktivní nějaký nadřazený element a pokud ano, stránka je automaticky neaktivní. Pouze pokud jsou nadřazené stránky aktivní, tak přichází ke slovu vlastní příznak stránky.
public setIsActive(
bool $is_active
): void		 Nastavuje vlastní příznak stránky je / není aktivní.
public getIsDeactivatedByDefault(
): bool		 Zjišťuje zda je neaktivní nějaký z nadřízených elementů. Tedy true vrátí pokud:
  • Je neaktivní rodičovská stránka
  • Je neaktivní příslušná lokalizace
  • Je neaktivní příslušná báze
public getTitle(
): string		 Vrátí titulek stránky. Titulek je již určený pro použití například na webu, nebo e-shopu - tedy pro koncové uživatele.
public setTitle(
string $title
): void		 Nastaví titulek stránky.
public getIcon(
): string		 Stránka může mír přiřazenou ikonu. Jak je ikona konkrétně implementována a zobrazene, to už je na vás.
Já používám např. ikony Font Awesome a tak to je udělaná i ukázková aplikace, ale v žádném případě to nemusí být ta jediná cesta. 
Důležité je, že údaj o ikoně ke stránce můžete přiřadit a pak použít. Hodí se např. pro administraci a podobně.
public setIcon(
string $icon
): void		 Nastaví ikonu stránky.
public getMenuTitle(
): string		 Stránka může mít extra titulek určený pro menu. Pokud není nastaven, je použit titulek hlavní.
public setMenuTitle(
string $menu_title
): void		 Nastaví titulek stránky pro menu.
public getBreadcrumbTitle(
): string		 Stránka může mít extra titulek určený pro drobečkovou navigaci. Pokud není nastaven, je použit titulek hlavní.
public setBreadcrumbTitle(
string $breadcrumb_title
): void		 Nastaví titulek stránky pro drobečkovou navigaci.
public getSSLRequired(
): bool		 Indikuje zda stránka vyžaduje / nevyžaduje https spojení.

Stránka má svůj vlastní příznak zda je https vyžaduje, ale opět není zohledněn pouze tento příznak. Nejprve pomocí metody isSSLRequiredByDefault zjistí, zda náhodou https vyžadováno nějakým z nadřízených elementů a pokud ano, tak automaticky i daná stránka vyžaduje https.
public setSSLRequired(
bool $SSL_required
): void		 Nastavuje zda stránka vyžaduje / nevyžaduje https spojení.

Tato možnost je dnes již prakticky k ničemu. Je rozhodně lepší mít na https celé báze. Ale kvůli konzistenci tato možnost je.
public isSSLRequiredByDefault(
): bool		 Zjišťuje zda https vyžaduje některý z nadřízených elementů. True vrátí pokud:
  • Https vyžaduje rodičovská stránka
  • Https vyžaduje příslušná lokalizace
  • Https vyžaduje příslušná báze
public isCurrent(
): bool		 Vrátí true pokud je daná instance stránky tou, která je právě aktuální pro zpracovávaný požadavek.
public isInCurrentPath(
): bool		 Vysvětlím raději hned na příkladu. Dejme tomu že aktuální stránka je stránka s ID stranka-3.

Ovšem stranka-3 má rodiče stranka-1 a stranka-2.

Tedy aktuální cesta k otevřené stránce je: _homepage_ / stranka-1 / stranka-2 / stranka-3

Vy pracujete s instancí stranka-2.

To znamená, že metoda vrátí true, protože stranka-2 je v aktuální cestě. Nebo se také dá říct, že stranka-2 je jednou z nadřazench stránek stránky aktuální.
public setDataFilePath(
string $data_file_path
): void		 Nastaví cestu k souboru kde je uložená definice stránky.

Nastavení hodnoty provádí Jet automaticky při inicializaci.
public getDataFilePath(
bool $actualized=false
): string		 Vrátí cestu k souboru kde je uložená definice stránky.

Pokud je parametr $actualized = true, tak vrátí cestu aktualizovanou podle aktuální podoby definice. Tedy cestu která bude reflektovat případnou změnu URL stránky a tedy i jejího adresáře.
public getDataDirPath(
bool $actualized=false
): string		 Vrátí cestu k adresáři, kde je uložená definice stránky. 

Pokud je parametr $actualized = true, tak vrátí cestu aktualizovanou podle aktuální podoby definice. Tedy cestu která bude reflektovat případnou změnu URL stránky a tedy i jejího adresáře.

Inicializace - trait Jet\MVC_Page_Trait_Initialization

Tento trait řeší vše kolem inicializace seznamu stránek. Nebo možná lépe řečeno jejich nahrání a sestavení všech potřebných dat.

Metoda Význam
public static createByData(
MVC_Base_Interface $base,
Locale $locale,
array $data
): static		 Vytvoří instanci stránky na základě dat v poli. Slouží zejména pro interní účely a pro účely nástrojů. V aplikačním prostoru se běžně nepoužívá.
public static getRelativePathMap(
MVC_Base $base,
Locale $locale
): array		 Další metoda zejména pro interní účely. Vrátí mapu relativních cest (částí URL) stránek dané lokalizace dané báze. Tuto metodu (a tedy i mapu) používá router.
public static loadMaps(
MVC_Base $base,
Locale $locale
): array		 Pro interní účely. Vátí interní mapy, které systém potřebuje pro práci se stránkami. 
public __wakeup(
) : void		 Magická metoda, která donastaví deserializovanou instanci stránky (zejména po načtení z cache). 

Stromová struktura - trait Jet\MVC_Page_Trait_Tree

Tento trait řeší vzájemné vztahy stránek, které jsou uspořádány do stromové struktury.

Metoda Význam
public setParentId(
string $page_id
) : void		 Nastavuje ID rodičovské / nadřazené stránky.

Metoda je určená opět primárně pro nástroje jako je Jet Studio.
public getParent(
): static|null		 Vrátí instanci rodičovské / nadřazené stránky. Kořenová stránka (tedy homepage) pochopitelně vrátí null.
public getOrder(
): int		 Vrátí pořadí (nebo dá se říct i prioritu) stránky. To je možné použít například pro seřazení různých menu a podobně.
public setOrder(
int $order
): void    		 Nastaví pořadí / prioritu stránky.
public getPath(
): array		 Vrátí cestu ke stráne od kořenové stránky v podobě pole obsahujícího ID rodičovských stránek.
public getChildren(
): MVC_Page[]		 Vrátí potomky / podřízené stránky v podobě pole obsahujícího jejich instance. Vrací pouze potomky z následující úrovně. Nikoliv potomky potomků.
public getChildrenKeys(
): array		 Vrátí klíče potomků stráky (klíč: viz metoda getKey() ) a to pouze z následující úrovně (ne z dalších úrovní, tedy potomků potomků).
public getChildrenIds(
): array		 Vrátí ID potomků stráky a to pouze z následující úrovně.

URL - trait Jet\MVC_Page_Trait_URL

Jak název napovídá, tak trait řeší vše kolem URL stránek.

Metoda Význam
public getURL(
array $path_fragments = [],
array $GET_params = []
): string		 Vrátí celou URL stránky a to tak aby odpovídala definici. Tedy pokud stránka vyžaduje https, pak vrátí URL s https a vice versa. 

Důležité jsou parametry metody. Pojďme na ně kouknout:

$path_fragments:
Dejme tomu, že chcete URL stránky, jejíž URL je dle definice https://domena/stranka/, ale to vám nestačí.

Například je to stránka nějakého katalogu zboží a vy potřebujete URL nějakého produktu. Tedy toto:
https://domena/stranka/kategorie/produkt/ 

Celkem běžná situace. Každá ta část URL by navíc měla být příslušně zakódována a musí být sestaven řetězec ...
Jek to udělat? Takto: MVC:getPage($id)->getURL(path_fragments: [$catalog_url, $procut_url]) A Jet už se o zbytek postará, nemusíte to děla ručně.

$GET_params:
A co když chceme do URL nějaké GET parametry? Samozřejmě žádný problém: MVC::getPage($id)->getURL(GET_params:['param'=>$value, 'param2'=>$value2])
public getURLPath(
array $path_fragments = [],
array $GET_params = []
): string		 Funguje stejně jako getURL, nevrací však celou URL, ale pouze URL bez schématu a domény - cestu.

Například místo: https://domena/stranka/

vrátí pouze: /stranka/

Parametry fungují zcela identicky jako u metody getURL
public getNonSchemaURL(
array $path_fragments = [],
array $GET_params = []
): string		 Funguje stejně jako getURL, nevrací však celou URL, ale pouze URL bez schématu.

Například místo: https://domena/stranka/ 

vrátí pouze: //domena/stranka/

Parametry fungují zcela identicky jako u metody getURL
public getNonSslURL(
array $path_fragments = [],
array $GET_params = []
): string		 Funguje stejně jako getURL, ovšem bez ohledu na definici vrátí URL s http

Parametry fungují zcela identicky jako u metody getURL
public getSslURL(
array $path_fragments = [],
array $GET_params = []
): string		 Funguje stejně jako getURL, ovšem bez ohledu na definici vrátí URL s https

Parametry fungují zcela identicky jako u metody getURL
public setRelativePathFragment(
string $relative_path_fragment
): void		 Nastavuje část URL, která se týká dané stránky. 

Slouží pro nástroje jako je Jet Studio.
public getRelativePathFragment(
): string		 Vrátí část URL, která se týká dané stránky. 

Slouží pro nástroje jako je Jet Studio.
public getRelativePath(
): string		 Vrátí část URL, která je relativní cestou. Ukažme si to raději na příkladu.

Báze a lokalizace má kořenovou URL http://domena/cs/
Stránka má celou URL ttp://domena/cs/o-nas/kontakt/

Relativní cesta je tedy o-nas/kontakt/
public setRelativePath(
string $relative_path
): void		 Nastaví relativní cestu. 

Slouží pro nástroje jako je Jet Studio.

Autentizace a autorizace - trait Jet\MVC_Page_Trait_Auth

Trait řeší záležitosti kolem neveřejných stránek. Tedy těch, kde uživatel / návštěvník musí být přihlášen a mít potřebná oprávnění.

Metoda Význam
public getIsSecret(
): bool		 Indikuje zda stránka je / není tajná. Tedy zda vyžaduje přihlášení uživatele a ověření jeho práv.

Stránka má svůj vlastní příznak zda je tajná, ale i zde opět není zohledněn pouze tento příznak. Nejprve pomocí metody isSecretByDefault zjistí, zda je tajný nějaký z nadřízených elementů a pokud ano, tak automaticky je tajná i daná stránka - bez ohledu na její vlastní nastavení (příznak může být false a i tak je tajná).
public setIsSecret(
bool $is_secret
): void		 Nastavuje zda daná strána je / není tajná.
public isSecretByDefault(
): bool		 Zjišťuje zda je tajný nějaký z nadřazených elementů. Tedy buď rodičovská stránka, nebo celá báze. V takovém případě metoda vrátí true a stránka je automaticky tajná.
public authorize(
): bool		 Tuto metodu sránky volá router. 

Pokud je stránka přístupná z hlediska kontroly oprávnění, vrátí true, jinak false.

Stránka je přístupná když:
  • Není tajná
  • Je tajná, ale uživatel je přihlášen a zároveň má potřebné oprávnění k návštěvě stránky
public accessAllowed(
): bool		 Tato metoda je určena k všeobecnému použití - tedy zejména v aplikačním prostoru.

Klasická situace: Máte stránku a je možné, že by pro uživatele nemusela být přístupná a odkaz na ní chcete zobrazit pouze když přístupná je. Uděláte to takto: $page = MVC::getPage($id);
if($page->accessAllowed()) {
     echo $page->getURL();
}

Layout - trait Jet\MVC_Page_Trait_Layout

Dle názvu je jasné, že zde se řeší vše kolem návaznosti na layout, tedy na Jet\MVC_Layout.

Metoda Význam
public getLayoutScriptName(
): string		 Vrátí název layout skriptu nastaveného u stránky.
public setLayoutScriptName(
string $layout_script_name
): void		 Nastaví název layout skriptu pro stránku. 

Sice primárně určeno pro Jet Studio a podobné nástroje, ale již jsem tuto metodu použil v aplikačním prostoru.
public getLayoutsPath(
): string		 Vrátí cestu k adresáři, kde jsou layouty. V praxi je to ekvivalent volání $page->getBase()->getLayoutsPath();
public initializeLayout(
): void		 Metoda inicializuje layout dle definice stránky. Volá se při samotném renderování výstupu. 

Meta tagy - trait Jet\MVC_Page_Trait_MetaTags

A tento trait řeší vše kolem meta tagů určených pro HTML hlavičky stránky.

Metoda Význam
public getMetaTags(
): MVC_Page_MetaTag[]		 Vrátí výchozí meta tagy stránky. A pozor, vrací všechny výzhozí meta tagy co ke stránce patří. To znamená i ty definované v rámci báze. Pokud báze i samotná stránka definuje stejný meta tag (se stejným atributem), tak nadřazený je ten, který definuje stránka sama.

Právě tato metoda se používá pro generování výstupu.
public setMetaTag(
string $attribute,
string $attribute_value,
string $content
) : void		 Nastaví meta tag stránky. Pokud nebyl obdobný meta tag ještě definován, tak jej přidá. Jinak nastaví hodnotu content u již definovaného meta tagu (i když šlo o meta tag definovaný bází a ne stránkou)

Tato metoda je užitečná pro aplikační prostor. Např. když chcete nastavit description a key words podle aktuálního článku, či produktu (pokud děláte e-shop)
public setMetaTags(
MVC_Page_MetaTag[] $meta_tags
): void		 Hromadně nastaví definici meta tagů stránku. Neovlivňuje tagy definované bází, ale pouze ty definované stránkou samotnou.
public addMetaTag(
MVC_Page_MetaTag $meta_tag
): void		 Přidá meta tag definici stránky.

Http hlavičky - trait Jet\MVC_Page_Trait_HttpHeaders

Tohle už je možná trochu specifické. Stránka může definovat krom vše homožného i http hlavičky, které budou vráceny v odpovědi. A k čemu že je to dobré? Například máte plně statickou stránku, pro její zobrazení není třeba žádná operace - tedy nemáte možnost poslat hlavičky pomocí nějaké aplikační logiky. Ale i tak potřebujete z nějakého důvodu specifikovat jaké http hlavičky budou v odpovědi poslány. A třeba vás napadne i další využiti.

Metoda Význam
public getHttpHeaders(
): array		 Vrátí definované http hlavičky. Pozor! Zahrnuje i hlavičky definované některou z nadřazených stránek.

Vráceno je prosté asociované pole, kde klíč je název http hlavičky a hodnota prvku pole je zároveň hodnota hlavičky.
public setHttpHeaders( 
array $http_headers 
): void		 Nastaví http hlavičky definici dané stránky (ne nadřazeným stránkám).

Opět platí že definice hlaviček je prostá - asociované pole, kde klíč je název a hodnota je prostě hodnota hlavičky.

Interní parametry - trait Jet\MVC_Page_Trait_Parameters

Jde o vámi libovolně volitelné parametry a jejich hodnoty. Vše využitelné vaší aplikací. Tedy máte možnost stránkám jednoduše nadefinovat to, co u nich ještě definováno není.

Příklad? Tak dejme tomu že si automaticky generujete navigaci a různé meníčka. Ale jak určit, která stránka bude například v hlavním a která ne? Na to můžete použít právě interní parametry a definovat si tak vlastní příznak u stránek. A určitě na spoustu dalších věcí.

Metoda Význam
public getParameters(
): array		 Vrátí seznam interních parametrů v podobně asociovaného pole, kde klíč je název parametru.

Na rozdíl od meta tagů a http hlaviček interní parametry jsou vztažené vždy pouze na konkrétní stránku. Nikdy tedy nevrací parametry stránky rodičovské a podobně. 
public setParameters(
array $parameters
): void		 Hromadně nastaví parametry dané stránce. Parametry jsou opět v podobě asociovaného pole.
public setParameter( 
string $key, 
mixed $value 
): void		 Nastaví jeden parametr.
public getParameter(
string $key,
mixed $default_value = null
): mixed		 Vrátí hodnotu zadaného parametru. Pokud daný parametr neexistuje, pak vrátí výchozí hodnotu.
public parameterExists(
string $key
): bool		 Zjišťuje zda parametr existuje.

Obsah - trait Jet\MVC_Page_Trait_Content

A teď obsah stránky, tedy dosti zásadní věc.

Statická stránka, nebo stránka generovaná pomocí callback

Metoda Význam
public setOutput(
string|callable $output
): void		 Jak jste se dočetli zde tak je několik způsobů jak stránka definuje co bude jejím výstupem. 
A tato metoda nastavuje výstup v situaci:
  • Když je stránka plně statická. Tedy prostě posílá nějaký HTML výstup a hotovo.
  • Když bude stránka generována pomocí nějaké funkce / metody.
public getOutput(
): string|callable|null		 Vrátí nastavený výstup stránky. Viz metoda setOutput()

Definovaná sada obsahu

Metoda Význam
public getContent(
): MVC_Page_Content[]		 Vrátí definice obsahu dané stránky.

Pochopitelně zde není žádná dedičnost (jako v případě meta tagů a http hlaviček). Každá stránka má svou vlastní definici.
public setContent(
MVC_Page_Content[] $contents
): void		 Hromadně nastaví definici obsahu. 
public addContent(
MVC_Page_Content $content
): void		 Přidá jednu definici obsahu.
public removeContent(
int $index
): void		 Odstraní definici obsahu na dané pozici, kde 0 = první pozice. 

Keš - trait Jet\MVC_Page_Trait_Cache

Keš MVC je samostatné téma. Ale alespoň stručně vysvětlím význam následujících metod, které se týkají kontextu keše.

Co je kontext keše? Záznam v keši je nutné nějak identifikovat. Pro tuto identifikaci slouží ID báze, kód lokalizace, ID stránky, pak klíč identifikující konkrétní obsah (tedy konkrétní modul, kontroler atd).

Ovšem toto v praxi to nemusí stačit. Například tato stránka kterou čtete je z pohledu MVC stále jedna a tatáž stránka pro všechny kapitoly dokumentace na které modul Web.Doc.Browser právě zobrazil tento článek. I když překliknete na jinou kapitolu, vždy to bude pro MVC tatáž báze, tatáž stránka a tentýž modul.

Tedy pro identifikaci záznamů v keši již nestačí údaje z Jet MVC. Je nutné přidat další rozlišení. V tomto konkrétním případě, na který právě teď koukáte, je tím rozlišením ID článku dokumentace. Právě to jaký máte otevřený článek / kapitolu dokumentace je konkrétní kontext.

Co bude tvořit kontext ve vaší aplikaci? Tedy pokud vůbec nějaký kontext pro danou situaci budete potřebovat ... To už jsou otázky na vás, je to o tom jak projekt navrhnete. Co kontextem bude není pevně dáno.

Metoda Význam
public setCacheContext( 
string $cache_context 
): void		 Nastaví kontext cache.

Metoda určená pro aplikační prostor.
public getCacheContext(
): string		 Vrátí nastavený kontext.

Handlery - trait Jet\MVC_Page_Trait_Handlers

Trait je téměř na konci této kapitoly dokumentace, ale o to je zajímavější. Právě zde jsou metody mající na starosti zpracování a zobrazení stránky.

Metoda Význam
public resolve(
): bool		 Tuto metodu volá router na konci procesu rozpoznání požadavku. Tedy router už ví všechno co je třeba, ale poslední slovo má stránka. Ta udělá to, že o vyřešení situace požádá veškerý svůj obsah - jednotlivé kontrolery modulů a jejich metody resolve. Pokud má nějaký z modulů potřebu ještě něco zjišťovat, tak to dělá právě zde. Ale ukažme si raději konkrétní příklad. 

Jak víte z této kapitoly, tak může existovat nezpracovaná část URL (která nenáleží ke stránce). Ta část URL může představovat URL například nějakého článku.

Opět na takovou věc právě koukáte.
URL této stránky je: https://www.php-jet.net/doc/mvc/plne-vyuziti-mvc-v-php-jet/stranka-page/jet-mvc-page
Nezpracovaná část URL této stránky je "mvc/plne-vyuziti-mvc-v-php-jet/stranka-page/jet-mvc-page". 

A právě zde se vyřeší otázka "co s tím". Během tohoto procesu si modul Web.Doc.Browser tuto informaci zpracuje a určí, že je to v pořádku a je to URL článku, který právě teď čtete.
K takovým operacím je tato část procesu zpracování (tedy metoda resolve a její činnost) určena. 

Pokud resolve vrátí true, tak router ví, že vše je v pořádku a připraveno a může se pokračovat.

Ovšem resolve může vrátit i false a v takovém případě router ví, že něco není v pořádku a zpracovávaná URL není platná. Výsledkem je 404.
 public handleHttpHeaders(
): void		 Tato metoda fakticky posílá definované http hlavičky jako odpověď. Je to tedy již součást odpovědi.
public render(
): string		 Tato metoda sestaví výstup stránky.

Pozor! Výstup (sestavenou stránku) nepošel ined uživateli, ale vrátí jej jako návratovou hodnotu!

Je tedy možné si vygenerovat výstup stránky jak potřebujete a použít jej jak potřebujete. Stránku je možné sestavit i samostatně - třeba i bez celého procesu zpracování požadavku.

Ale pochopitelně primárním určením této metody je poslat výstup uživateli.

Ukládání - trait Jet\MVC_Page_Trait_Save

A poslední, nikoliv však nedůležitý, trait. Zde jsou metody pro ukládání definice stránky.

Metoda Význam
public toArray(
): array		 Obdobě jako u všech ostatních entit i stránka má metodu pro převedení objektů do asociovaného pole (tedy surových dat), které je následně určeno k uložení.
public saveDataFile(
): void		 Uloží datový soubor definice stránky.
Předchozí kapitola
Stránka / Page
Další kapitola
Obsah / Jet\MVC_Page_Content
GitHub