Wpis archiwalny z 2012 roku dotyczący Joomla 1.5, która od dawna nie jest wspierana. Jeśli potrzebujesz modułu na zamówienie dla aktualnej wersji Joomla, sprawdź naszą obsługę stron Joomla. Większość modułów, których chcielibyśmy użyć na naszej stronie jest już dostępna w internecie, wystarczy znaleźć, pobrać i zainstalować. Jednak czasami zdarza się, że potrzebnego nam jeszcze nikt nie napisał. Tutaj właśnie przyda nam się umiejętność pisania modułów dla Joomla! W tym poście dowiesz się, jak napisać od podstaw taki moduł oraz poznasz podstawy tworzenia modułów Joomla!
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 do 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ł będzie się składał tylko z 6 plików i katalogu. Z czego naprawdę 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 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, 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. Ostatnia 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 linii 22 podpinamy do klasy parametry modułu. Zmienna $params jest globalną dla każdego modułu. W linii 31 deklarujemy teksty naszych powitań do wyboru. A w linii 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 Twój kod będzie zwykle bardziej skomplikowany, na potrzeby tutorialu taki wystarczy. W pierwszej linii jak zwykle zabezpieczamy plik przed możliwością wykonania poza frameworkiem Joomla. W drugiej natomiast 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ść 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 linii 13. Tag folder z linii 16 pozwala nam dodać cały katalog wraz z jego plikami bez potrzeby ujmowania każdego pojedynczo. W linii 18 dodaliśmy tag params, zawierać on powinien parametry konfiguracyjne naszego modułu. Oczywiście moduł nie musi go posiadać ale w większości wypadków będzie przydatny. W linii 19 deklarujemy parametr konfiguracji, który wykorzystamy do wyboru powitania. W linii 24 natomiast deklarujemy parametry zaawansowane. Dwa zadeklarowane tam parametry określają nam czy system powinien zapisywać kod zwracany przez moduł w pamięci podręcznej (cache) (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. Gotową paczkę instalacyjną można pobrać stąd: mod_hello. Powinno to ułatwić Ci analizę modułu i szukanie ewentualnych błędów.
Podsumowanie
Nasz moduł jest oczywiście uproszczony. Mógłby jeszcze zawierać pliki językowe lub niestandardowe parametry, ale to ewentualnie omówię w kolejnych wpisach.
