České vysoké učení technické v Praze Fakulta elektrotechnická Bakalářský studijní obor Softwarové technologie a management Semestrální projekt Y38PRO Návod na vytvoření modulu pro CMS Drupal verze 6.x 2009/2010 Autor: Ondřej Sadílek Vedoucí projektu: Ing. Radek Sedláček Ph.D.
1. Úvod Motivací pro vytvoření vlastního modulu pro redakční systém Drupal je potřeba vykonávání vlastního kódu začleněného do systému. Pomocí modulů můžeme rozšiřovat funkcionalitu redakčního systému. Modul může využívat kontext, funkce a proměnné redakčního systému. 2. Adresáře modulu Pro uživatelské moduly Drupalu je určen adresář sites/all/modules/, kde se nachází adresáře pojmenované názvem modulu. Pro nový modul je zde nutné vytvořit další adresář a v tomto adresáři vytvořit tři soubory, ze kterých se modul skládá. Pro názornost si zvolíme název modulu mujmodul. Adresář pro náš modul bude tedy sites/all/modules/mujmodul. V souborech modulu se opět používá název modulu a v našem případě se budou jmenovat následovně. První bude mujmodul.module, ve kterém se nachází vlastní PHP kód modulu. Mujmodul.install obsahuje funkce pro instalaci a odinstalaci modulu. A konečně mujmodul.info obsahuje informace o modulu. Název modulu tvoří i prefix funkcí, které modul využívá. Název funkcí je v následujícím tvaru {nazev_modulu_{hook, kde hook je název předdefinavaných funkcí systému Drupal. Podle předpony se jménem modulu systém ví, který modul funkci volá. A rozpozná jen funkce, které mají stejnou předponu jako je jméno modulu. 3. Soubory modulu Soubory module začínají otevíracím PHP tagem, ale ukončující tag se vynechává. Ponechání ukončující tagu by přineslo problémy při běhu na serveru. Na další řádek souborů module se vkládá kód // $Id$. Id je CVS ID tag, který revizní systém Drupalu vyplní informacemi o revizích a autorovi. Všechny moduly musí mít soubor nazevmodulu.info, který obsahuje informace o modulu a nachází se v adresáři modulu. Bez tohoto souboru by Drupal modul nerozpoznal. V našem modulu se soubor jmenuje mujmodul.info. Tento soubor je ve formátu souborů.ini. Může obsahovat komentáře, které se uvozují středníkem. 4. Informace o modulu 4.1 Soubor *.info ; $Id$ name = "Muj modul" description = "Priklad naseho modulu" core = 6.x dependencies[] = views dependencies[] = panels package = Views (1) Kód (1) představuje příklad modulu. První řádek začíná komentářem a CVS ID tagem. Jméno modulu name je povinné, velké písmeno se používá pouze pro první slovo. Popis description je také povinná položka krátce popisuje modul. Omezení tohoto pole je 255 znaků. Další povinným parametrem je core, který udává pro kterou verzi Drupalu je modul určen. Neudává se konkrétní vývojová větev. Pro verzi Drupal 6 bude položka vyplněné 6.x. Položka dependicies závislosti je volitelná a obsahuje pole, ve kterém jsou jména modulů, která náš modul vyžaduje. Pokud tyto moduly nejsou nainstalované, modul nepůjde aktivovat.
Pokud jsou nainstalované, ale neaktivní, administrátor bude upozorněn na nutnost aktivace. Jména vyžadovaných modulů zapisujeme malými písmeny a na každý řádek jedno jméno. Další nepovinná položka je package, která se využívá, pokud náš modul patří do nějaké balíčku modulů. A nebo bude používán konkrétně s dalšími moduly. Pokud položku nevyplníme, bude modul patřit mezi Other moduly. Vyplňovat toto pole je vhodné, pokud náš modul rozšiřuje nějaké již hotové balíčky modulů. Případně máme vytvořené čtyři a více modulů, které jsou na sobě závislé. Čtyři moduly je pouze doporučený počet. Jméno balíčku se uvádí s velkým písmenem na začátku. Pokud náš modul vyžaduje minimální požadavky na verzi PHP, můžeme je specifikovat v položce php. Pokud nic nepožadujeme, předpokládá se, že bude pro modul využívána stejná verze jazyka PHP jako pro jádro. Dále můžeme určit verzi našeho modulu v poli version. Pokud modul nehostujeme na infrastruktuře drupal.org, můžeme si verzi libovolně určit. V případě hostování modulu se verze vyplňuje automaticky. Pole project se obvykle nevyplňuje. Balíčkovací skript drupal.org toto pole vyplňuje sám. Tento řetězec určuje balíček, ze kterého modul pochází. A slouží pro monitorování a update modulů. 4.2 Hook funkce help Další informace o modulu můžeme poskytnout implementací hook funkce help. Hook funkce patří do souboru *.module. Účelem této funkce je poskytovat nápovědu dostupnou z administrace systému. A je jen na naši volbě, jaké informace budeme prostřednictvím této funkce poskytovat. Implementace funkce není povinná, ale je velice vhodné ji implementovat. Help funkce našeho modulu se bude jmenovat mujmodul_help(). Funkce má dva parametry, $path a $arg. Parametr $path poskytuje funkce cestu, ze které uživatel požaduje nápovědu. /** * Zobrazi napovedu a informace o modulu * @param path cesta, ze které pozadujeme zobrazeni napovedy * @param arg pole, které obsahuje soucasnou cestu * @return text napovedy pro konkretni cestu */ function mujmodul_help($path, $arg) { $output = ''; //promenna k navraceni switch ($path) { case "admin/help#mujmodul": $output = '<p>'. t("my modul help").'</p>'; break; return $output; // function mujmodul_help (2) Kód (2) představuje ukázkovou implementaci funkce help. Způsob zpracování parametru pomocí podmínkového výrazu switch patří mezi často používané patterny v systému Drupal. Cesta admin/help#modulename patří hlavní straně s nápovědou /admin/help. 5. Přístupová práva modulu Implementací funkce hook_perm() pouze definujeme názvy práv, která jsou k dispozici pro daný modul. Nedefinujeme význam práv a ani je negarantujeme. Jméno funkce bude mujmodul_perm().
Tuto funkci vložíme do souboru mujmodul.module a nesmíme zapomenout na vynechání zavíracího PHP tagu?>. Otevírací tag se v souboru objeví jen jednou na začátku. /** * Pristupova prava pro modul * @return array Pole s nazvy prav pro modul */ function mujmodul_perm() { return array('pristup mujmodul obsah'); (3) Kód (3) je funkce perm pro náš modul. Názvy práv si můžeme zvolit libovolně, ale musí být unikátní pro každý modul. Proto je doporučené používat v názvu práva název modulu, aby nedošlo ke kolizi. Konvence pro pojmenování práv v uživatelských modulech by se měl řídit podle vzoru: slovesny_nazev_akce jmeno_modulu. 6. Obsah bloku 6.1 Popis a umístění bloku Moduly mohou vytvářet různé typy obsahu a právě jedním typem je blok. Blok obsahu je obvykle umístěn ve sloupcích na krajích stránky. Může obsahovat menu systému, odkazy na další stránky, kalendář, přihlašovací pole apod. V administraci lze při aktivaci modulu vybrat umístění bloku na stránce. 6.2 Deklarace bloku /** * Implementace funkce hook_block * @param string $op operace "list", "view", "save" a "configure" * @param integer $delta kod pro identifikaci bloku * @param array $edit **/ function mujmodul_block($op = 'list', $delta = 0, $edit = array()) { if ($op == "list") { // Generovani vypisu bloku pro administraci Drupal $block = array(); $block[0]["info"] = t('my modul'); return $block; (4) Blok obsahu se deklaruje hook funkcí hook_block(). Funkce ukázkového modulu se jmenuje mujmodul_block(). Funkci se předávají tři parametry. Parametr $op může přijmout čtyři různé operace. Operace list, která se volá při zobrazování modulu v administraci, operace view se volá při generování stránky a zobrazování obsahu, který bude generován v bloku. Operace save ukládá konfiguraci bloku a pracuje s parametrem $edit, kterým se předávají uživatelský data z formuláře. Poslední operace configure nastavuje formulář pro blok. Modul může mít deklarovaných více bloků, proto je určen poslední parametr $delta,
pomocí kterého se bloky volí. Zdrojový kód (4) implementuje ve funkci block pouze zobrazování v administraci. Proměnná $block je dvourozměrné pole, do kterého ukládáme bloky. Proměnná $delta tvoří index, kterým se přistupuje do prvního rozmeru tohoto pole, pokud je vytvořeno více bloků. První blok se nachází na indexu 0, další blok by se deklaroval $block[1]["info"] = t('my next modul'). Druhý rozměr pole $block je asociativní pole, kde je vyžadované vyplnit prvek s klíčem info s názvem bloku. Další klíče jsou např. cache, weight a status. 6.3 Generování obsahu bloku /** * Implementace funkce hook_block * @param string $op operace "list", "view", "save" a "configure" * @param integer $delta kod pro identifikaci bloku * @param array $edit * @returns block HTML */ function mujmodul_block($op='list', $delta=0, $edit = array()) { { switch ($op) { case "list": // Generovani vypisu bloku pro administraci Drupal $block = array(); $block[0]["info"] = t('my modul'); return $block; break; case "view": $block_content = ''; // Generovani obsahu bloku if ($block_content == '') { // zadny obsah k zobrazeni $block['subject'] = 'Můj modul'; $block['content'] = 'Žádný obsah'; return $block; // sestaveni bloku $block['subject'] = 'Můj modul'; $block['content'] = $block_content; return $block; break; case "save": // Kod pro ukladani dat z formulare bloku break; case "configure": // Kod pro konfiguraci bloku break;
(5) Doporučená implementace (5) pro generování obsahu bloku. Ve větvi view sestavujeme obsah bloku. Např. získáním dat a zobrazením určitých dat z databáze. Je vhodné kontrolovat podmínkovým příkazem přítomnost dat. V případě neúspěšného získání dat, zobrazíme chybovou hlášku. 7. Obsah stránky 7.1 Popis a umístění stránky Prostor pro obsah v bloku je omezený. Pokud potřebujeme pro výstupní data modulu více prostoru, musíme vytvořit stránku. Stránka je zobrazována obvykle uprostřed mezi postranními sloupci bloků. 7.2 Deklarace a generování obsahu stránky Pro stránku není určená zvláštní hook funkce. Stačí jen v souboru *.module vytvořit další funkci s libovolným jménem, odlišným od předdefinovaných funkcí. Jen je nutné zachovat předponu s názvem modulu. Vzor pro funkci je: {nazev_modulu_{nazev_funkce. Obsah stránky generujeme obdobným způsobem jako obsah bloku. Pro správnou funkčnost stránky je nutné sdělit redakčnímu systému Drupal existenci nové funkce, které generuje nový obsah. Zvolíme např. jméno funkce mujmodul_stranka(). 7.3 Zařazení nové funkce do systému Vytvořená funkce generuje obsah, ale redakční systém neví, na jaké URL adrese má novu stránku zobrazit. URL adresy se definují jako položky menu. Pro definici nové URL adresy menu slouží funkce hook_menu(). Opět se použije zavedený systém pojmenování funkce a do souboru mujmodul.module napíšeme funkci mujmodul_menu(). Funkce vrací pole s různými hodnotami, např. definovanou URL adresou, titulkem stránky, popisem, přístupovými právy a funkcí, která generuje obsah stránky. Položka pole klíčové hodnoty title je povinná a tvoří titulek položky menu. Jednou z hodnot pole je možnost volby zobrazování odkazu na URL. Odkaz může být zobrazován běžným způsobem v menu, nebo se může URL adresa jen registrovat do systému a umístění odkazu lze zvolit libovolně. function mujmodul_menu() { $items = array(); //Pridani nove polozky menu $items['mujmodul'] = array( 'title' => 'Můj modul', 'page callback' => 'mujmodul_stranka', 'access arguments' => array('access mujmodul content'), 'type' => MENU_CALLBACK ); return $items; (6)
Klíčová hodnota mujmodul v poli items tvoří URL cestu ke stránce. Stránku lze nalézt na URL adrese http://priklad.cz/mujmodul. Prvku page callback se přiřadí funkce na generování obsahu, která se zavolá při přístupu na zadanou URL adresu. Prvkem type se určuje volba zobrazování odkazu. Při hodnotě MENU_CALLBACK se URL adresa pouze registruje v systému a nezobrazuje se odkaz na ni v menu. Pro zobrazování v menu je nutné nastavit hodnotu MENU_NORMAL_ITEM. Při změně menu je nutné vyčistit vyrovnávací pamět systému, aby systém novou URL adresu rozpoznal. Drupal načítá do vyrovnávací paměti i seznam všech URL adres, které rozpoznává. 8. Vytvoření konfigurace modulu Pro zajištění flexibility modulu je nutné vytvořit konfigurační menu v administraci systému. Konfigurační stránku tvoří obvykle formulář, který je nutné začlenit do menu administrace. Úprava menu se provádí podle postupu v 7. odstavci. Administrační formulář se vytváří pomocí funkce začleněné do souboru mujmodul.module. Jméno funkce by se mělo skládat z názvu modulu, který tvoří přeponu. A libovolného názvu. Formulář se definuje polem, které se předá funkci system_settings_form(), která zajistí zobrazení formuláře, vytvoření tlačítek pro odeslání formuláře a uložení konfigurace. function mujmodul_admin() { $form = array(); $form['mujmodul_maxdisp'] = array( '#type' => 'textfield', '#title' => t('the maximal number of links.'), '#default_value' => variable_get('mujmodul_maxdisp', 3), '#size' => 2, '#maxlength' => 2, '#description' => t("the maximum number of links to display in the block."), '#required' => TRUE, ); return system_settings_form($form); (7) Proměnná $form je asociativní pole, kde si určíme klíčovou hodnotu pro náš formulář. Dopuručené pravidlo pro tvorbu je použít název modulu jako předponu. Klíčové hodnoty by měly mít unikátní název. Aplikační rozhraní pro formuláře je velmi rozsáhlé a nabízí všechny obvyklé druhy formulářových polí s možnostmi nastavení. Prvním nastavením při tvorbě formuláře je volba druhu formulářového pole. V ukázkovém případě je zvolen druh textfield. Tato hodnota se přiřadí položce pole #type. Funkce variable_get() slouží k získání poslední uložené hodnoty formuláře, pokud žádná taková není, přiřadí hodnotu 3. 8.1 Kontrola formuláře Pro správnou funkčnost konfigurace modulu je nutné před odesláním formuláře provést kontrolu. Aplikační rozhraní redakčního systému nabízí prostředky pro kontrolu formůlářů. Pro automatickou funkci kontroly je nutné vytvořit funkci stejného jména jako pro vytváření formuláře
a přidat příponu _validate. Drupal automaticky použije funkci při odesílání formuláře. function mujmodul_admin_validate($form, &$form_state) { $maxdisp = $form_state['values']['mujmodul_maxdisp']; if (!is_numeric($maxdisp)) { form_set_error('mujmodul_maxdisp', t('you must enter an integer for the maximum number of links.')); else if ($maxdisp <= 0) { form_set_error('mujmodul_maxdisp', t('maximum number of links must be positive.')); (8) V ukázce (8) je příklad pro kontrolu jednoduchého formuláře. Kontroluje se, zda vložená hodnota je číslo a zda je kladné. 9. Trigger Trigger v systému Drupal je nějaká událost, která může spustit akci. Typickou událostí je přihlášení uživatele, nebo úprava článku. A právě na událostí chceme spustit akci, např. odeslání e- mailu administrátorovi při přidání komentáře. 9.1 Vytvoření trigger funkce Pro vytvoření nové trigger funkce je nutné popsat akci hook funkcí hook_hook_info(), implementovat funkci hook_trigger_name() a vložit funkci module_invoke_all() na místa, kde chceme událost vyvolat. 9.2 Popis trigger funkce 1. /** 2. * Implementace hook_hook_info(). 3. */ 4. function mujmodul_hook_info() { 5. return array( 6. 'mujmodul' => array( 7. 'mujmodul' => array( 8. 'block_viewed' => array( 9. 'runs when' => t('block has been viewed.'), 10. ), 11. 'page_viewed' => array( 12. 'runs when' => t('the page has been viewed.'), 13. ), 14. ), 15. ), 16. ); 17.?> (9) Funkce (9) popisuje trigger a poskytuje informace administraci systému, které může vidět administrátor. Funkce musí vracet pole. Na 6. řádku je název záložky pod kterou najdeme v administarci trigger. Na 7. řádku musí být jméno modulu. 8. a 11. řádek jsou jména operací, 9. a 12.
řádek je slovní popis, kdy bude událost vyvolána. 9.3 Vykonávání příslušné akce 1. /** 2. * Implementace hook_trigger_name(). 3. */ 4. function mujmodul_mujmodul($op, $user) { 5. // We support a subset of operations. 6. if (!in_array($op, array('block_viewed', 'page_viewed'))) { 7. return; 8. 9. $aids = _trigger_get_hook_aids('mujmodul', $op); 10. $context = array( 11. 'hook' => 'mujmodul', 12. 'op' => $op, 13. 'user' => $user, 14. ); 15. actions_do(array_keys($aids), $user, $context); 16.?> (10) V podmínce na 6. řádku kódu (10) se testuje, zda se budou vyvolávat jen definované akce. Na 9. řádku se vybere akce, kterou chceme spustit pomocí funkce _trigger_get_hook_aids(). 9.4 Volání trigger funkce... $block['content'] = $block_content; global $user; //Zavolani trigger module_invoke_all('mujmodul', 'block_viewed', $user);?> return $block; (11) Zavolání trigger funkce se provede zavoláním funkce module_invoke_all(), které se předá jméno trigger funkce, jméno akce a další informace. V tomto případě předáváme globální proměnnou $user, kde jsou informace o uživateli, který viděl blok. 9.5 Přiřazení akce /** * Implementace hook_action_info_alter */ function mujmodul_action_info_alter(&$info) { if (isset($info['system_send_email_action']['hooks']
['mujmodul'])) { array_merge($info['system_send_email_action'] ['hooks']['mujmodul'], array('block_viewed', 'page_viewed')); else { $info['system_send_email_action']['hooks'] ['mujmodul'] = array('block_viewed', 'page_viewed');?> Funkcí mujmodul_action_info_alter() přiřadíme trigger funkci akci poslání e-mailu. Podmínka kontroluje, aby se neodstranila trigger funkce, která už byla přidána. Poté se funkce přidá na seznam. Pokud seznam neexistuje, vytvoří se nový. 10. Závěr V rámci této práce se mi podařilo napsat návod pro vytvoření základního modulu do redakčního systému Drupal verze 6.x. Konkrétně se jedná o popis a postup napsání základních souborů modulu pro správnou funkčnost. Dále naprogramování základních funkcí pro vytváření obsahu zobrazovaného modulem a popis funkcí z aplikačního rozhraní. Na projekt bude navazovat bakalářská práce, ve které bude návod rozšířen, aby splňoval celé zadání. A bude naprogramován konkrétní ukázkový modul. 11. Použité prameny [1] PHP: Hypertext Preprocessor [online]. c2001-2009, Last updated: Mon Jan 4 10:14:04 2010 UTC [cit. 2010-01-04]. Dostupný z WWW: <http://www.php.net/>. [2] Drupal handbooks drupal.org [online]. c2000-2009 [cit. 2010-01-04]. Dostupný z WWW: <http://drupal.org/handbooks>. [3] SUCHÝ, Jakub, PROCHÁZKA, Pavel. Drupal.cz Český portál o open source CMS Drupal [online]. c2009 [cit. 2010-01-04]. Dostupný z WWW: <http://www.drupal.cz>. [4] GILMORE, W. Jason. Velká kniha PHP a MySQL 5 : Kompendium znalostí pro začátečníky i profesionály. Ing. Pavel Kristián; RNDr. Jan Pokorný. 2006. rozš. vyd. Brno : Zoner Press, 2006. 864 s. ISBN 80-86815-53-6. (12)