Na początek ustalmy czym jest moduł Joomla. Jest to jeden z najmniejszych dodatków, który zwykle zajmuje się prezentacją niewielkich treści bądź przesyłaniem danych poprzez POST/GET to komponentów. My napiszemy mały moduł który w zależności od ustawień będzie wyświetlał tekst "Siema" lub "Witaj w świecie Joomla!".
Wymagania
Do napisania modułu potrzebne nam będą: podstawy Joomla!, php, html, xml, nasz ulubiony edytor (w moim wypadku NetBeans) i strona testowa postawiona na Joomla 1.5 celem sprawdzenia modułu.
Struktura plików modułu
Nasz prosty moduł składał się będzie tylko z 6 plików i katalogu. Z czego tak naprawę najważniejsze będą cztery z nich. Struktura plików naszego modułu wyglądać będzie jak na obrazku z boku. mod_hello.php jest plikiem głównym i to jego poszukiwać będzie system. mod_hello.xml jest plikiem instalacyjnym zawierającym szczegóły modułu, listę plików, oraz parametry konfiguracyjne. Plik default.php będzie zajmował się prezentacją danych. Dzięki umieszczeniu go w katalogu tmpl będziemy mieli możliwość nadpisania wyglądu naszego modułu w szablonie bez zmiany modułu (Wykorzystanie Template Overrides). Plik helper.php zawierać będzie wszystkie funkcje zajmujące się pobieraniem danych z systemu. Natomiast dwa pliki index.html są pustymi plikami umieszczonymi po jednym na każdy katalog modułu dla bezpieczeństwa na wszelki wypadek gdyby serwer miał włączone listowanie plików.
Tworzymy plik główny modułu
Najważniejszym plikiem modułu jest plik php o takiej samej nazwie jak moduł w naszym wypadku mod_hello.php. To jego będzie poszukiwał system system gdy zostanie wyświetlona strona z naszym modułem. Poniżej kod pliku głównego.
<?php defined('_JEXEC') or die;
// załączamy klasę pomocniczą
require_once ('helper.php');
// tworzymy instancję klasy i pobieramy nasze powitanie
$helper = new modHelloHelper($params);
// tekst naszego powitania
$hello_text = $helper->getHello();
require( JModuleHelper::getLayoutPath('mod_hello') );
Pierwsza linia sprawdza dla bezpieczeństwa czy moduł został uruchomiony w Frameworku Joomla! jeśli nie, kończy działanie. Ta deklaracja powinna znajdować się na początku w każdym pliku php modułu. W czwartej linii załączamy deklarację naszej klasy pomocniczej. W siódmej Tworzymy jej instancję by pobrać dane z systemu. Dziesiąta linia służy pobraniu tekstu powitania. Ostatnią linia (linia 12) odpowiada za prezentację danych w naszym szablonie. Funkcja ta pobiera adres pliku default.php dla naszego modułu (jeśli nie ma jej w szablonie wykorzysta domyślne naszego modułu).
Klasa pomocnicza modułu
By trzymać oddzielnie prezentację modułu od pobierania danych stworzymy klasę pomocniczą modHelloHelper w pliku helper.php, która zajmie się pobraniem danych do wyświetlenia przez moduł. To w niej powinny znajdować się funkcje pobierania danych z bazy, pliku, czy też innych stron. Nasza klasa wyglądać będzie następująco.
<?php
defined('_JEXEC') or die;
/**
* Klasa pomocnicza modułu
*/
class modHelloHelper {
/**
* Parametry modułu
*
* @var JRegistry
*/
var $_params;
/**
* Podpinamy parametry
*
* @param JRegistry $params
*/
function __construct($params) {
$this->_params = $params;
}
/**
* Zwracamy nasze powitanie
*
* @return string
*/
function getHello() {
$hello = array(
0 => 'Siema',
1 => 'Witaj w świecie Joomla!',
);
return $hello[$this->_params->get('hello_id', 0)];
}
}
W naszym wypadku klasa nie będzie nic pobierała z zewnętrznych stron czy bazy więc jest mała. W lini 22 podpinamy do klasy parametry modułu. Zmienna $params jest globalną dla każdego modułu. W lini 31 deklarujemy teksty naszych powitań do wyboru. A w lini 36 zwracamy wybrane w zależności od parametru hello_id z pliku instalacyjnego (konfiguracji) modułu.
Szablon modułu
Teraz przygotujemy plik zajmujący się prezentacją naszych danych użytkownikom. Dla każdego modułu plik ten powinien nazywać się default.php i znajdować w katalogu tmpl. Dzięki temu projektanci będą mogli modyfikować wygląd modułu bez potrzeby ingerowania w kod modułu.
<?php defined('_JEXEC') or die; ?>
<p class="greeting"><?php echo $hello_text ?></p>
Oczywiście wasz kod będzie zwykle bardziej skomplikowany, na potrzeby tutorialu taki wystarczy. W pierwszej lini jak zwykle zabezpieczamy plik przed możliwością wykonania poza framework'iem Joomla. W drugiej ntomiast wyświetlamy nasze powitanie pobrane z klasy pomocniczej w pliku mod_hello.php.
Plik instalacyjny/konfiguracyjny modułu
Ostatnim plikiem, który jest wymagany do instalacji modułu i zadeklarowania parametrów konfiguracyjnych jest plik mod_hello.xml. Schemat nazwy jest taki sam jak w przypadku pliku głównego, tj. nazwa taka jak nazwa modułu i rozszerzenie xml.
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>Powitanie</name>
<author>Imię i Nazwisko Autora</author>
<creationDate>Data stworzenia modułu (w dowolnym formacie)</creationDate>
<copyright>Nazwia podmiotu posiadającego prawa do modułu</copyright>
<license>Licencja (np GNU/GPL 3.0)</license>
<authorEmail>Adres e-mail autora</authorEmail>
<authorUrl>Adres strony www autora</authorUrl>
<version>Wersja (dowolny ciąg znaków)</version>
<description>Krótki opis modułu</description>
<files>
<filename module="mod_hello">mod_hello.php</filename>
<filename>helper.php</filename>
<filename>index.html</filename>
<folder>tmpl</folder>
</files>
<params>
<param name="hello_id" type="list" default="0" label="Powitanie" description="Wybierz powitanie">
<option value="0">Siema</option>
<option value="1">Witaj w świecie Joomla!</option>
</param>
</params>
<params group="advanced">
<param name="cache" type="list" default="1" label="Cache" description="Czy zapisywać w Cache">
<option value="1">Globalnie</option>
<option value="0">Nie</option>
</param>
<param name="cache_time" type="text" default="15" label="Czas Cache" description="Czas przechowywania w Cache" />
</params>
</install>
Pierwsze tagi pliku są dośc oczywiste i nie ma sensu tłumaczyć do czego służą. W tagu <files> umieszczamy listę plików naszego modułu z pominięciem pliku XML (tj mod_hello.xml) inaczej instalator nie pozwoli na instalację modułu. Plik główny modułu powinien mieć w tagu filename dodany atrybut module ustawiony na nazwę modułu tak jak to jest w lini 13. Tag folder z lini 16 pozwala nam dodać cały katalog wraz z jego plikami bez potrzeby ujmowania każdego pojedynczo. W lini 18 dodaliśmy tag params, zawierać on powinien parametry konfiguracyjne naszego modułu. Oczywiście moduł nie musi go posiadać ale w większności wypadków będzie przydatny. W lini 19 deklarujemy parametr konfiguracji, który wykorzystamy do wyboru powitania. W lini 24 natomiast deklarujemy parametry zaawansowane. Dwa zadeklarowane tam parametry określają nam czy system powinien zapisywać kod zwaracany przed moduł w cachu (parametr o nazwie cache) oraz jak długo powinien on być przechowywany do czasu odświeżenia (parametr cache_time). Wszystkie typy parametrów wraz z przykładami można znaleźć pod tym adresem:
http://docs.joomla.org/J1.5:Standard_parameter_types
Przygotowanie paczki instalacyjnej
Jedyne co nam pozostało to spakować wszystkie pliki jako ZIP i przetestować działanie naszego modułu. Kotową paczkę instalacyjną można pobrać z tąd mod_hello. Powinno to ułatwić wam analizę modułu i szukanie ewentualnych błędów.
Podsumowanie
Nasz moduł jest oczywiście uproszczony. Mógl by on jeszcze zawierać pliki językowe lub też niestandardowe parametry ale to obejmę może w nastpęnych postach.
