Pisanie modułu Joomla cz.1
Moduły to jedne z najmniejszych dodatków Joomla choć mogą być także niezwykle rozbudowane. Każda instalacja Joomla posiada domyślnie zainstalowane kilkanaście modułów takich jak np: mod_mainmenu, mod_login czy mod_banners.Joomla pozwala posiadać na jednej podstronie kilka takich samych modułów co czyni je niezwykle przydatnymi jeśli część naszego kodu powtarza się w kilku miejscach lub musi się wyświetlać niezależnie od tego jaki aktualnie komponent jest uruchomiony.
Wymagania: podstawy php i html/xml
Nasz prosty moduł składał się będzie tylko z 6 plików i katalogu. Będzie on wyświetlał w zależności od tego czy aktualna minuta jest parzysta czy nie, pierwsze powitanie lub drugie (oba będą parametrami modułu ustalanymi w panelu Joomla)
Struktura katalogu modułu
Oto struktura katalogu z naszym modułem:/mod_witam.php
/mod_witam.xml
/helper.php
/index.html
/tmpl/
/default.php
/index.html
Nazwa katalogu powinna być taka sama jak nazwa modułu i poprzedzona prefiksem "mod_". W naszym przypadku będzie to katalog o nazwie "mod_witam".
Pliki modułu
Plik mod_witam.php to główny plik naszego modułu, jest wymagany przez system i nie może jego zabraknąć w żadnym module. To jego będzie szukał gdy dodamy moduł gdzieś na stronie.mod_witam.php:
<?php defined('_JEXEC') or die('Direct Access Denied');
// załączamy klasę pomocniczą
require_once ('helper.php');
// tworzymy instancję klasy i pobieramy nasze powitanie
$helper = new modWitamHelper($params);
$item =& $helper->getPowitanie();
require( JModuleHelper::getLayoutPath('mod_witam') );
W pierwszej linijce mamy zabezpieczenie przed bezpośrednim uruchomieniem pliku. Stała _JEXEC jest zadeklarowana w głównym pliku systemu tj. index.php i każda próba uruchomienia naszego modułu bezpośrednio zakończy się wyświetleniem komunikatu "Direct Access Denied"
W kolejnej linijce załączmy plik z klasą pomocniczą modułu. To w nim powinniśmy wykonywać operacje pobierania danych z bazy, pliku czy innych stron. Dzięki temu kod HTML naszego modułu będzie zawierał mniej kodu PHP a co za tym idzie będzie łatwiejszy do zmian dla webmastera.
Następnie tworzymy instancję klasy pomocniczej i pobieramy nasze powitanie.
Na końcu załączamy plik, którego adres zwróci nam funkcja JModelueHelper::getLayoutPath(). Funckja ta sprawdza, czy w obecnie używanym szablonie strony istnieje plik szablonu modułu o nazwie "mod_witam", czyli naszego dodatku. W ten sposób możemy zmieniać wygląd naszego modułu zależnie od szablonu strony bez ingerowania w sam kod modułu. Technika ta nazywa się Template Overrides (Nadpisywanie szablonem)
Kod helper.php:
<?php defined('_JEXEC') or die('Direct Access Denied');
class modWitamHelper {
var $_tekst1; // pierwsze powitanie
var $_tekst2; // drugie powitanie
var $_params; // parametry modułu
function __construct( &$params ) {
$this->_params =& $params;
$this->_tekst1 = $this->_params->get('witam1','Witam!');
$this->_tekst2 = $this->_params->get('witam2','Hello!');
}
/**
* Zwracamy nasze powitanie
* @return string
*/
function &getPowitanie() {
if ( date('i', time())%2 == 0 ) {
$powitanie = $this->_tekst1;
} else {
$powitanie = $this->_tekst2;
}
return $powitanie;
}
}
W pierwszej linijce jak zawsze sprawdzamy czy plik nie jest uruchomiony bezpośrednio. Następnie deklarujemy nasza klasę pomocniczą. Ważne żeby ta klasa nie nosiła nazwy którejś z klas systemu, dlatego dobrze jest ją nazywać używając schematu:
[mod][Nazwa modułu][Nazwa klasy pomocniczej]
Deklarujemy 3 zmienne klasy, pierwsze 2 to powitania pobrane z parametrów a drugie to sam obiekt parametrów.
Jak parametr konstruktora klasy przyjmujemy parametry. Dzięki temu podczas tworzenia klasy, nasza klasa automatycznie będzie miała dostęp do parametrów modułu. Następnie podczepiamy nasze parametry do zmiennej w klasie na wypadek gdybyśmy potrzebowali je jeszcze gdzieś w naszej klasie.
Jedyna właściwa funkcja w naszej klasie to getPowitanie(). Zwraca ona nam powitanie w zależności od tego czy obecna minuta jest parzysta czy nie.
Kod /tmpl/default.php
<?php defined('_JEXEC') or die('Direct Access Denied') ?>
<div style="background:#b6df6d;
border-radius:10px;
-moz-border-radius:5px;
-webkit-border-radius:5px;
border:1px solid #538200;
text-align:center;
padding:8px 10px;
font:bold 22px 'Arial';
color:#ecffca">
<?php echo $powitanie ?>
</div>
W pliku default.php mamy dostęp do wszystkich zmiennych głównego pliku modułu więc także i do naszego pobranego powitania.
Żeby nasz moduł nie był taki nudny zrobiłem ładne okrągłe obramowanie w CSS3 (niestety nie zawsze będzie widoczne ze względu na to, że CSS3 jest nadal w fazie projektowania i nie wszystkie przeglądarki go obsługują ) naszego tekstu.
Instalacja modułu
Teraz jedyne co nam pozostało to przygotować plik instalacyjny naszego modułu. Będzie on zawierał także parametry naszego modułu, które zobaczymy w konfiguracji modułu.Kod mod_witam.xml:
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>Powitanie</name>
<author>Artur Stępień</author>
<creationDate>Marzec 2010</creationDate>
<copyright>www.b-support.pl</copyright>
<license>GNU/GPL 2.0</license>
<authorEmail> Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć. </authorEmail>
<authorUrl>www.b-support.pl</authorUrl>
<version>1.0.0</version>
<description>Moduł powitanie</description>
<files>
<filename module="mod_witam">mod_witam.php</filename>
<filename>helper.php</filename>
<filename>index.html</filename>
<folder>tmpl</folder>
</files>
<params>
<param name="witam1" type="text" default="Witam!" label="Powitanie 1" description="Treść pierwszego powitania" />
<param name="witam2" type="text" default="Hello!" label="Powitanie 2" description="Treść drugiego powitania" />
</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>
Znaczenie tagów: name, author, creationDate, copyright, license, authorEmail, authorUrl, version i desription uważam za oczywiste i nie będę ich tłumaczył. Będą one takie same dla każdego dodatku Joomla.
W tagu<files> umieszczamy listę plików modułu. Każdy plik umieszczamy w tagu <file>. Dodatkowo w tagu który zawierać będzie główny pliki naszego modułu (mod_witam.php) dodajemy atrybut module="mod_witam", w którym umieszczamy nazwę naszego modułu. Jeśli w naszym module jest jakiś katalog a w nim pliki lub/i katalogi nie musimy dodawać każdy plik/katalog oddzielnie. Wystarczy nazwę takiego katalogu umieścić w tagu <folder>. Naprawdę upraszcza to przygotowanie pliku instalacyjnego przy większych dodatkach Joomla.
W każdym katalogu modułu, czy dowolnego innego dodatku Joomla powinniśmy umieścić czysty plik index.html. Dzięki temu nikt obcy nie będzie miał możliwości przejrzenia struktury katalogów naszej strony.
Uwaga: Na liście plików modułu nie umieszczaj także pliku instalacyjnego (mod_witam.xml). Spowoduje to błąd i nie pozwoli na instalację modułu
W tagu <params> umieszczamy parametry naszego modułu. Lista dostępnych domyślnie typów parametrów Joomla znajduje się tutaj:
http://docs.joomla.org/Standard_parameter_types
Moduł może posiadać 2 tagi <params>. Jeden zwykły zawierający domyślne parametry Joomla (w panelu nazwane "Parametry modułu"), oraz drugi zawierający parametry zaawansowane (w panelu nazwane "Parametry: rozszerzone"). Ten drugi powinien zawierać atrybut group="advanced" (). Te dwa parametry, które są umieszczone w naszym module w grupie advanced umożliwiają nam korzystanie z Cache systemu. Dzięki temu moduły pobierające dane np. z bazy danych nie będą wykonywały zapytań przy każdym wyświetleniu. Umożliwia nam to także wyłączenie korzystania z Cache na wypadek gdyby dane umieszczone w module musiały być aktualne. pierwszy parametr decyduje czy moduł będzie korzystał z Cache, drugi natomiast podaje czas, po którym zawartość modułu powinna byś odświeżona. Te dwa parametry powinny być umieszczone w każdym module Joomla choć nie są one wymagane.
Teraz wystarczy spakować cały katalog /mod_witam/ w ZIP i zainstalować.
Pobierz gotową paczkę instalacyjną:
Pobierz: mod_witam.php
Oczywiście cały proces budowania modułu możemy wykonywać na gotowej instalacji Joomla. Znacznie ułatwi nam to debugowanie bo nie będziemy musieli podawać od razu wszystkich plików modułu i za każdym razem go instalować. Wystarczy umieścić katalog modułu (/mod_witam) w katalogu /modules systemu Joomla. Poprawne muszą być także nazwy naszych plików i budowa pliku instalacyjnego (musi się parsować i zawierać w tagu <files> tag <file module="mod_witam">mod_witam.php</file>)
Podsumowanie
Duża część naszego modułu nie jest wymagana. Np. cały moduł mógł by się składać z 3 plików (mod_witam.php, mod_witam.xml i index.html) ale utrudniło by to dokonywanie zmian przez webmastera. Pominąć można by też oba parametry Cache w pliku instalacyjnym ale przy większej ilości własnych modułów na naszej stronie nie mielibyśmy kontroli nad tym co jest zapisywane co co regularnie aktualizowane.Zachęcam także do zapoznania się z angielską wersją dokumentacji dla programistów Joomla: http://docs.joomla.org/Developers.