--=REKLAMA=--
Moduł jest lekkim i elastycznym dodatkiem używanym do generowania zawartości strony. Są one wykorzystywane do tworzenia niewielkich fragmentów strony, które są na ogół mniej złożone i są w stanie być wyświetlane z poziomu wielu komponentów.
Możesz znaleźć wiele przykładów modułów w standardowej instalacji Joomla! - menu, ostatnie artykuły, logowanie i wiele innych.
Ten poradnik wyjaśni, w jaki sposób stworzyć prosty moduł Witaj Świecie (Hello Word). W trakcie czytania poradnika nauczysz się, jak wygląda podstawowa struktura plików w module. Ta prosta struktura może być później wykorzystana do tworzenia bardziej rozbudowanych modułów.
Są cztery podstawowe pliki wykorzystywane w standardowym wzorcu projektowania modułu:
mod_helloworld.php
- Plik ten jest głównym punktem dostępu do modułu. Będzie wykonać wszelkie niezbędne procedury inicjalizacji, wywoływał procedury pomocnicze do pobierania danych i dołączał szablon, który będzie wyświetlany na wyjściu modułu.
mod_helloworld.xml
- Plik ten zawiera informacje o module. Określa, które pliki muszą zostać zainstalowane przez Joomla! i parametry konfiguracji modułu.
helper.php
- Zawiera klasę pomocniczą, która wykorzystywana jest do pobierania informacji, które mają zostać wyświetlone w module (zazwyczaj z bazy danych lub z innych źródeł).
tmpl/default.php
- Jest to szablon modułu. Plik ten odbierze dane zebrane w mod_helloworld.php i wygeneruje kod HTML, który zostanie wyświetlony na stronie.
Plik mod_helloworld.php będzie odpowiedzialny za trzy zadania:
Klasa pomocnicza zdefiniowana jest w pliku helper.php. Plik ten dołączany jest z wykorzystaniem instrukcji require_once:
require_once( dirname(__FILE__).'/helper.php' );
require_once
jest użyte, ponieważ nasze metody pomocnicze są zdefiniowane wewnątrz klasy, a także dlatego, że chcemy wczytać naszą klasę tylko raz.
Nasza klasa pomocnicza nie została jeszcze zdefiniowana, ale w jej skład będzie wchodziła tylko jedna metoda:: getHello(). Dla naszego prostego przykładu, nie jest ona wprawdzie wymagana - komunikat "Witaj Świecie", który będzie zwracać ta metoda, równie dobrze mógłby być dołączony do szablonu. Niemniej, użyjemy klasy pomocniczej w tym przykładzie do zademonstrowania tej prostej techniki.
Nasz moduł aktualnie nie korzysta z żadnych parametrów, ale przekażemy je do metody pomocniczej, aby mogły być wykorzystane później, jeśli zdecydujemy rozszerzyć możliwości naszego modułu.
Metoda klasy pomocniczej naszego modułu jest wywoływana w następujący sposób:
$hello = modHelloWorldHelper::getHello( $params );
Pełen kod pliku mod_helloworld.php wygląda następująco:
<?php // zabezpieczenie przed bezpośrednim dostępem defined( '_JEXEC' ) or die( 'Restricted access' ); // dołączanie klasy pomocniczej require_once( dirname(__FILE__).'/helper.php' ); $hello = modHelloWorldHelper::getHello( $params ); require( JModuleHelper::getLayoutPath( 'mod_helloworld' ) ); ?>
Jedyna linia której jeszcze nie omawialiśmy, to linia pierwsza. The one line that we haven’t explained so far is the first line. Linia ta sprawdza czy dostęp do pliku odbywa się za pośrednictwem aplikacji Joomla! Zapobiega to możliwości wstrzyknięcia niebezpiecznego kodu z zewnątrz oraz innym problemom związanym z bezpieczeństwem.
Plik helper.php zawiera klasę pomocniczą, która używana jest do uzyskania danych, które zostaną wyświetlone na wyjściu modułu. Jak wspomniano wcześniej, klasa a będzie mała tylko jedną metodę: getHello(). Metoda ta zwróci komunikat 'Witaj Świecie!'.
Oto kod pliku helper.php:
<?php class modHelloWorldHelper { /** * Zwraca komunikat powitalny * * @param array $params - obiekt zawierający parametry modułu * @access public */ public static function getHello( $params ) { return 'Witaj Świecie!'; } } ?>
Nie ma reguł odnoszących się do nazewnictwa klas pomocniczych, ale pomocne jest tworzenie takich nazw, które ułatwią zidentyfikowanie jej zawartości i przeznaczenia. Niemniej, przedstawiony w przykładzie format nazewnictwa jest wymagany, jeśli planujesz użyć pluginu com_ajax.
Bardziej zaawansowane moduły mogą zawierać zapytania do bazy danych lub inne metody w klasie pomocniczej.
Plik default.php jest szablonem wyświetlanym na wyjściu modułu.
Kod pliku default.php wygląda następująco:
<?php // no direct access defined( '_JEXEC' ) or die( 'Restricted access' ); ?> <?php echo $hello; ?>
Ważne pamiętać, że plik szablonu posiada ten sam zasięg co plik mod_helloworld.php file. Oznacza to, że zmienna $hello może być zdefiniowana w pliku mod_helloworld.php i bez żadnych dodatkowych deklaracji użyta w pliku szablonu.
Plik mod_helloworld.xml jest wykorzystywany do określenia, które pliki powinny zostać skopiowane podczas instalacji i używany przez menadżer modułów do zdefiniowania, które parametry modułu posłużą do jego konfiguracji. Inne informacje o module również są umieszczane w tym pliku.
Kod pliku mod_helloworld.xml wygląda następująco:
<?xml version="1.0" encoding="utf-8"?> <extension type="module" version="3.1.0" client="site" method="upgrade"> <name>Witaj Świecie!</name> <author>John Doe</author> <version>1.0.0</version> <description>Prosty moduł Witaj Świecie!</description> <files> <filename>mod_helloworld.xml</filename> <filename module="mod_helloworld">mod_helloworld.php</filename> <filename>index.html</filename> <filename>helper.php</filename> <filename>tmpl/default.php</filename> <filename>tmpl/index.html</filename> </files> <config> </config> </extension>
Plik manifestu wyjaśnia szczegóły techniczne dotyczące elementów stosowanych w pliku XML.
Można zauważyć, że pozostały jeszcze dwa pliki, które nie zostały omówione: index.html oraz tmpl/index.html. Pliki te zostały dołączone, by zapobiec możliwości wyświetlenia zawartości katalogów modułu. Jeśli użytkownik spróbuje wyświetlić zawartość katalogu modułu w przeglądarce, zostanie mu wyświetlony plik index.html. Plik ten może być zupełnie pusty lub zawierać prosty kod:
<html><body bgcolor="#FFFFFF"></body></html>
który wyświetli pustą stronę.
Ponieważ nasz moduł nie używa żadnych pól formularza, sekcja config jest pusta.
Tworzenie modułu w Joomla! jest dość prostym procesem. Używając metod opisanych w tym poradniku, można tworzyć moduły o szerokim zastosowaniu.