WebToDate/Příručka vývojáře/Extenze

Úvod

Co jsou extenze

V systému WebToDate jsou stránky, které návštěvník prohlíží, sestavovány buď generátorem stránek nebo skriptem pro zobrazování jednotlivých článků či dynamických objektů ve stránce. V obou případech je jako základ stránky použitá zvolená šablona a na ní jsou umísťovány prvky vkládané redakčním systémem z databáze, které jsou formátovány zvolenými WebToDate styly.

V obou případech lze do procesu sestavování kódů stránek programově vstupovat. V případě generování statických stránek lze přidat kód, který se spouští po sestavení HTML kódu stránky, ale před jejím uložením na disk serveru. V případě dynamicky sestavovaných stránek jednotlivých článků lze do tohoto procesu vstoupit jednak na začátku (tj. po vykonání úvodních kontrol a před zahájením vlastního sestavování) a jednak na konci (po sestavení HTML stránky a před jejím zasláním do prohlížeče návštěvníka.

Programovým kódům, které takto vstupují do procesu sestavování stránek, se říká extenze. Jsou to tedy bloky PHP kódu volané v rámci generování statických stránek či v rámci sestavování dynamických stránek článků, které mohou modifikovat již sestavený HTML kód nebo provádět jakékoliv jiné akce, které jsou zpravidla závislé na tom, jaká stránka se zrovna sestavuje. Z toho důvodu musí být v těchto kódech k dispozici proměnné, podle kterých lze zjistit informace o sestavované stránce, např. ID článku apod.

Následující diagram např. znázorňuje, jak z hlediska extenzí pracuje skript pro dynamické zobrazování jednotlivých článků.

Extenze prvního typu (preprocess) se volá před zahájením vlastního sestavování stránky. Zde je možné doplnit kódy, které např. ovlivňují, zda se vůbec má stránka zobrazit apod. Extenze druhého typu (postprocess) se volá ve chvíli, kdy je stránka sestavená, ale není ještě odeslaná do prohlížeče. Zde je možné doplnit kódy které přidávají další obsah do stránky nebo stávající modifikují apod.

Jednoduché extenze mohou být vytvářeny jako samostatné doplňky. Typicky se jedná o jeden PHP soubor, který provádí nějakou konkrétní akci. Složitější extenze mohou být součástí nějakého modulu – pokud chceme vytvořit extenzi, která funguje na základě nastavení prováděných administrátorem WebToDate či dokonce dat zadávaných redaktory, vytváří se zpravidla modul a extenze pracuje s nastaveními či daty tohoto modulu.

Fyzicky jsou extenze bloky PHP kódu v samostatných souborech, které se inkludují do určených souborů v adresáři config.

Důležité je, že seznam podporovaných typů extenzí (tj. těch míst, kde se extenze volají) je přesně dán a tím je dáno i to, do kterých stránek lze pomocí extenzí vstupovat. Nejsou podporovány extenze modulů. To např. znamená, že pokud se po instalaci modulu Kalendář akcí na dané adrese zobrazuje stránka prezentující seznam nejnovějších akcí, do této stránky již nelze programově vstupovat a její vlastnosti lze nastavovat pouze redakčním rozhraním tohoto modulu.

Příklady využití

Jednoduchý příklad extenzí – rozšíření slovníku klíčových slov WebToDate o klíčové slovo, které v šablonách a stylech reprezentuje počet shlédnutí daného článku, je detailně popsán v následujících kapitolách.

Standardně dodávané extenze jsou např. extenze pro:

• Cachování článků v souborové cache
• Zvýrazňování výsledků fulltextového hledání (hledaných slov)

Standardně dodávané moduly, které obsahují extenze jsou např.:

• Diskuse – extenze zajišťuje zobrazování diskusních příspěvků pod článkem
• Ankety – extenze zajišťuje vkládání hlasovacího formuláře do stránky článku
• Neveřejná část – extenze zajišťují zjišťování, zda daný článek patří do neveřejné zóny a ověřují přístup uživatele k danému článku.

Příklady uživatelských extenzí mohou být např.:

• Extenze, která na základě metadat zprávy doplňuje do stránky se zprávou další data či informace z jiného zdroje (jiné databáze či externího serveru).
• Extenze, která modifikuje vygenerovaný kód stránky, např. generujeme-li XML stránku a chceme určité znaky nahrazovat znakovými entitami XML.
• Extenze, která při zobrazování zpráv zapisuje podrobné informace sloužící ke statistickému zpracování (identifikační údaje uživatelů, podklady pro podrobnější statistiky návštěvnosti apod.).

Postup při vytváření extenzí

V adresáři scripts/modules (pro extenze pro dynamické zobrazování článků) resp. application/modules (pro extenze pro generátor stránek) založte vlastní adresář a v tomto adresáři nový PHP soubor, ve kterém se bude nacházet programový kód extenze. Název souboru může být libovolný, ve WebToDate se používá konvence, že názvy tohoto typu souborů začínají znakem podtržítko.

Do příslušného souboru v adresáři config vložte referenci na tento nově založený soubor. Soubory v tomto adresáři jsou popsány v kapitole Instalace extenze.

Nyní je možné psát vlastní PHP kód této extenze, který se okamžitě aplikuje. Pro psaní kódu je především potřebná znalost proměnných, které lze v extenzi využít, seznamy těchto proměnných jsou uvedeny v kapitole Reference. Pro většinu extenzí je nutná rovněž znalost databázové struktury databáze WebToDate, která je popsána v samostatném dokumentu.

Příklad extenze – čtenost článků

Dynamické zobrazování článků

Jako příklad si uveďme extenzi, která nahrazuje klíčové slovo <!—WTD_F(CTENOST_CLANKU)--> HTML kódem s uvedením počtu shlédnutí daného článku. Klíčové slovo umístíme podle pravidel kamkoli, protože vždy budeme mít k dispozici ID aktuální zprávy.

Předpokládejme tedy, že jsme umístili klíčové slovo <!—WTD_F(CTENOST_CLANKU)-->. Vytvoříme si soubor (/scripts/modules/ctenost/_ctenost.php) s následujícím obsahem:

<?php
//	*** extenze vklada pocet shlednuti zpravy ***
	
//	Klicove slovo, ktere se bude v textu nahrazovat
	$myKeyword = "<!--WTD_F(POCET_SHLEDNUTI)-->";
	
//	Zjistime pocet shlednuti (v promenne $news_id je ulozeno ID zpravy)
	$sql = "SELECT NUMOFIMP = COALESCE((SELECT SUM(IMPRESSIONS) FROM NEWSIMPRESSIONS WHERE SUMMARIZED=0 AND ZPRAVAID=" . $news_id . "),0) + COALESCE((SELECT 
 SUM(IMPRESSIONS) FROM NEWSIMPSUM WHERE ZPRAVAID=" . $news_id . "),0)";
	$res = $db->query( $sql );
	$rec = $db->fetch_array( $res );
	$pocet_shlednuti = ( is_array($rec) ? $rec['NUMOFIMP'] : 0 );
	
//	Sestavime si HTML kod, kterym nahradime vyskyt klicoveho slova
	$html_kod = '<B> Počet shlédnutí: ' . $pocet_shlednuti . ' <B>';
	
//	Vsechny vyskyty klicoveho slova nahradime sestavenym HTML kodem
	$content = str_replace ( $myKeyword, $html_kod, $content );
?>

Generování statických stránek

Rozdílem při použití extenzí u generovaných statických stránek je, že v nich nejsou k dispozici informace o zpracovávaných zprávách. Pokud je tedy například potřeba znát identifikátor vygenerované zprávy, je nutné jej uvést jako součást klíčového slova zvlášť pro každou zprávu, tzn. klíčové slovo se v tomto případě uvádí nikoli např. ve Stylu, ale ručně přímo u zprávy.

Jako příklad uveďme opět zobrazení počtu shlédnutí dané zprávy. Předpokládejme tedy, že jsme si do zprávy (např. s ID 15) vložili klíčové slovo <!—WTD_F(CTENOST_CLANKU,15)--> (kde xx je ID zprávy). Vytvoříme si soubor (/application/modules/ctenost/_ctenost.php) s následujícím obsahem:

<?php
//	*** extenze vklada pocet shlednuti zpravy ***
//	Klicove slovo, ktere se bude v textu nahrazovat; ID se nachazi mezi *Begin a *End
	$myKeywordBegin = "<!--WTD_F(POCET_SHLEDNUTI,";
	$myKeywordEnd = ")-->";
	
//	Prochazime text, dokud obsahuje klicove slovo
	$pozice = strpos ( $content, $myKeywordBegin );
	
	while ( ($pozice = strpos ( $content, $myKeywordBegin )) !== false ):
//		- posuneme ukazatel na zacatek ID
		$pozice += strlen($myKeywordBegin);
		
//		- ziskame ID
		$id_zpravy = substr ( $content, $pozice, (strpos( $content, $myKeywordEnd, $pozice )-$pozice) );
		
//		- ziskame plne zneni klicoveho slova
		$klicove_slovo = $myKeywordBegin . $id_zpravy . $myKeywordEnd;
		
//		- overime ziskany udaj
		$html_kod = "";
		if ( is_numeric($id_zpravy) ):
//			- ID ziskano, zjistime pocet shlednuti
			$sql = "SELECT NUMOFIMP = COALESCE((SELECT SUM(IMPRESSIONS) FROM NEWSIMPRESSIONS WHERE SUMMARIZED=0 AND ZPRAVAID=" . $id_zpravy . "),0) + 
 COALESCE((SELECT SUM(IMPRESSIONS) FROM NEWSIMPSUM WHERE ZPRAVAID=" . $id_zpravy . "),0)";
			$res = $db->query( $sql ); $rec = $db->fetch_array( $res );
			$pocet_shlednuti = ( is_array($rec) ? $rec['NUMOFIMP'] : 0 );
			
//			- sestavime si HTML kod, kterym nahradime vyskyt klicoveho slova
			$html_kod = '<B> Počet shlédnutí: ' . $pocet_shlednuti . ' <B>';
		endif;
		
//		- nahradime klicove slovo sestavenym HTML kodem
		$content = str_replace ( $klicove_slovo, $html_kod, $content );
	endwhile;
?>

Reference

Instalace extenze

Reference na vytvořené soubory – programové kódy se vkládají do příslušných souborů v adresáři config. Tyto soubory jsou následující.

Soubor	Význam
_preprocess_inc.php	Reference na extenze, které se spouštějí při dynamickém zobrazování zpráv (pomocí skriptu detail.php) jako extenze typu preprocess.
_modules_inc.php	Reference na extenze, které se spouštějí při dynamickém zobrazování zpráv (pomocí skriptu detail.php) jako extenze typu postprocess..
_genmodules_inc.php	Reference na extenze, které se spouštějí při generování statických stránek jako extenze typu postprocess.

Reference mohou být vloženy jako PHP kód např. podle následujícího příkladu.

$cache_file = './modules/mujmodul/_mojeextenze_inc.php';
if( is_file( $cache_file ) ) {include ( $cache_file );};

Obecně lze pro odkaz na soubor s extenzí využívat instrukce include i include_once. Užití druhé instrukce je jistě pohodlnější, ovšem nesmíme zapomenout na to, že jí specifikované tělo se na místo určení vkládá pouze jednou. Proto je nemyslitelné její použití ve skriptu _genmodules_inc.php. Tento skript se totiž mimo jiné využívá při generování podstromu. Tehdy se jednotlivé stránky generují v cyklu a při použití zmíněné instrukce by se tím pádem extenze volala pouze jednou u prvně generované stránky.

Využití knihoven WebToDate

Při tvorbě extenzí je nutné využívat nabízených knihoven, konkrétně Souborové (pro práci se soubory a adresáři) a Databázové (pro přístup a operace s databází).

• Postup práce se Souborovou knihovnou, viz. Souborová knihovna
• Postup práce s databázovou knihovnou, viz. Databázová knihovna.

Extenze pro dynamické zobrazování článků

Při tvorbě extenze jsou k dispozici proměnné, které definují současný obsah stránky, databázový objekt a další užitečné hodnoty. První tabulka obsahuje proměnné přístupné extenzím typu preprocess :

Proměnná	Popis
templateContent	současný obsah generované stránky
db	objekt pro práci s databázovou knihovnou
fa	objekt pro práci se souborovou knihovnou
f_event	událost
f_preview	(bool); určení, zda se jedná o náhled
f_templateid	číslo šablony
f_template_path	cesta k šabloně
f_mime_id	identifikátor typu značkovacího jazyka
f_mime_type	typ značkovacího jazyka
f_pageid	identifikátor stránky
f_pageabbrev	zkratka stránky
f_publikaceid	identifikátor publikace
f_vydaniid	identifikátor vydání
f_jazykid	identifikátor jazyka
f_kategid	identifikátor kategorie
f_layoutid	identifikátor stylu
f_page	číslo stránky pro zobrazení publikace
newsOnDisk	(bool); určení, zda se zprávy ukládají na disk

Druhá tabulka obsahuje proměnné, které jsou dostupné pro extenze typu postprocess navíc. Výše uvedené proměnné jsou pro ně samozřejmě přístupné také.

Proměnná	Popis
news_id	identifikátor zprávy
news_abbrev	zkratka použitá u zprávy
checkNewsStatus	(bool); určení, zda se má kontrolovat status zprávy
isUserLogged	(bool); určení, zda je uživatel přihlášen
newsData	(array); kompletní data zprávy klíče pole jsou např: NADPIS nadpis zprávy POPIS popis zprávy TELO obsah těla zprávy OBRAZEK cesta k obrázku přiřazeného ke zprávě ... atd.

Extenze pro generování stránek

Při tvorbě extenze pro generovaní stránky jsou rovněž k dispozici proměnné, které definují současný obsah stránky, objekty knihoven apod. Podstatným rozdílem ale je, že nejsou k dispozici informace o zpracovávané zprávě (např. identifikátor, název), jen obsah vygenerované stránky.

8	Popis
content	současný obsah generované stránky
db	objekt pro práci s databázovou knihovnou
fa	objekt pro práci se souborovou knihovnou

Extenze a cachování zpráv

Při instalaci extenzí je třeba brát v úvahu i možnost cachování zpráv do souborové cache. Jedná se o volitelný standardně dostupný doplněk WebToDate, jehož nejdůležitější části jsou vytvořené právě formou extenzí.

Důležité při instalaci je právě pořadí uvedení extenzí v souboru _modules_inc.php. Pořadí ovlivňuje, které části stránky se budou ukládat (a tedy i následně číst z cache). Platí, že kód generovaný extenzemi vloženými před extenzí pro cachování (tedy _cache_post_inc.php) se cachuje, kódy generované extenzemi uvedenými za touto extenzí se necachují a načítají se vždy dynamicky. Volba vhodného pořadí je proto poměrně důležitá.

Cache má i extenzi volanou v souboru _preprocess_inc.php, tato extenze by měla být (pokud je instalovaná) volána vždy v tomto souboru jako první.