Tworzenie modułów dla CMS Drupal 6, cz. 1

W serwisie drupal.org jest dostępnych kilka tysięcy darmowych modułów o różnej funkcjonalności. Zdarza się jednak, że nie znajdziemy tam modułu, który jest potrzebny do stworzenia serwisu. Co wtedy zrobić? Napisać własny moduł! Własne moduły dla wygody należy trzymać w odrębnym katalogu. Wygodnie jest zrobić podział w katalogu sites/all/modules i utworzyć tam dwa podkatalogi:

• contrib: tu lądują wszystkie moduły z drupal.org,
• custom: tutaj tworzymy własne moduły.

Wymagane pliki

Na początek utworzymy moduł, który będzie definiował własny blok drupalowy. Moduł nazwiemy "my_module". Pierwszym krokiem jest utworzenie katalogu o nazwie "my_module" w sites/all/modules/custom. W tym katalogu tworzymy dwa puste pliki o nazwach:

• my_module.info
• my_module.module

Plik .info

Plik .info zawiera podstawowe informacje o module. Wpisujemy tam następującą zawartość: name = My Module description = My Module description core = 6.x Pierwsza i druga linia pliku to informacje o module, które są wyświetlane na stronie z lista modułów (admin/build/modules). W trzeciej linii wpisujemy informację dla jakiej wersji Drupala jest przeznaczony moduł. Plik .info ma więcej opcji, jednak na potrzeby tego wpisu te trzy opcje są wystarczające. Więcej informacji o pliku .info można poczytać na stronie http://drupal.org/node/206756

Plik .module

Kolej na drugi plik - my_module.module. Jest to plik przechowujący główny kod modułu napisany w PHP. Plik pownien zaczynać się od tagów rozpoczynających kod PHP czyli "<?php". Na końcu pliku nie zamykamy tagu PHP, ponieważ może to powodować błedy jeśli po zamknięciu tagu zostawimy białe znaki. Pisząc kod modułu w Drupalu najczęściej używa się tzw. hook'ów, czyli funkcji pozwalających na "zaczepienie się" do konkretnej akcji wykonywanej w systemie. Hooki wykorzystuje się we własnych modułach tworząć funkcję o nazwie [module_name]_[hook_name], np dla hook_help utworzymy funkcję o nazwie my_module_help().

hook_help

Zaczniemy od hook_help. Dla każdego własnego modułu należy zacząć od napisania tej funkcji, taki jest standard w Drupalu. Funkcja ta zawiera opis modułu, który można przeczytać przez panel administracyjny w Drupalu (strona admin/help). Wpisujemy do pliku zawartość: <?php /** * Implementation of hook_help(). */ function my_module_help($path, $arg) { switch ($path) { case 'admin/help#my_module': return t('My Module description'); } } Funkcja t() służy to tłumaczenia interfejsu użytkownika. Wszystkie wyświetlane teksty zapisane w module powinny być napisane po angielsku i wstawione do funkcji t() aby można było tekst przetłumaczyć przez interfejs Drupala. Po zapisaniu pliku przechodzimy do strony admin/build/modules. Na liście modułów powinien pojawić się nasz nowy moduł. Włączmy go. Teraz na stronie admin/help pojawi się nowy element na liście pomocy - My Module.

hook_block

Czas na utworzenie bloku wyświetlającego przykładowy tekst. Do definiowania bloków służy hook_block. hook_block($op = 'list', $delta = 0, $edit = array()) Hook ten posiada 3 parametry:

• $op - jaki rodzaj operacji jest wykonywany na bloku. Możliwe opcje to:
  • list - wyświetlanie listy bloków definiowanych przez moduł
  • configure - wyświetlanie formularza konfiguracji bloku
  • save - zapisywanie formularza konfiguracji bloku
  • view - wyświetlanie zawartości bloku
• $delta - jeśli moduł definiuje więcej niż jeden blok to ta zmienna jest używana do wskazania, który blok zwrócić (nie dotyczy gdy $op = list)
• $edit - dla $op = save zmienna ta przechowuje dane z formularza konfiguracji bloku

Aby wykorzystać hook_block w naszym module należy utworzyć funkcję o nazwie my_module_block(). /** * Implementation of hook_block(). */ function my_module_block($op='list', $delta=0, $edit=array()) { switch ($op) { case 'list': $blocks = array(); $blocks[0]['info'] = t('My block description'); return $blocks; case 'view': $block = array(); switch ($delta) { case 0: $block['content'] = t('My block content'); $block['subject'] = t('Block title'); break; } return $block; break; case 'configure': break; case 'save': break; } } W kodzie wykorzystaliśmy tylko dwie opcje ($op). Dla $op = list zwracamy listę bloków, które generuje moduł. Listę zapisujemy w tablicy $blocks, której kluczem jest parametr $delta. Znaczy to, że jeśli chcemy później się odwołać do konkretnego bloku przy wyświetlaniu ($op = view) to należy dla każdej z opcji zmiennej $delta zwrócić zawartość bloku. Dla dwóch bloków kod wygląda następująco: /** * Implementation of hook_block(). */ function my_module_block($op='list', $delta=0, $edit=array()) { switch ($op) { case 'list': $blocks = array(); $blocks[0]['info'] = t('My block 1 description'); $blocks[1]['info'] = t('My block 2 description'); return $blocks; case 'view': $block = array(); switch ($delta) { case 0: $block['content'] = t('My block 1 content'); $block['subject'] = t('Block 1 title'); break; case 1: $block['content'] = t('My block 2 content'); $block['subject'] = t('Block 2 title'); break; } return $block; break; case 'configure': break; case 'save': break; } } Analogicznie można tworzyć w module większą ilość bloków, zależnie od wymagań serwisu. Po zapisaniu cały kod w pliku .module wygląda następująco: <?php /** * Implementation of hook_help(). */ function my_module_help($path, $arg) { switch ($path) { case 'admin/help#my_module': return t('My Module description'); } } /** * Implementation of hook_block(). */ function my_module_block($op='list', $delta=0, $edit=array()) { switch ($op) { case 'list': $blocks = array(); $blocks[0]['info'] = t('My block 1 description'); $blocks[1]['info'] = t('My block 2 description'); return $blocks; case 'view': $block = array(); switch ($delta) { case 0: $block['content'] = t('My block 1 content'); $block['subject'] = t('Block 1 title'); break; case 1: $block['content'] = t('My block 2 content'); $block['subject'] = t('Block 2 title'); break; } return $block; break; case 'configure': break; case 'save': break; } } W tym momencie po przejściu do strony admin/build/block pojawią się na liście dwa nowe bloki, które zdefiniowaliśmy. Możemy je umieścić w dowolnym regionie. W przykładzie zawartość bloku to prosty tekst, ale można tam wstawić dowolną treść, np informacje pobierane z bazy danych. Wystarczy tylko dopisać trochę kodu PHP według własnych potrzeb.

Standardy

Napisany moduł powinien być sprawdzony pod kątem zgodniości ze standardem drupala za pomocą modułu Coder. Informacje o standardach kodowania dostępne są na stronie http://drupal.org/coding-standards Należy także tworzyć komentarze w kodzie za pomocą stanradu Doxygen, więcej na stronie http://drupal.org/node/1354

Przydatne strony:

• http://api.drupal.org/api/drupal/includes--module.inc/group/hooks/6 - lista wszystkich hook'ów dostępnych w Drupal 6

Zgłoś  się do nas

Jeśli nie czujesz się na siłach, aby stworzyć swój własny moduł do Drupala, możesz poprosić o pomoc naszą agencję drupalową. Zgłoś się do nas. Chętnie napiszemy moduł dla Ciebie.