Vytvoření nového modulu do publikačního systému Xaraya

V rámci svojí diplomové práce jsem sestavil jednoduchý návod, který částečně rozebírá tvorbu nových modulů do publikačního systému Xaraya. Vzhledem k tom, že se jedná o netriviální činnost, která mi i přes určité nemalé znalosti Xarayai zabrala mnoho času, rád se podělím se zkušenostmi. Někomu mohou uvedené informace třeba trochu ulehčit život při tvorbě webu s tímto hodně slušným publikačním systémem.

Všechny moduly tohoto publikačního systému jsou uloženy v podadresáři Xarayai /modules. Vzhledem k tomu, že je tento CMS určen pro širší používání veřejností, vývojáři počítali s možností tvorby nových modulů. Pro tuhle činnost tedy vytvořili jednoduchý příklad. Tento příklad se jmenuje dyn_example a obsahuje základní kostru jakéhokoliv modulu a lze z něj v některých částech snadno, v jiných obtížně, odvodit to, jakou má mít nový modul strukturu a co přesně má obsahovat. Pro použití následujícího textu k vytvoření nového modulu se předpokládá, že si čtenář uzpůsobí výše uvedený příklad ke své požadované funkčnosti, nikoliv že bude vytvářet zcela nový modul od úplného začátku. Text se nezabývá částmi, které jsou snadno odvoditelné z příkladu a bylo by zbytečné je opakovat. Snadno lze plno nutných vlastností nového modulu vyvodit z příkladu dyn_example.

URL adresa a struktura adresářů

Pro vytváření modulu je dobré dodržovat určité konvence, kterých se drží celý publikační systém. Tyto standardy nejsou vyžadovány primárně ve vytvářeném modulu, je možno je porušovat a používat vlastní vymyšlené, ovšem potom může lehce dojít k nefunkčnosti navázání na další moduly, nebo používání hezkých URL adres. Proto doporučuji tyto pravidla používat.

Struktura podadresářů modulu je prostá a jasná. Jak bylo výše uvedeno, každý modul je uložen v podadresáři /modules v adresáři se svým jménem. Tedy na příklad: {adresar_xaraya}/modules/jmeno-modulu/.

Typická struktura adresářů je následující:

/xaradmin
/xaradminapi
/xarblocks
/xarimages
/xartemplates
/xaruser
/xaruserapi

Xaradmin obsahuje administrační část modulu, typicky funkce pro přidání položky, editaci, smazání. V adresáři xaradminapi jsou obsaženy soubory s funkcemi pro API celého publikačního systému. Na příklad funkce, která zabezpečuje zobrazení odkazu na modul v hlavním levém menu Xarayai. V dalším adresáři xarblocks jsou soubory s php kódem pro zobrazení uživatelských bloků menu. Xarimages je primárním adresářem pro obrázky používané v modulu. Obdobou je xartemplates, který udržuje šablony modulu. Poslední dva adresáře jsou podobné adresářům administrace. V xaruser jsou uloženy soubory s funkcemi, které může používat uživatel pro čtení, slouží typicky pro zobrazení obsahu modulu, nebo pro uživatelské nastavení. V xaruserapi opět dřímají funkce pro API systému, na příklad pro dekódování URL adresy nebo zobrazení do uživatelského menu.

Jak je vidět důležité soubory adresářů jsou tu dva. Pro dobré používání a vytváření modulu je nutné pochopit jejich smysl. Adresář, který obsahuje slovo admin, je adresářem, obsahujícím celou administrační část modulu, ke které má přístup uživatel, jenž dostane práva na spravování modulu. To znamená, že to primárně nemusí být pouze administrátor webu. Naopak v adresářích obsahujících slovo users je uložen php kód, který typicky zobrazuje položky (data) modulu. Tyto funkce jsou přístupny těm uživatelům, kteří mají přístup čtení k tomuto modulu. Nemusí to automaticky znamenat uživatele bez přihlášení, to znamená prostého návštěvníka webu.

URL adresa publikačního systému je tohoto tvaru:

index.php?module=jmeno_modulu&type=admin&func=new&dalsi_parametry

• jmeno_modulu: adresářový název modulu, tedy v našem případě novy-modul
• admin: adresáře, ve které je uložen soubor v parametru func. Před jeho jméxno je automaticky doplněno Xar, ve výsledku to tedy je buď adresář xaradmin, xaradminapi, xaruser nebo xaruserapi.
• new: jméno souboru php, který bude vložen

Pokud tedy budeme chtít tedy zavolat soubor moje-funkce.php z podadresáře xarmuj-adresar v testovacím modulu se jménem novy-modul, URL bude vypadat takto:

index.php?module=novy-modul&type=muj-adresar&func=moje-funkce

XML soubory

Každý modul obsahuje maximálně čtveřici standardních xml souborů, vyžadovaných systémem Xaraya. Tyto soubory obsahují informace o modulu nebo vstupní datové položky modulu.

jmeno-modulu.xml

Soubor obsahuje atributy nutné pro registraci modulu do publikačního systému Xaraya

• object name: jméno objektu, tedy modulu, shodné se jménem adresáře
• objectid: id objektu, tak jak leží v databázi v tabulce xar_modules. Je třeba vybrat nějaké volné id, aby nebylo již ve výše uvedené tabulce zahrnuto a nebo nekolidovalo s dalšími moduly.
• label: název nebo pojmenování modulu
• moduleid: registrační id modulu, kterým se modul identifikuje
• urlparam: jméno parametru v URL, kterým se bude předávat číslo položky, na příklad index.php?module=novy-modul&type=muj-adresar&func=moje-funkce&itemid=5
• isalias: povoluje možnost použití jména modulu jako URL aliasu v adrese. Při povolení hezkých URL je adresa následující http://{urlXaraya}/jmeno-modulu/
• properties: seznam datových atributů modulu, ve kterých budou uchovávány položky. Tuhle část XML souboru je možno psát buď ručně nebo pomocí modulu dynamických dat. V tomto se vytvoří nový objekt dat (Admin -> Content -> Dynamic data -> View object -> Create new) a každá položka dat se poté přidá ve formuláři. Až je konfigurace dokončena stačí provést export dat do XML stejnojmenným odkazem. Vznikne soubor, který obsahuje vygenerovanou datovou strukturu, kterou stačí vložit mezi tagy a .

jmeno-modulu.data.xml

 
    1
    Josef
  
  … dalsi radky …

Soubor obsahuje vstupní datové položky pro právě registrovaný modul, struktura je dle datových atributů uvedených v předchozím souboru mezi tagy a . Lze říci, že se jedná o případná zdrojová data vkládaná do modulu.

modulesettings.xml

Soubor s atributy jenž vyjadřují parametrickou nastavitelnost modulu v administraci. V příkladu podporu hezkých adres.

 

• object name: jméno objektu s nastavením modulu
• objectid: id objektu
• moduleid: udává id modulu, do kterého registrujeme data o novém modulu. V tomto případě ukládáme data od modulu jménem jmeno-modulu. Modul, jenže se stará o registraci modulů má identifikační číslo 1 pevně pro všechny instalace publikačního systému Xaraya
• properties: seznam nastavitelných parametrů modulu, které chceme pro modul využívat

usersettings.xml

Soubor s atributy jenž vyjadřují parametrickou nastavitelnost modulu samotným uživatelem. Možnost volby nastavení se objeví v uživatelské části každého modulu. Soubor obsahuje možnosti nastavení modulu.

• object name: jméno objektu s nastavením modulu
• objectid: id objektu
• moduleid: udává id modulu, do kterého registrujeme uživatelská data o novém modulu. V tomto případě ukládáme data od modulu jménem jmeno-modulu. Modul, jenže se stará o uživatelské parametry je modul rolí a má identifikační číslo 27 pevně pro všechny instalace publikačního systému Xaraya
• properties: seznam nastavitelných parametrů modulu uživatelem, které chceme pro modul využívat

PHP soubory

Soubory s php kódem jsou umístěny jak v hlavním adresáři modulu, tak v adresářích xadmin, xaradminapi, xarblocks, xaruser, xaruserapi. Moduly jsou psány systémem separovaných funkcí, každá funkce má své jméno, které musí začínat jménem souboru. Na příklad pro funkci vypisVysledky se musí funkce v modulu jmenovat jmeno-Modulu_vypisVysledky(). Je tedy nutné připojit vždy tento určitý prefix názvu.

Instalační a informační soubory

Pro instalaci modulu do publikačního systému Xaraya se využívá soubor xarinit.php. Obsahuje tři funkce, které budou dále uváděny bez prefixu s názvem modulu, protože ten se liší vždy podle vlastního názvu modulu. Funkce init() zabezpečuje instalaci modulu do systému. Nejprve dojde k nahrání výše uvedených xml souborů s parametry do tabulek, dále jsou uloženy určité konstanty a zaregistrován vlastní modul a její poslední funkcí je zaregistrování přístupových masek k modulu. Např:

xarRegisterMask(‘AddJmenoModulu’,’All’,’jmeno-modulu’,’Item’,’All’,’ACCESS_ADD’);

Tato část zabezpečuje přístupová práva k modulu. Pomocí registrace této masky se dosáhne přidání možnosti vytvoření privilegia přidání položky v administraci přístupových práv, konkrétně v sekci správy privilegií.

Funkce upgare($version) provádí upgrade dat pro původní modul na základě nových nahraných dat. Tento update lze rozlišovat na základě verzí.

Poslední funkcí ze souboru je delete(), která odstra�?uje modul kompletně z tabulek publikačního systému, včetně uložených dat.

Druhým důležitým souborem je xarversion.php. Ten v sobě uchovává informace o modulu, jak systémové, jako je jméno nebo identifikační číslo, tak ryze informační, jako je jméno a email autora.

Soubory s funkčností

Soubory obstarávající funkčnost modulu jsou uloženy v adresářích xadmin, xaradminapi, xarblocks, xaruser nebo xaruserapi. Platí, že každý ze souborů obsahuje jen jednu funkci, jejíž jméno je totožné se jménem souboru. Toto jméno obsahuje pochopitelně i prefix dle jména modulu. Např. pro soubor new.php se funkce v něm bude jmenovat jmeno-modulu_new().

Další popisování programování funkcí do modulu nemá valný význam. Nový modul totiž vždy obsahuje svoje specifické vlastnosti, které je nutno vytvořit samostatně. Tento programovací aparát, to znamená především styl práce s vlastními funkcemi napsanými v jádře publikačního systému Xaraya, je možné získat ze zdrojového příkladu modulu (dyn_example) nebo ze standardních modulů obsažených v systému.

Šablony

Publikační systém Xaraya využívá pro zobrazování HTML kódu do prohlížeče šablony. Tyto soubory obsahují jak výsledný zobrazovaný kód, tak především i skriptovací šablonový jazyk specielně vyvinutý pro tento publikační systém.

Šablony systému fungují jednoduchým způsobem. V souborech s funkčností modulu jsou naplněny pole daty, které chceme zobrazit uživateli a tato pole jsou předána třídě starající se o zobrazení spolu se jménem šablony. Tato třída proparsuje šablonu, provede skriptovací šablonový jazyk, jenž v drtivé většině pracuje s poslanými poli, a těmito hodnotami nahradí v šabloně proměnné. Výsledkem jsou vložená data do šablon a čistý výstupní (X)HTML kód.

Všechny šablony každého modulu jsou uloženy v podadresáři templates. Naplnění a zobrazení šablon je tvořeno samostatným systémem, není třeba ani zadávat jméno šalobny. Automaticky se totiž po provedení určitého souboru modulu zobrazí šablona složená z jeho jména a adresáře, kde leží, tedy dojde k provedení šablony jmeno-modulu/templates/jmeno-adresare-jmeno-souboru.xd. Konkrétně pro funkci modulu jmeno-modulu, která leží v podadresáři admin v souboru new.php, dojde k zobrazení šablony jmeno-modulu/templates/admin-new.xd.

Instalace modulu

Instalace modulu se provádí v administraci modulů (Admin -> Content -> Modules -> View all) tlačítkem Install u instalovaného modulu. Při instalaci dojde ke spuštění xarinit.php, který nahraje konfigurační xml soubory do tabulek. Pro odinstalaci nebo odebrání modulu ze systému se použijí příslušná tlačítka v administraci modulů.