Vývoj modulů pro CMS systém Drupal 6.x (3. díl)

V třetím pokračování seriálu o vývoji modulů se nejprve seznámíme s databází, která se vytvoří během instalace Drupalu a následně začneme s vývojem vlastního modulu: hlasování pro článek.

Letmý náhled do databáze

Drupal ke svým účelům pracuje s několika databázovými tabulkami. Tabulky, které existují v každé instalaci Drupalu se vztahují k core-required modulům. Další tabulky se vytvoří aktivací dalších modulů, a to jak základních, které jsou součástí instalace Drupalu (ale jsou po nainstalování neaktivní), tak modulů rozšiřujících (třeba jednoho z našich).

Tip: Referenci k tabulkám core modulů Drupalu naleznete na adrese http://drupal.org/node/22754. Při studiu je třeba opět dávat pozor, zda se díváme do reference ke správné verzi Drupalu.

Mezi nejzajímavější tabulky patří:

• node – základní informace o každém nodu v systému
• node_revision – informace o revizích každého nodu
• node_counter – statistiky k jednotlivým nodům
• comments – komentáře k jednotlivým nodům
• files – informace k uploadovaným souborům
• user_roles – vazba mezi uživatelem a typem uživatelského účtu
• user – informace o uživatelích
• role – informace o rolích (typech uživatelského účtu)
• cache – některé stránky jsou cachovány pro zvýšení výkonu sítě
• sessions – sessions
• blocks – nastavení a obsah bloků

S těmito (a dalšími neuvedenými) tabulkami mohou pracovat vaše moduly: mohou z nich získávat data, editovat obsah a měnit jejich strukturu (například přidáním nového sloupce), což však nebývá obvyklé.

Váš modul může přirozeně vytvářet tabulky nové. Ty jsou Drupalem automaticky vytvořeny během instalace (první aktivace) příslušného modulu administrátorem. Popis tabulek se musí nacházet v hooku hook_schema, která musí být definována v souboru nazevmodulu.install a zapisuje se pomocí speciálního API. Reference k tomuto API se nachází zde a my se s ní seznámíme v souvislosti s našim prvním modulem.

Mohlo by být zajímavé nahlédnout, jak jsou vytvořeny tabulky core modulů během instalace Drupalu. Kód, který hledáme, se nachází v souboru system.install ve funkci system_install:

// Create tables.
$modules = array('system', 'filter', 'block', 'user', 'node', 'comment', 'taxonomy');
foreach ($modules as $module) {
    drupal_install_schema($module);
}

Funkce drupal_install_schema, zajišťuje instalaci každého z modulů a nachází se v souboru includes/common.inc.

Náš první modul – hlasování pro článek

Na místo pokračování v popisu vnitřností Drupalu se pustíme rovnou do psaní jednoduchého modulu, přičemž další nezbytné znalosti o systému získáme „zapochodu“. Modul, který hodláme vytvořit, patří v programování pro CMS mezi kategorii „hello world“ programů. I když (narozdíl od „hello world“ programu) je – dokonce bez dalšího upravování – skutečně použitelný. Co tedy naprogramujeme? Naprogramujeme modul pro hodnocení článků čtenáři. Od ostatních podobných jej trochu modifikujeme v tom smyslu, že návštěvník může udělit/neudělit danému článku pouze jeden hlas (bod).

Modul nazveme „Hlasování“ a jako jednoslovní název, který bude prefixem názvu všech funkcí, volíme „hlasovani“. Náš modul se bude skládat z následujících souborů:

• hlasovani.info – soubor bude obsahovat základní informace, které se zobrazují v administrativní části systému a další informace
• hlasovani.install – soubor je aktivní během instalace a odinstalace modulu
• hlasovani.modul – samotný PHP kód modulu
• hlasovani.css – definice stylů

Jako první krok vytvoříme ve složce sites/all/modules nový adresář hlasovani, ve které se budou nacházet všechny (výše zmíněné) soubory našeho modulu. Dále vytvoříme všechny čtyři soubory a necháme je prozatím prázdné. Postupně je budeme vyplňovat kódem.

hlasovani.info – informace o modulu

Soubory .info jsou formátu .ini, což je jednoduchý standard pro PHP konfigurační soubory. Více informací o .ini souborech naleznete například v referenci k PHP.

V našem případě vyplníme ze všech možných položek o nichž hovoří reference Drupalu pouze několik. Každá položka má název (identifikátor) a hodnotu a píše se na samostatný řádek. Název položky a její hodnota jsou odděleny symbolem „=“. Záleží na dobré vůli programátora, které a kolik položek vyplní (a zda vůbec nějaké). My vyplníme položky name, description, package a code.

Položka name nese informaci o názvu modulu:

name = Hlasování

Do položky description, v níž je vyplněn popis modulu, napíšeme:

description = Modul umožňuje čtenářům hlasovat váhou jednoho hlasu pro publikované nody.

V další položce vyplníme informaci o tom, pro jakou verzi Drupalu je náš modul určen:

core = 6.x

V poslední položce vyplníme informaci o tom, do jakého balíčku (položka package) náš modul náleží. Můžeme si vymyslet vlastní název balíčku (například „Pokusné moduly“). Moduly se stejným názvem balíčku jsou v administrační části od sebe graficky odděleny:

package = Pokusné moduly

Na začátek souboru ještě přidáme řádek s prázdným CVS identifikačním tagem (ten budeme přidávat na začátek všech souborů):

; $Id$

Jsme hotovi. Celý soubor hlasovani.info by měl vypadat takto:

; $Id$
name = Hlasování
description = Modul umožňuje čtenářům hlasovat váhou jednoho hlasu pro publikované nody.
core = 6.x
package = Pokusné moduly

Pokud se nyní podíváte do administrátorské sekce Drupalu, do části, kde se aktivují moduly, měli byste vidět váš modul v samostatné záložce „Pokusné moduly“ s popisem, který odpovídá tomu, co jsme vyplnili v souboru hlasovani.info. V administraci se zdá, že by bylo možné modul aktivovat. Můžete to zkusit. Drupal sice vypíše hlášku „The configuration options have been saved.“, ale ve skutečnosti se nic nestane. Přirozeně, zatím jsem žádný modul nenapsali.

Návrh databáze a soubor hlasovani.install

Než začneme psát kód, měl bych se zmínit o tom, že existují tzv. Coding standards, které jsou součástí oficiální reference k Drupalu. Budeme se snažit těchto doporučení držet, neboť jsou komunitou Drupalu v podstatě vyžadovány (je považováno za neslušné se od nich příliš odchylovat).

Komunita Drupalu je poměrně háklivá na styl zápisu komentářů. Krátce se tedy o tom zmíníme:

Krátké komentáře k funkcím píšeme:

/**
 * Funkce konverguje pole na objekt.
 */
function array2object($array) {

Hook dokumentujeme jednoduše jako:

/**
 * Implementace hook_help().
 */
function blog_help($section) {
  // ...
}

Drupal podporuje styl dokumentace Doxygenu, více informací o tom naleznete opět v referenci. U složitějších funkcí tedy můžeme použít tagy Doxygenu:

/**
 * Verifikuje syntax emailove adresy.
 *
 * Prazdna e-mailova adresa je povolena, viz RFC 2822.
 *
 * @param $mail
 *   e-mailova adresa - string
 * @return
 *   TRUE, pokud je adresa ve spravnem formatu
 */
function valid_email_address($mail) {

Přistupíme k implemetaci souboru hlasovani.install. Obecně je soubor .install aktivní během instalace a odinstalace modulu a je v něm definováno schéma databáze. Reference Drupalu říká, že soubor .install má implementovat tři hooky:

• hook_schema – zde je definováno databázové schéma
• hook_install – hook instaluje aktuální databázové schéma voláním funkce drupal_install_schema, může vykonat i další operace, které souvisejí s instalací modulu.
• hook_uninstall – hook je volán při odinstalaci (nikoli deaktivaci) modulu. Může například odstranit databázové tabulky voláním funkce drupal_unistall_schema (je otázkou, zda je rozumné při odinstalaci modulu vždy po sobě uklidit tímto způsobem), smazat nepotřebné soubory, odstranit globální proměnné apod.

Je nutné striktně rozlišovat mezi instalací/aktivací a deaktivací/odinstalací. Instalace je první aktivace modulu (po tom co buď vůbec nebyl ještě aktivován, nebo byl předtím odinstalován). Aktivace je opětovné přivedení modulu k životu (po tom, co byl deaktivován). Během instalace je volána hook hook_install, jehož prací je většinou modifikace databáze. Hook není volán během aktivace modulu (a nedochází tak k pokusu o vytvoření již existujících tabulek, přepisování souborů apod.).

Pokud je v administrativní části modul deaktivován, není ještě odinstalován (i když je deaktivace nutnou podmínkou k odinstalaci, viz administrace). Teprve při odinstalaci je volán hook hook_uninstall. Ten není volán při deaktivaci modulu a nemůže tak dojít pouhou deaktivací modulu k vymazání obsahu databáze.

Do souboru hlasovani.install napíšeme:

function hlasovani_schema() {
  $schema['hlasovani'] = array(
     // specifikace databázové tabulky
  );
  return $schema;
}

function hlasovani_install() {
  // edituj databázi
  drupal_install_schema('hlasovani');
}

function hlasovani_uninstall() {
  // ukliď po sobě v databázi
  drupal_uninstall_schema('hlasovani');
}

Funkce hlasovani_install a hlasovani_uninstall jsou již hotové. K jejich implementaci nám stačil vždy jeden příklad. Nevyplněna zůstala pouze funkce hlasovani_schema, kde budeme definovat novou tabulku hlasovani, která se během instalace vytvoří a která bude uchovávat informaci o hlasování jednotlivých uživatelů.

Tabulku bude obsahovat vazbu na tabulku node a to sloupcem nid (nid jednoznačně identifikují nod, viz tabulka node ve vaší instalaci Drupalu) a dále vazbu na uživatele sloupcem uid (viz tabulka user ve vaší instalaci Drupalu). Skutečnost, že uživatel hlasoval pro jistý článek do databáze, zaneseme přidáním nového řádku s příslušnými uid a nid.

CREATE TABLE hlasovani (
	uid int NOT NULL default '0',
	nid int NOT NULL default '0',
	PRIMARY KEY (uid, nid));

SELECT COUNT(*) FROM hlasovani WHERE nid = xx;

$schema['hlasovani'] = array(
	'description' => 'The base table for nodes.',
	'fields' => array(
		'nid' => array(
			'description' => 'The primary identifier 
			                   for a node.',
			'type' => 'int',
			'unsigned' => TRUE,
			'not null' => TRUE,
		),
		'uid' => array(
			'description' => 'aentifier for a node.',
			'type' => 'int',
			'unsigned' => TRUE,
			'not null' => TRUE
		)
	),
	'primary key' => array('nid', 'uid')
);

<?php
/**
 * Implementace hook_schema().
 * @return array se tabulkou "hlasovani" definovanou pomoci Scheme API
 */
function hlasovani_schema() {
	$schema['hlasovani'] = array(
		'description' => 'The base table for nodes.',
		'fields' => array(
			'nid' => array(
				'description' => 'The primary identifier for a node.',
				'type' => 'int',
				'unsigned' => TRUE,
				'not null' => TRUE,
			),
			'uid' => array(
				'description' => 'aentifier for a node.',
				'type' => 'int',
				'unsigned' => TRUE,
				'not null' => TRUE
			)
		),
		'primary key' => array('nid', 'uid')
	);
	return $schema;
}

/**
 * Implementace hook_install().
 */
function hlasovani_install() {
  // edituj databázi
  drupal_install_schema('hlasovani');
}

/**
 * Implementace hook_uninstall().
 */
function hlasovani_uninstall() {
  // ukliď po sobě v databázi
  drupal_uninstall_schema('hlasovani');
}
?>

db_query('INSERT INTO {hlasovani} (nid, uid) 
          VALUES (%d, %d)', $nid, $uid);

return (int) db_result(db_query('SELECT COUNT(*) FROM {hlasovani} 
	          WHERE nid = %d', $nid));

$sql = "SELECT nid FROM {node} ORDER BY nid";
$query = db_query($sql);

while($data = db_fetch_object($query)) {
    $output .= ' '.strval($data->nid);
}