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

V tomto čtvrtém a (zatím) posledním pokračování seriálu o vývoji modul pro publikační systém Drupal dokončíme náš první modul. V této části článku budeme implementovat soubor hlasovani.modul.

Implementace souboru hlasovani.modul

Nyní se pustíme do nejobsáhlejšího souboru, který bude již obsahovat samotnou logiku modulu. Jedná se o soubor hlasovani.modul. Začneme se základními hooky, které by měly být součástí snad každého modulu:

• hook_perm
• hook_menu

Jako první implementujeme hook_perm. Hook určuje, jaké oprávnění musí mít daný uživatel (přesněji role, která je danému uživateli přidělena), aby mohl pracovat s daným modulem. V administraci potom můžete přidělovat/odebírat tyto oprávnění jednotlivým uživatelským rolím. My budeme požadovat oprávnění s názvem hlasovani. Po instalaci a aktivaci modulu se toto oprávnění objeví jako volitelné u všech uživatelských rolí (viz administrace Drupalu po tom, co aktivujete/instalujete náš modul).

/**
  * Implementace hook_perm
  * @return array se opravneni
  ;*/
function hlasovani_perm() {
  return array('hlasovani');
}

Obecněji může být vráceno více oprávnění, které mají k modulu přístup. Ilustračně:

return array('access onthisdate content', 'administer onthisdate');

My si však v tomto modulu vystačíme s jedním.

V implementaci budeme pokračovat hookem hook_menu, v němž jsou obecně definovány callbacky a prvky menu. My budeme definovat pouze jeden callback a žádný prvek menu.

Definice callbacku je opět ve formě pole (přesněji vnořených polí), jak jsme se s ním již seznámili ve Scheme API. S tímto způsobem definování různých prvků systému je třeba si zvyknout, protože je v Drupalu (a v PHP) obvyklý.

Asociativní pole může obsahovat položky, které jsou vypsány v referenci k hooku hook_menu. O nejdůležitějších položkách se zmíníme:

• title – název prvku menu
• description – popis prvku
• page callback – název funkce, která bude obsluhovat danou URL
• access arguments – pole se seznamem oprávnění, kteří mají k danému callbacku/prvku menu přístup
• type – viz dále

Položka type může nabývat několika možných hodnot. Zmíníme se o dvou nejdůležitějších (nejčastějších):

• MENU_NORMAL_ITEM – bude se zobrazovat jako prvek v menu, kliknutí na prvek tohoto menu obslouží funkce uvedená v definici prvku
• MENU_CALLBACK – nebude se zobrazovat v menu, pouze se registruje URL a funkce, která toto URL obslouží

Vraťme se k našemu kódu. Budeme chtít zaregistrovat URL hlasovani/zahlasuj s funkcí, kterou nazveme hlasovani_zahlasuj. Název URL se uvádí jako klíč, se kterým jsou spojeny položky pole:

/**
* Implementace hook_menu.
*
*  @return
*    struktura (array) s definici prvku menu (v nasem
*    pripade nedefinujeme ani jeden prvek menu) a callbacku
*/
function hlasovani_menu(){

  $items['hlasovani/zahlasuj'] = array(
    'page callback' => 'hlasovani_zahlasuj',
    'type' => MENU_CALLBACK,
    'title' => 'Zpracovani hlasu',
    'access arguments' => array('hlasovani'),
  );
  return $items;
}

Nyní implementujeme funkci, kterou voláme v callbacku. Připomenu, který prvek pole spojuje callback s názvem:

'page callback' => 'hlasovani_zahlasuj',

Tato funkce bude obsluhovat volání URL vase_site/hlasovani/zahlasuj. Funkce má argument $nid. Kde se tento argument vezme? Vždyť jsme naznačovali, že funkce je volána automaticky! Jak je tedy tento parametr předán? Parametr je předán automaticky jako další část URL: vase_site/hlasovani/zahlasuj/hodnota_promenne. Tento princip funguje v Drupalu vždy, když se jedná o callback funkce.

Vlastní funkce hlasovani_zahlasuj:

/**
 * Implementace callbacku hlasovani/zahlasuj.
 *
 * @param $nid
 *   id nodu, pro ktery je hlasovano
 */
function hlasovani_zahlasuj($nid){
  //dostan objekt do lokalniho scopu
  global $user;
  
  //autori nemohou hlasovat pro svuj vlastni clanek
  $je_autorem = db_result(db_query('SELECT uid FROM {node} WHERE nid = %d 
    AND uid = %d', $nid, $user->uid));
  
  //muze dany uzivatel skutecne pro tento clanek hlasova?
  if ($user->uid && ($nid > 0) && !$je_autorem) {
    $hlasoval = hlasovani_hlasoval($nid, $user->uid);
    if(!$hlasoval){
      hlasovani_hlasuj($nid, $user->uid);
    }
  }
  
  //presmeruj se na adresu z niz jsme prisli
  drupal_goto("node/".$nid);
}

Funkce je hodně jednoduchá. Na prvním řádku dostaneme do lokálního scopu objekt user (který se vytvoří během zaváděcího procesu Drupalu), který nese informace o uživateli, který zaslal požadavek (který si právě prohlíží stránku). Na tomto objektu nás momentálně zajímá hodnota user->uid, což je id uživatele. Na dalším řádku jednoduchým SQL dotazem zjišťujeme, zda daný uživatel je autorem článku (nodu).

//autori nemohou hlasovat pro svuj vlastni clanek
$je_autorem = db_result(db_query('SELECT uid FROM {node} WHERE nid = %d 
  AND uid = %d', $nid, $user->uid));

Následuje struktura if, která rozhodne, zda daný uživatel může nodu přidat hlas. Podmínkou je, že není autorem a ješťe nehlasoval. O přidání hlasu se stará funkce hlasovani_hlasuj (napíšeme ji vzápětí).

Poslední příkaz drupal_goto se stará o přesměrování zpět na node, ze kterého hlasující uživatel přišel. Tento způsob řešení: tj. přechod na jinou URL a znovu přesměrování již dávno není v Drupalu obvyklý. Používá se AJAX (s knihovnou JQuery), který dovoluje tyto věci řešit mnohem elegantněji: bez přenačítání stránky.

Připomínám, že funkce je volána pouze ve chvíli, kdy váš systém dostane URL vase_site/hlasovani/zahlasuj/cislo_nodu. Jak se volání této URL má k hlasování? Za pár okamžiků napíšeme kód, který bude generovat HTML s odkazem na právě tuto URL, přičemž cislo_nodu bude skutečně nahrazeno číselnou hodnotu, která odpovídá id (nid) daného nodu. Klikem na odkaz dojde k přechodu na tuto URL a tím k vykonání funkce hlasovani_hlasuj a tedy i zahlasování a přesměrování zpět.

Ve funkci voláme funkce hlasovani_hlasuj a hlasovani_hlasoval. Od funkce hlasovani_hlasuj očekáváme, že provede uložení potřebných dat do databáze:

/**
* Zahlasuj pro dany clanek - uloz jeden sloupec do tabulky.
*
* @param $nid
*   nid nodu
* @param $uid
*   uid uzivatele
*/
function hlasovani_hlasuj($nid, $uid){
  db_query('INSERT INTO {hlasovani} (nid, uid) VALUES (%d, %d)', $nid, $uid);
}

Funkce hlasovani_hlasoval bude vracet, zda daný uživatel již pro článek hlasoval:

/**
 * Hlasoval uzivatel s danym uid pro nod s danym nid?
 *
 * @param $nid
 *   id nodu
 * @param $uid
 *   id uzivatele
 * @return
 *   pocet hlasu pro dany clanek od daneho uzivatele 
 *   (pretypovavame na boolean)    
 */
function hlasovani_hlasoval($nid, $uid){
  return (bool) db_result(db_query('SELECT COUNT(*) FROM {hlasovani} 
    WHERE nid = %d AND uid = %d', $nid, $uid));
}

Jak připojíme výstup modulu (tj. HTML kód s počtem hlasů pro článek a s odkazem, kterým lze zahlasovat) na konec každého nodu? Implementujeme hook_nodeapi.

V tomto hooku můžeme modifikovat obsahu nodu, který je právě sestavován, aby byl zobrazen uživateli. Hook je však volán kdykoli se s nějakým nodem děje něco zajímavého, například ve chvíli, kdy je mazán, editován apod. V hooku budeme chtít obsloužit dvě události: příprava nodu pro zobrazení a mazání nodu. V případě přípravy pro zobrazení budeme chtít „přilepit“ hlasovací prvek. V případě mazání nodu budeme i my chtít smazat k němu relevantní data v tabulce hlasovani.

Node je zde reprezentován jako objekt, který je předáván referencí. Druhým argumentem funkce je op, který říka, jaká událost s hookem nastává. Význam dalších dvou argumentů hooku je popsán v komentáři:

/**
 * Implementace hook_nodeapi().
 * Modifikuje obsahu nodu, ktery je predan parametrem. 
 *
 * @param &$node
 *   referenci je predan node, ktereho se udalost tyka
 * @param $op
 *   informace o tom, co se vlastne deje: zda je clanek mazan, 
 *   prohlizen apod. Mozne hodnoty viz http://api.drupal.org/api/function/hook_nodeapi/6
 * @param $teaser
 *   informace, zda se jedna o renderovani teaseru
 * @param $page
 *   informace o tom, zda se jedna o renderovani cele stranky
 */
function hlasovani_nodeapi(&$node, $op, $teaser, $page) { 
  switch($op){
    case 'view':
    //zobraz hlasovani
    if(!$teaser){
      $node->content['hlasovani'] = array(
      '#value' => hlasovani_renderer($node->nid),
      '#weight' => 90);
    }
    break;
  	
    case 'delete':
      db_query('DELETE FROM {hlasovani} WHERE nid = %d', $node->nid);
    break;
  }
} 

Podle hodnoty parametru op tedy buď k obsahu nodu ($node->content) připojíme nový prvek, jehož hodnota je dána návratovou hodnotu funkce hlasovani_renderer, nebo vymažeme z tabulky hlasovani všechny řádky s daným nid.

Pokračujeme funkcí hlasovani_renderer. Ta bude již vracet HTML kód, který budeme chtít na konec nodu přilepit.

Funkce hlasovani_renderer:

/**
 * Vytvor HTML kod, ktery se bude zobrazovat pod nodem
 * jako hlasovaci prvek.
 *
 * @return
 *   HTML kód, který se zobrazí na konci nodu
 */
function hlasovani_renderer($nid) {
  //nahraj CSS soubor
  drupal_add_css(drupal_get_path('module', 'hlasovani') .'/hlasovani.css');
  	
  //ziskej objekt user do lokalniho scope
  global $user;
  	
  //ziskej skore
  $pocethlasu = hlasovani_pocethlasu($nid);
  //je aktualni ctenar autorem clanku?
  $je_autor = db_result(db_query('SELECT uid FROM {node} WHERE nid = %d 
     AND uid = %d', $nid, $user->uid));
  //hlasoval jiz pro dany clanek?								 
  $hlasoval = hlasovani_hlasoval($nid, $user->uid);
  //vrat HTML kod hlasovaciho prvku
  return hlasovani_output($nid, $je_autor, $pocethlasu, $hlasoval);
}

Funkce drupal_add_css přidává referenci na soubor se styly, který je v adresáři s ostatními soubory modulu. Funkce drupal_get_path vrací cestu k danému modulu.

Jako návratová hodnota je předána návratová hodnota funkce hlasovani_output. Ta již na základě vstupních parametrů generuje HTML kód, který se pod nodem zobrazí. Podle toho, zda uživatel je autorem nodu a hlasoval či nehlasoval, se zobrazí buď link na callback (který automaticky volá funkci hlasovani_zahlasuj, která se postará o započtení hlasu), který jsme vytvořili, nebo text: „Již jste hlasoval.“ případně „Nelze hlasovat pro vlastní článek.“

Budeme pokračovat funkcí hlasovani_output:

/**
 * Vytvor HTML kod, samotneho hlasovaciho prvku.
 *
 * @param $nid
 *   nid nodu
 * @param $je_autor
 *   je uzivatel s danym uid autorem clanku?
 * @param $pocethlasu
 *   kolik hlasu dany clanek ziskal?
 * @param $hlasoval
 *   hlasoval jiz dany uzivatel pro clanek?
 */
function hlasovani_output($nid, $je_autor, $pocethlasu, $hlasoval){	
  $output = '<div class="hlasovani">';
  $output .= '<div class="pocethlasu">';
  $output .= $pocethlasu; 
  $output .= '</div>';
  $output .= '<div class="hlas">';	
  	
    if(!$hlasoval && !$je_autor){ 
      //hlasovat muze jen ten, kdo neni autor a kdo
      //jeste nehlasoval
      $output .= l("Hlasuj", "hlasovani/zahlasuj/".$nid);
    }
    elseif ($hlasoval) {
      //jiz hlasoval, vypis pouze hlasku
      $output .= 'Již jste hlasoval.';
    }
    elseif ($je_autor) { 
      //nelze hlasovat pro vlasnit clanek - vypis
      //pouze hlasku
    $output .= 'Nelze hlasovat pro vlastní článek';
  }
  
  $output .= '</div>';
  $output .= '</div>';
  
  // vrat HTML kod
  return $output;
}

Poslední funkcí, kterou musíme implementovat je funkce hlasovani_pocethlasu, která počítá počet hlasů pro daný článek. Obsahuje pouze jeden SQL dotaz, jehož výsledek je vrácen jako návratová hodnota:

/**
 * Spocti hlasy pro dany clanek.
 *
 * @param $nid
 *   nid nodu
 * @return
 *   pocet hlasu pro dany clanek
 */
function hlasovani_pocethlasu($nid){
  return (int) db_result(db_query('SELECT COUNT(*) FROM {hlasovani} 
    WHERE nid = %d', $nid));
}

Implementace souboru hlasovani.css

Zbývá soubor hlasovani.css. CSS kód nechávám na vaší představivosti, zde uvádím pouze návrh, jak by mohl soubor vypadat.

div.hlasovani {
  width: 150px;
  text-align: center;
  margin-bottom: 5px;
}

div.hlasovani .hlas {
  padding: 3px 5px;
  border: 1px solid white;
  margin-top: 2px;
  background-color: white;
}

div.hlasovani .pocethlasu{
  font-size: 175%;
  padding: 10px;
  border: 1px solid black;
  background-color: white;
}

Zbývá připomenout, jak je soubor hlasovani.css připojen k našemu modulu. O to se stará funkce. Viz řádek ve funkci hlasovani_renderer:

drupal_add_css(drupal_get_path('module', 'hlasovani') .'/hlasovani.css');

Nyní zbývá dát vše dohromady a pochopit kód v celku. Ale to je již práce pro vás. Přeji hodně štěstí.

Závěr

V tomto seriálu jsme začali obecným popisem Drupalu a seznámili se s jeho „vnitřním chodem“ a základní terminologií, jejž znalost je nezbytná při studiu reference. Napsali jsme společně relativně jednoduchý, ale použitelný modul, který umožní uživatelům s daným právem hlasovat pro nody. Seznámili jsme se se základními hooky (hook_perm, hook_menu), které je třeba implementovat prakticky v každém modulu, a máme přehled o tom, jaké hooky existují (a jaké události lze tedy ovlivnit). Seznámili jsme se s funkcemi drupal_add_css a drupal_goto, jejichž použití je při vývoji modulů časté. Získali jsme přehled o databázové vrstvě (včetně základních funkcí a jejich použití) a Scheme API.

Dokončili jsme první modul! Po instalaci by měl spolehlivě fungovat. Lze mu vytknout mnoho vlastností. Nejzávažnějším nedostatkem je nutnost načtení celé stránky po hlasování. Tuto nemilou vlastnost lze snadno odstranit pomocí AJAXu a jQuery, a tím se budeme zabývat v další sérii článků o Drupalu.