Druga część zmagań z Drupalem, implementacja bloku z formularzem, wraz z obsługą błędów, zapisem do bazy i wyświetlaniem komunikatów. Formularz korzysta z AHAH i JQuery, jakkolwiek działa także bez wsparcia JavaScriptu. Całość nie jest dopieszczona wizualnie, ale działa bez zarzutu ;]

$(document).ready(function(){
    $("input#edit-email-subscribtion").focus(function(){
        $(this).val("");
    });
});

    Prosta funkcja JQuery umieszczona w pliku “custom_newsletter.js” w folderze modułu. Jeżeli po załadowaniu strony zostanie zaznaczone pole o id=”edit-email-subscribtion” jego wartość zostanie ustawiona na pustą. Pozostałe fragmenty kodu należą do “custom_newsletter.module”

function custom_newsletter_init() {
  drupal_add_js(drupal_get_path('module', 'custom_newsletter') .'/custom_newsletter.js');
}

    Funkcja dodaje do nagłówków stron, w których używany jest moduł, link do powyższego pliku z JavaScriptem.

function custom_newsletter_block($op = 'list', $delta = 0, $edit = array()) {
  switch ($op) {
    case 'list':
      $block[0] = array(
        'info' => t('Subscription block'),
      );
      return $block;

    case 'view': default:
      if ($delta==0) {
        $block['subject'] = t('Newsletter');
        $block['content'] = custom_newsletter_contents();
      }
      return $block;
  }
}

    Funkcja deklarująca wyświetlany blok, część “list” odpowiada za wyświetlanie bloku w liście bloków, “view” determinuje jego wygląd na stronie. Więcej na: hook_block

function custom_newsletter_contents(){
  $msgfield = "<div id=custom_subscribtion_msgfield>".
                custom_newsletter_build_message(variable_get('subscribtion_state','')).
              "</div>";
  $contents = "<div>".$msgfield.drupal_get_form('custom_newsletter_form')."</div>";
  variable_del('subscribtion_state');
  return $contents;
}

    Funkcja wywoływana w celu wypełnienia bloku zawartością. Zawiera diva wyświetlającego komunikaty, oraz wywołanie funkcji generującej formularz.

function custom_newsletter_build_message($message){
  return '<hr />'.$message.'<hr />';
}

    Poglądowa wersja tworzenia komunikatu na podstawie wartości zadeklarowanej zmiennej. Przydałoby się zróżnicowanie komunikatów pod kątem treści i wyglądu, może kiedyś ;]

function custom_newsletter_form(){
  $form['email_subscribtion'] = array(
  '#type' => 'textfield',
  '#default_value' => t('enter email here'),
  '#size' => 20,
  '#maxlength' => 30,
  '#element_validate' => array('subscribtion_form_validate'),

  );

  $form['submit'] = array(
  '#type' => 'submit',
  '#value' => t('Subscribe'),
  '#submit' => array('custom_newsletter_form_submit'),

  '#ahah' => array(
        'path' => 'custom_newsletter/js',
        'wrapper' => 'custom_subscribtion_msgfield',
  		'method' => 'replace',
        'progress' => array('type' => 'throbber',),
  ),
  );
  return($form);
}

    Deklaracja poszczególnych pól formularza, przypisanie im właściwości oraz funkcji wywoływanych w celu walidacji pól oraz po zatwierdzeniu formularza. Sekcja #ahah określa reakcję na zatwierdzenie bez przeładowywania strony, określa kolejno link pod którym są opisane owe reakcje, następnie element zmieniany podczas działania funkcji, metodę zmiany oraz animację. Więcej na: form API

function custom_newsletter_menu() {
  $items = array();
  $items['custom_newsletter/js'] = array(
    'title' => 'Javascript Choice Form',
    'page callback' => 'custom_newsletter_js',
    'access arguments' => array('access custom_newsletter js'),
    'type' => MENU_CALLBACK,
  );
  return $items;
}

    Funkcja tworzy element menu (http://localhost/drupal/?q=custom_newsletter/js), pod którym znajduje się funkcja wywoływana po zatwierdzenia formularza z użyciem AHAH.

function custom_newsletter_js(){
    $form_state = array('storage' => NULL, 'submitted' => FALSE);
    $form_build_id = $_POST['form_build_id'];
    // Get the form from the cache.
    $form = form_get_cache($form_build_id, $form_state);
    $args = $form['#parameters'];
    $form_id = array_shift($args);
    // We will run some of the submit handlers so we need to disable redirecting.
    $form['#redirect'] = FALSE;
    // We need to process the form, prepare for that by setting a few internals
    // variables.
    $form['#post'] = $_POST;
    $form['#programmed'] = FALSE;
    $form_state['post'] = $_POST;
    // Build, validate and if possible, submit the form.
    drupal_process_form($form_id, $form, $form_state);
    // This call recreates the form relying solely on the form_state that the
    // drupal_process_form set up.
    $form = drupal_rebuild_form($form_id, $form_state, $args, $form_build_id);
    // Render the new output.

    $coumunicate = custom_newsletter_build_message(variable_get('subscribtion_state',''));
    variable_del('subscribtion_state');
    return drupal_json(array('status' => TRUE, 'data' => $coumunicate));
}

    Funkcja pełna kodu świadczącego o kulawości AHAH, formularz należy najpierw zrekonstruować z keszu aby go zwalidować i zatwierdzić. Brzydki kod który nie wiadomo jak się zachowa przy kilku formularzach. Zwraca element json modyfikujący element określony w deklaracji formularza w sekcji ahah.

function custom_newsletter_form_submit($form, &$form_state){
  $form_values = $form_state['values'];
  $email=$form_values['email_subscribtion'];
  db_query("INSERT INTO {custom_newsletter} (id, email, hash) VALUES (%d, '%s', '%s')", 0, $email, substr(md5($email.time()),0,19));
}

    Funkcja wymieniona w deklaracji formularza, poza przekazaniem wartości pola formularza, warto zwrócić uwagę na database abstraction layer.

function subscribtion_form_validate($element, &$form_state) {
  if (empty($element['#value'])) {
    variable_set('subscribtion_state', 'ERROR');
    form_set_error('email_subscribtion', '', TRUE);
  }else{
    variable_set('subscribtion_state', 'OK');
  }
}

    Jest to funkcja wymieniona w deklaracji formularza, kod jest poglądowy, przydałoby się sprawdzanie regexem, oraz dublowania wpisów. Formularz nie zostaje zatwierdzony, jeżeli zostanie wywołana funkcja form_set_error. W tym przypadku pole wiadomości jest puste, żeby nie wyświetlać komunikatu błędu u góry strony.

    Pisanie w Drupal API potrafi być dość przyjemne kiedy już wiadomo o co chodzi. Człowiek staje się wygodny, tym bardziej dziwi toporność AHAH. Standardowe komunikaty błędów pojawiające się na górze strony nie są domyślnie obsługiwane przez AHAH i ich ewentualne wyświetlenie następuje dopiero po ręcznym przeładowaniu strony. Ponadto jego używanie jest tak mało intuicyjne, że aż powstał moduł mający temu zaradzić (AHAH helper module).
    Poza tym w kodzie widać moje pierwsze próby przekazywania zmiennych za pomocą funkcji variable_set(). Zmienne te są przechowywane w bazie i częste operacje na nich są zapewne mało efektywne, choć pewnie nie mają alternatywy w przypadku operacji AJAXowych.
    Warto zaopatrzyć się w moduł Cache Disable, wyłącza keszowanie bloków i elementów menu. Spowalnia to działanie całości, ale ułatwia pracę nad modułami, brak reakcji na zmiany w kodzie nie musi być leczony ręcznym usuwaniem keszu w bazie ;]

Coming soon: Strony konfiguracyjne oraz zarządzające modulem. Stay tuned ;]

    Postaram się przedstawić i omówić proces tworzenia modułów do Drupala 6 na przykładzie pisanego przeze mnie modułu do rozsyłania ręcznie redagowanego newslettera na podstawie anonimowej subskrybcji emailowej. Moduł nazwę adekwatnie do jego funkcji “custom newsletter”.

Moduł będzie się składać z następujących elementów:

• bloku odpowiedzialnego za wyświetlanie formlularza zapisów email wraz z obsługą ajaxa
• strony służącej do zarządzania podanymi adresami email
• strony służącej do konfiguracji szablonu wysyłanych wiadomości
• strony służacej do redagowania treści wewnątrz szablonu
• strony po przekierowaniu na którą, dany adres zostanie wypisany z listy subskrybentów

    W dzisiejszym odcinku zajmiemy się utworzeniem modułu, sprawdzeniem kompatybilności z istniejącą konfiguracją oraz utworzeniem tabeli w bazie. Dziką i fascynującą imprezę zaczynamy od utworzenia katalogu [\drupal\sites\all\modules\custom_newsletter], w którym będziemy umieszczać kolejne pliki:

Plik *.info – definiuje podstawowe informacje i jest wymagany aby dany moduł pokazał się w liście dostępnych modułów. Posiada składnię plików *.ini

    custom_newsletter.info

; $Id$
name = custom_neswletter
description = provides custom newsletter for anonymous subscribers
core = 6.x
php = 5.1

    Pierwsza linijka odnosi się do SVN i jest wymagana dla zgodności ze sztuką, następnie nazwa, opis wyświetlany przy liście modułów, wymagana wersja drupala oraz php. Mozliwe jest także dodanie zależności wobec innych modułów (dependencies), oraz nazwanie grupy przy której dany moduł będzie wświetlany w panelu administracyjnym (package).

Plik *.module – zawiera funkcje realizujące funkcjonalność modułu, musi zostać utworzony aby moduł pokazał się na liście dostępnych modułów, w tym przypadku zawiera podstawową funkcję hook_help() definiującą treść pomocy.

    custom_neswletter.module

function custom_newsletter_help($path, $arg) {
  if ($path == 'admin/help#customnewsletter') {
    $txt = 'This is string containing help info about custom newsletter module '
      .'none info text included '
      .'module is being developed ;] ';
    $replace = array();
    return '<p>'. t($txt, $replace) .'</p>';
  }

Plik *.install – plik do ktorego zagląda drupal w poszukiwaniu hook_install() oraz hook_uninstall() podczas włączania i analogicznie wyłączania/deinstalacji modułu. Można za jego pomocą określić, czy są spełnione warunki wymagane przez dany moduł (np. odpowiednie funkcje php) i w razie potrzeby zasygnalizować problem, a także utworzyć/usunąć tabele w bazie. Niniejszy utworzy określoną tabelę w bazie o ile funkcja mail() zwróci “true”, oraz usunie tabelę po odinstalowaniu modułu. Funkcja hook_requirements() w zależności od wartości obsłuugi zmiennej $phase wyświetli komunikat błędu nad listą modułów uniemożliwiając instalację ($phase == ‘install’), lub w Administer->Reports->Status Report ($phase == ‘runtime’)

    custom_neswletter.install

< ?php
/* $Id: custom_newsletter.install,v 1.0 2009/03/15 05:49:50 dries Exp $ */

function custom_newsletter_requirements($phase) {
  $requirements = array();
  //Check mail() function
  $requirements['mail']['value'] = 'mail function';
  if (mail('example@example.com','','') ) {
    $requirements['mail']['severity'] = REQUIREMENT_OK;
  }else{
    $requirements['mail']['value'] = t('Not working');
    $requirements['mail']['severity'] = REQUIREMENT_ERROR;
    $requirements['mail']['description'] = t('mail() function not supported
                                                          please visit <a href="@url">PHP mail documentation for information on
                                                          how to correct this.', array('@url' => 'www.pl.php.net/manual/pl/ref.mail.php'));
  }
  $requirements['mail']['title'] = t('mail() function');
  return $requirements;
}

function custom_newsletter_install() {
  drupal_install_schema('custom_newsletter');
}

function custom_newsletter_uninstall() {
  drupal_uninstall_schema('custom_newsletter');
}

function custom_newsletter_schema() {
  $schema['custom_newsletter'] = array(
 	'fields' => array(
 			'id' => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE,),
 			'email' => array('type' => 'varchar', 'length' => 127, 'not null' => TRUE, 'default' => '',),
 			'hash' => array('type' => 'varchar', 'length' => 30, 'not null' => TRUE, 'default' => '',)
     ),
     'primary key' => array('id'),
  );
  return $schema;
}
?>

    Efektem końcowym jest nowy moduł w grupie ‘Other’, który przy próbie włączenia przy nieskonfigurowanym serwerze smtp powinien uniemożliwić instalację obwieszczając błąd przyjaznym różowym komunikatem, a po przejściu testu zgodności powinien utworzyć w bazie tabelę ‘custom_newsletter’. Aby usunąć tabelę z poziomu Drupala, należy wyłączyć moduł, a następnie gdy pojawi się on na liście modułów w zakładce “Uninstall” odinstalować go.
    Jak widać Drupal 6 ma wbudowaną Database Abstraction Layer, więc tabele i ich powiązania opisywane są za pomocą metadanych a nie jak w Drupal 5, kiedy trzeba było określać typ bazy oraz pisać oddzielne kwerendy dla wszystkich przypadków. We wcześniejszych wersjach Drupala istniała tabela ’sequences’ zliczająca ilość różnych elementów, co umożliwiało nadawanie unikalnych wartości kluczom, w wersji 6 korzysta się z własności auto_increment pogarsza to portability, ale podnosi wydajność.
    Po godzinie publikacji widać, że się ostro z tym namordowałem, interfejs administracyjny nawet na localhoście działa dość powolnie, tabela w bazie pokazała mi się dopiero po kilku próbach a raz Drupal się dość poważnie wywalił. Oczywiście po wdrożeniu do użytku większość wyświetlanych treści jest keszowana i całość prezentuje się dość płynnie, jednak zastanawia mnie jak dużo jeszcze złożoności udźwignie Drupal zanim stanie się przekombinowanym bloatem jak wordpress ;]

Przydatne linki:

• hook_requirements
• hook_install
• hook_uninstall
• hook_schema
• schema data types
• schema api
• schema reference

Comming soon: Blok z formularzem, przy odrobinie szczęścia wraz z obsługą AJAXa ;]

Gg samo w sobie ma w czasach obecnych coraz to więcej funkcji, ale nikt nie zdaje sobie sprawy z tego że większość tych funkcji była wcześniej wprowadzona w kadu. Aby wyposażyć kadu w dodatkowe opcje np: autoodpowiedź musimy zainstalować dodatkowe moduły. Instalacja kadu wraz z modułami:

sudo apt-get install kadu kadu-external-modules kadu-themes

po instalacji kadu, uruchomieniu go i skonfigurowaniu wciskamy F4 następnie dwuklikiem ładujemy interesujące nas moduły. Opisy modułów znajdziemy na oficjalnej stronie kadu.

Dodatkowe informacje wraz z zmianą wygladu okna rozmowy:

konfiguracja -> wygląd -> okno rozmowy -> edytuj

Wklejamy kod:

<p style=”background-color: #{backgroundColor}”>#{separator}
<kadu:header>
<table border=”0″ cellspacing=”0″ cellpadding=”0″ width=”100%”>
<tr>
<td align=”left” width=”17″ valign=”center”>
<img src=”{${KADU_CONFIG}/avatars/%u.png}{~${KADU_CONFIG}/avatars/%u.png @{Message}}” width=”15″ height=”15″ alt=”gg: %a” />
</td>
<td align=”left” valign=”center”>
<b><font color=”#{nickColor}” face=”Candara” size=”4″ style=”font-style: italic;”>%a </font></b> <i>%i</i> %v
</td>
<td align=”right” valign=”center”>
<font color=”#555″>#{receivedDate}[ / S #{sentDate}]</font>
</td>
</tr>
</table>
<hr color=”#ccc” />
</kadu:header>
<font color=”#{fontColor}”>#{message}</font>

zapisujemy daje nam taki efekt: zobacz

Zmiana emotikon kadu na emotikony z gadu:

1. Potrzebujemy emotikon, jeżeli ktoś posiada windowsa zainstalowanego na oddzielnej partycji ma z tym najmiejszy problem jeśli nie to ściągamy je stąd. Wchodzimy do katalogu: program files/gadu/emoticons na dysku na którym jest system windows i kopiujemy folder “emoticons”.

2. Następnie klikamy na folder z emotami “emoticons” prawym klawiszem myszki, zaznaczamy kopiuj.

3. Odpalamy Terminal i wpisujemy:

sudo nautilus

i wchodzimy do katalogu z emotami, mieści się on w:

/usr/share/kadu/themes/emoticons

4. wklejamy skopiowany folder i zmieniamy skopiowanemu folderowi nazwę na: “emoticons_gg”. sprawdzamy prawa odczytu jeśli odczyt ma tylko root zmieniamy go na naszą nazwe użytkownika.

5. Restartujemy Kadu.

6. Następnie prościutko:
Menu -> Konfiguracja -> Wygląd -> Okno rozmowy (zjeżdzamy paskiem na dół!)-> Ścieżki do zestawów ikon [Wybierz]
podajemy lokalizacje:
/usr/share/kadu/themes/emoticons/emoticons_gg

7. dodaj -> ok

8. Teraz wybieramy emoticony w polu zestaw, odszukujemy nazwy “emoticons_gg”
zastosuj -> ok, restartujemy kadu dla pewności. Powinno działać.

Zmiana domyślnych dźwięków na własne (nie działa w najnowszych wersjach kadu):

Dźwięki w kadu znajdują się w katalogu:

/usr/share/kadu/themes/sounds

jeśli umieścimy w nim zwykły folder z plikami wav nic nam to nie da, musimy napisać sobie sami plik z konfiguracją. W tym pliku znajdują się następujące dane:

[sounds]
NewMessage=msg.wav
NewChat=msg.wav
StatusChanged/ToOnline=msg.wav
StatusChanged/ToBusy=msg.wav
StatusChanged/ToInvisible=msg.wav
StatusChanged/ToOffline=msg.wav
ConnectionError=msg.wav
FileTransfer/IncomingFile=msg.wav
FileTransfer/Finished=msg.wav

Dźwięki do kadu znajdziemy w necie ja uzywam takich.
Z dodawaniem dźwięków postępujemy podobnie jak z emotikonami.

Wpisujemy w terminalu:

sudo nautilus

i wklejamy folder z naszymi dźwiękami do:

/usr/share/kadu/themes/sounds

następnie naszemu folderowi z dźwiękami nadajemy prawa do odczytu identycznie jak emotikonom.

Własne dźwięki ustawimy w powiadomienia -> dźwięk -> ścieżki do zestawów i tam wskazujemy: /usr/share/kadu/themes/sounds/nazwatwojegofolderu następnie wybieramy go po restarcie kadu i powinno śmigać

Zmiana ikon statusu kadu na ikony z gg (nie działa w najnwszych wersjach kadu):

Pobieramy plik z ikonami, rozpakowujemy go klikając prawym przyciskiem myszy. Po czym wycinamy go również klikając na wypakowany folder prawym przyciskiem myszy stosując opcję wytnij. Wpisujemy w konsoli:

sudo nautilus

i wchodzimy do folderu /usr/share/kadu/themes/icons wklejamy wycięty folder. Dajemu mu odpowiednie prawa – klikamy na niego prawym przyciskiem myszy właściwości -> uprawnienia dając mu i zawartym plikom w nim odpowiednie prawa jako nasz użytkownik. Jeśli wszystkie prawa zostały dobrze ustawione to powinniśmy je zobaczyć w menu -> konfiguracja -> wygląd -> ogólne tam też  ustawiamy zestaw ikon o nazwie wingg. Dajemy zastosuj -> ok.

Pamiętaj że robisz to na własną odpowiedzialność.