Modul - opis

1.1. Moduł – Wprowadzenie
Moduły, obok komponentów, botów oraz szablonów są jednym z podstawowych elementów wchodzących w skład witryny budowanej w oparciu o CMS Joomla. Moduł, jest to lekki i elastyczny element
rozszerzający funkcjonalność witryny. Dla Joomla 1.5 moduły budowane są w oparciu o wzorzec
MVC (ang. Model-View-Controller), z czego wynika odpowiednia struktura plików wchodzących w
skład modułu. Standardowa instalacja Joomla zawiera wiele przykładów tego elementu, jakich jak
moduł logowania, menu czy sonda. Umiejscowienie modułu zaleŜny od szablonu witryny i jej konfiguracji.
Głównym zadaniem modułu jest pobieranie danych oraz ich prezentacja. Moduły występują zarówno
po stronie uŜytkowej witryny jak równieŜ w panelu administracyjnym.
Na potrzeby niniejszego samouczka zostanie zbudowany moduł, wyświetlający liczbę artykułów opublikowanych w instancji Joomla, w której moduł zostanie uruchomiony. Dodatkowo przedstawiony
zostanie sposób umieszczenia modułu w portalu.
1.2. Moduły - struktura plików
Architektura modułu według Joomla 1.5 zakłada, Ŝe wszystkie pliki modułu znajdują się w katalogu
którego nazwa budowana jest według wzorca:
mod_nazwamodułu
Ponadto zakłada się, ze katalog modułu zaimplementowanego na potrzeby witryny znajduje się w:
katalog_głowny\modules\
Moduły dla witryny administratora umiejscowione są w katalogu:
katalog_głowny\administrator\modules\
Informacja ta jest o tyle istotna, Ŝe zgodnie z powyŜszym schematem postępuje skrypt instalujący
moduł w systemie, co zostanie omówione później. Zakładamy, Ŝe nasz projekt (moduł) nazywa się
tabinfo, zgodnie z czym katalog główny modułu to mod_tabinfo. Ponadto pamiętać naleŜy, ze kaŜdy
katalog w strukturze modułu zawiera plik index.html. Plik ten najczęściej posiada pustą zawartość, a
jego zadaniem jest uniemoŜliwienie nieuprawnionego dostępu do struktury katalogu.
W strukturze katalogowej modułu wyróŜnić moŜna następujące pliki:
- mod_tabinfo.php – plik ten stanowi punkt wejściowy (uruchomieniowy) modułu, zgodnie ze wzorcem MVC pełni on role kontrolera. Za pomocą tego pliku dokonujemy inicjalizacji modułu, wywołujemy
model (w nomenklaturze Joomla zwanym helper), który słuŜy nam do pozyskiwania danych oraz uruchamia szablon, który słuŜy do wyświetlenia pozyskanych danych.
- mod_tabinfo.xml – plik opisujący moduł, wywoływany w trakcie instalacji modułu w systemie. Dodatkowo w pliku tym zamieszczone są parametry konfiguracyjne modułu.
- helper.php – plik inicjalizuję klasę helper, słuŜącą do pozyskiwania danych. Według wzorca MVC
plik ten naleŜy traktować jako model danych.
- temp\default.php – plik szablonu, którego zadaniem jest prezentacja danych. Według MVC jest to
widok.
1.3. Moduły – Model
Opis poszczególnych elementów modułu rozpoczniemy niejako od środka czyli od modelu danych.
Model danych (według Joomla 1.5 – helper) zajmuje się pozyskiwaniem danych. W efekcie moduł
działa tak, Ŝe niejako wytwarza dane za pomocą modelu i w odpowiedni sposób je wyświetla. Kod
modelu wykorzystywanego w opisywanym module został przedstawiony poniŜej.
defined('_JEXEC') or die('Restricted access');
class modTabInfoHelper {
function getTabInfo($params) {
$db = &JFactory::getDBO();
$query = "SELECT * FROM `jos_content`";
$db->setQuery($query);
$db->query($query);
return $db->getNumRows();;
}
}
Z punkty widzenia działania naszego modułu istotne są przede wszystkim nazwa klasy i nazwa funkcji.
Ale czym zajmują się poszczególne linie kodu? Pierwsza linia uniemoŜliwia bezpośrednie wywołanie
pliku. Oznacza to, Ŝe moŜe on być uruchomiony tylko przez instancję aplikacji. Na marginesie, kaŜdy
plik PHP w Joomla 1.5 zawiera powyŜszą linię (a przynajmniej powinien zawierać).
Kolejna linia jest rozpoczęciem definicji klasy. Następna linia oznacza rozpoczęcie definicji funkcji.
Funkcja moŜe, lecz nie musi pobierać parametr. Jak napisano we wstępie moduł zajmuje się pozyskiwaniem informacji na temat liczby artykułów i wyświetlaniem ich na stronie. Opisywana funkcja skierowuje zapytanie do bazy danych i zwraca uzyskany wynik w odpowiedniej postaci. I tak, kolejno
pierwsza linia funkcji to pozyskanie obiektu dającego moŜliwość dowołania do bazy danych. Nawiązanie połączenia do bazy danych następuje w innym miejscu systemu i jest on współdzielone przez inne
elementy. Innymi słowy jeśli jakiś moduł chce się połączyć do bazy danych, to nie tworzy nowego
połączenia tylko korzysta z juŜ istniejącego.
Kolejnym elementem jest definicja zapytania SQL (ang. Structured Query Language), jakie zostanie
skierowane do bazy danych (treść zapytania: „Pobierz wszystkie elementy tabeli ‘jos_content’ –
czyli tablicy z artykułami"). W kolejnych dwóch krokach dokonujemy ustawienia zapytania do wykonania i wykonania zapytania. Jako efekt wykonania zapytania dostajemy tablicę obiektów reprezentujących wszystkie elementy rzeczywistej tabeli danych (lub null – jeŜeli tabela danych nie posiada artykułów).
Ostatnim krokiem jest policzenie liczby elementów pozyskanych w wyniku wyŜej wymienionych operacji i zwrócenie wyniku na zewnątrz funkcji (czyli do elementu ją wywołującego).a
1.4. Moduły – Kontroler
Kontroler, jest to centralna część naszego moduły. Z jednej strony zajmuje się uruchomieniem modelu
danych, celem pozyskania informacji, z drugiej zaś strony jest odpowiedzialny za wywołanie widoku,
czyli wyświetlenie danych w odpowiedniej formie. Kod kontrolera przedstawiono poniŜej.
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
require_once (dirname(__FILE__).DS.'helper.php');
$hello = modTabInfoHelper::getTabInfo( $params );
require(JModuleHelper::getLayoutPath('mod_tabinfo'));
Pierwsza linia kodu reguluje prawa dostępu do pliku (opisano w paragrafie dotyczącym modelu danych). Druga linia to wywołanie klasy helper.php. Jest to klasa naszego modelu danych. Przed uruchomieniem tej funkcji, musimy się upewnić, Ŝe obiekt klasy moŜe być uŜyty. Kolejna linia kodu to
faktyczne wywołanie metody z klasy naszego modelu danych. Wynik wywołania zostaje przypisany do
zmiennej. Ostatnia linia kodu natomiast to wywołanie widoku.
W tym miejscu warto zwrócić uwagę, na fakt, Ŝe wywołując widok naszego modułu nie wskazujemy
bezpośrednio nazwy pliku. Wniosek jest oczywisty, mianowicie wywołujemy widok domyślny. Stąd tez
naleŜy zwrócić uwagę, na konwencję nazewnictwa dotyczącą pliku widoku. Oczywiście nazwa widoku
moŜe być inna od domyślnej, wówczas nazwę pliku naleŜy podać bezpośrednio w kontrolerze. Stwierdzenie powyŜej stanowi podstawę do drugiego wniosku, a mianowicie moduł moŜe mieć wiele róŜnie
zdefiniowanych widoków i w zaleŜności od przebiegu programu moŜe zostać wywołany jeden z nich.
1.5. Moduły – Widok
Zadaniem widoku jest prezentacja danych modelu uŜytkownikowi końcowemu. W naszym przypadku
sam plik widoku zawiera dwie linie kodu.
defined('_JEXEC') or die('Restricted access');
echo "Liczba artykułów: ".$rowNum;
Pierwsza dotyczy kontroli sesji, druga zaś to wyświetlenie informacji o liczbie artykułów na stronie. W
praktycznych rozwiązaniach zazwyczaj kod prezentacji danych jest opatrzony notacją HTML + CSS
celem uzyskania dobrej jakości efektów wizualnych.
Zastosowanie modelu MVC przy budowie modułów dla Joomla 1.5 daje nam moŜliwość rozdzielenia
warstwy aplikacji od warstwy prezentacji danych, co przy tworzeniu zaawansowanych rozwiązań daje
znaczącą poprawę efektywności kodu.
1.6. Moduły – XML konfiguracyjny
Plik konfiguracyjny mod_tabinfo.xml stanowi opis podstawowych parametrów moduły, takich jak
nazwa modułu pod jaka będzie on widoczny w instancji systemu, nazwa autora i jego dane kontaktowe, licencja na jakiej moduł jest rozpowszechniony, opis modułu i jego wersja. Pierwsze dwie linie
pliku definiują wersję języka XML oraz wersję Joomla dla jakiej moduł jest dedykowany.
Oprócz funkcji opisowej plik ten wykorzystywany jest podczas instalacji modułu. W sekcji zdefiniowany
jest katalog, w którym mają być umieszczone plik podczas instalacji oraz które plik maja być skopiowane. Istotny jest fakt, Ŝe skopiowane zostaną tylko te pliki, które zostały wymienione w wyŜej wymienionym pliku.
Kolejna sekcja to parametry. Jest ona opcjonalna w tej wersji moduły nie wykorzystywana. SłuŜy ona
do konfiguracji aplikacji w systemie.
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>TabInfo</name>
<author>Adam Król</author>
<creationDate>Wrzesień 2009</creationDate>
<copyright>Copyright (C) 2009 Open Source Matters.</copyright>
<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license>
<authorEmail>admin[at]ituzytki.cba.pl</authorEmail>
<authorUrl>www.ituzytki.cba.pl</authorUrl>
<version>1.1</version>
<description>Przykładowy moduł .</description>
<files>
<filename module="mod_tabinfo">mod_tabinfo.php</filename>
<filename>mod_tabinfo.xml</filename>
<filename>index.html</filename>
<filename>helper.php</filename>
<filename>tmpl/default.php</filename>
<filename>tmpl/index.html</filename>
</files>
<!-- Optional parameters -->
<params />
</install>
1.7. Moduły – Instalacja
Przed przystąpieniem do instalacji modułu w systemie musimy mieć utworzony pakiet instalacyjny.
Wszystkie wymienione dotychczas pliki naleŜy spakować (wraz z odzwierciedleniem katalogów i plikami index.html w kaŜdym z katalogów) do paczki .zip.
W panelu administracyjnym w chodzi do zakładki Rozszerzenia -> Instalator. Następnie wybieramy
naszą paczkę instalacyjną wybieramy klawisz „Wczytaj plik & Zainstaluj”. Instalator otwiera plik instalacyjny (wcześniej przez nas utworzony) i kopiuje odpowiednie pliki do struktury katalogowej. Dodatkowo dokonywany jest odpowiedni wpis w tabeli bazy danych (tabela *_modules). W ten sposób
zainstalowany moduł jest gotowy do wykorzystania w naszej witrynie.
1.8.1. Moduły zaawansowane – Parametry
Analizując moduły zainstalowane w Joomla 1.5 łatwo stwierdzić, Ŝe niemal kaŜdy moduł moŜe być
konfigurowany z poziomu panelu administratora. No i słusznie, moduł który moŜna rekonfigurować do
aktualnych potrzeb bez zmiany kodu poszczególnych elementów jest bardziej elastyczny i ergonomiczny w uŜyciu. Przewidując róŜne potrzeby uŜytkowników moŜe stworzyć naprawdę praktyczne i
elastyczne narzędzie.
Aby mieć moŜliwość korzystania z parametrów w module naleŜy je prawidłowo zdefiniować w pliku
deskryptora modułu (w naszym przypadku jest to mod_tabinfo.xml). Fragment kody poniŜej dotyczy
jedynie sekcji związanej z parametrami:
<params>
<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />
<param name="@spacer" type="spacer" default="" label="" description="" />
<param
name="tag_table"
type="radio"
default="0"
label="Select
table:"
description="PARAMTABDESC">
<option value="0">ARTICLES</option>
<option value="1">USERS</option>
</param>
</params>
<params group="advanced">
<param
name="tag_label"
type="list"
default="0"
label="Label
decoration"
description="PARAMLABELDESC">
<option value="N">Normal</option>
<option value="B">Bold</option>
<option value="I">Italic</option>
<option value="U">Underline</option>
</param>
</params>
W pliku konfiguracyjnym sekcja parametrów znajduje się bezpośrednią pod sekcją <files />. W powyŜszym przypadku. Parametry zostały podzielone na dwie grupy, sekcja podstawowa parametrów
(rozpoczynająca się znacznikiem <params>) oraz sekcja zaawansowana (rozpoczynająca się znacznikiem <params group="advanced">). Dzięki temu w panelu administracyjnym kaŜda grupa parametrów wyświetlana jest w oddzielnym oknie. Zwiększa to oczywiście przejrzystość całego okna.
Co oznaczają kolejno zdefiniowane parametry? Pierwszy z nich - moduleclass_sfx to parametr określający przedrostek dla arkusza stylów danego modułu. Dzięki niemy bez zmiany oryginalnego arkusza stylów moŜna definiować klasy stylów dla konkretnego modułu. Temat ten jest ściśle związany z
konfiguracja szablonów więc nie będzie w tym miejscu rozwijany. Warto tylko zaznaczyć, Ŝe jest to
standardowy parametr definiowany prze większość modułów.
Kolejny parametr - @spacer to definicja separatora. W zaleŜności od przeglądarki i zdefiniowanego
arkusza stylów jest on wyświetlany jako pozioma linia odseparowująca od siebie parametry (te występujące nad nim od tych występujących pod nim).
Ostatni parametr w tej sekcji - tag_table to parametr typu „radio button”. Parametr ten ma zdefiniowane dwie wartości. Za jego pomocą będziemy w stanie określić z której tabeli zamierzamy czytać dane.
Ostatni ze wszystkich parametrów określonych w pliku konfiguracyjnym - tag_label to parametr typu
lista rozwijalna. Ma on określone cztery róŜne wartości. Na jego podstawie określony zostanie sposób
wyświetlenia wyniku modułu.
Jak łatwo zauwaŜyć dla kaŜdego parametru zdefiniowana została określona lista atrybutów, i tak:
•
name – oznacza nazwę atrybutu za pomocą którego parametr będzie identyfikowany w systemie, za pomocą tej nazwy będziemy w stanie odczytać wartość parametru w kodzie modułu;
•
type – określa typ parametru, przez co określone są pewne właściwości parametru, za jego
pomocą stwierdzamy czy jest to lista, przełącznik, pole itp. Wszystkie typy parametrów moŜna
znaleźć na stronie domowej Joomla;
•
default – oznacza wartość domyślna jaka przyjmować ma określony parametr;
•
label – określa opis parametru jaki będzie się wyświetlał w panelu administracyjnym;
•
description – jest to atrybut którego wartość jest wyświetlana w sytuacji najechania kursorem
wyszy na nazwę parametru, jest to po prostu opis parametru;
Dla parametrów dających moŜliwość interakcji uŜytkownika określa się dodatkowo określona liczbę
wartości, czyli atrybut <option>. KaŜdy z nich posada wartość oraz opis.
W tym miejscu warto zauwaŜyć, Ŝe pola label, description czy opis parametru mogą podlegać internacjonalizacji. Innymi słowy wartość tych pól moŜna określić za pomocą etykiet, które mogą mieć róŜną
postać w zaleŜności od języka witryny. Przykładem tego typu zachowania jest parametr moduleclass_sfx dla którego wartość opisu określona jest za pomocą etykiety PARAMMODULECLASSSUFFIX. W zaleŜności od języka witryny etykieta ta przyjmuje róŜne wartości określone w odpowiednich
plikach językowych.
1.8.2. Moduły zaawansowane – Parametry
Do pobrania wartości parametru słuŜy następujące polecenie:
$params->get( 'tag_table' );
Za pomocą powyŜszego polecenia jesteśmy w stanie wydobyć wartość parametru ‘tag_table’ z tablicy
$params jaki został zdefiniowana przez uŜytkownika modułu w panelu administracyjnym. Dla przypomnienia w pliku konfiguracyjnym zdefiniowane zostały dwie wartości dla tego parametru:
<option value="jos_content">ARTICLES</option>
<option value="jos_users">USERS</option>
Jak widać wartość parametru odpowiada jednoznacznie nazwie tablicy do jakiej chcemy się odwołać.
Wartość tego parametru przekazywany jest bezpośrednio do metody pobierającej dane z bazy. Na
podstawie tego parametru 'tag_table' budowane jest odpowiednie zapytanie do bazy danych. Kod
modelu oraz metoda pobierająca dane z bazy danych zostały przedstawione poniŜej.
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
require_once (dirname(__FILE__).DS.'helper.php');
$rowNum = modTabInfoHelper::getTabInfo($params->get( 'tag_table' ));
if (!strcmp($params->get('tag_table'),"jos_content")) {
require(JModuleHelper::getLayoutPath('mod_tabinfo'));
} else {
require(JModuleHelper::getLayoutPath('mod_tabinfo','users'));
}
class modTabInfoHelper {
function getTabInfo($params) {
$query = "SELECT * FROM `".$params."`";
$db = &JFactory::getDBO();
$db->setQuery($query);
$db->query($query);
return $db->getNumRows();;
}
W modelu zastosowany został pewien wymyk odwołania modułu do widoku. Mianowicie w zaleŜności
od tego, czy wyświetlamy liczbę artykułów w portalu czy liczbę zarejestrowanych uŜytkowników wybierany jest inny widok. Oczywiście moŜna tego typu problemy rozwiązać w duŜo bardziej elegancki sposób, nam jednak chodzi o pokazanie w jaki sposób wyświetlane są róŜne widoki w zaleŜności od działania modułu. JeŜeli wybrana została tablica ‘jos_content’ w panelu administracyjnym wówczas wywoływany jest widok domyślny (w katalogu tmpl plik default.php). W przeciwnym przypadku wywoływany jest widok users.php (w wywołaniu podajemy nazwę widoku bez rozszerzenia php). PoniŜej
przedstawiono zawartość pliku widoku users.php.
defined('_JEXEC') or die('Restricted access');
if (!strcmp($params->get('tag_label'),"N")) {
echo "Liczba uŜytkowników: ".$rowNum;
} else if (!strcmp($params->get('tag_label'),"B")) {
echo "<strong>Liczba uŜytkowników:</strong> ".$rowNum;
} else if (!strcmp($params->get('tag_label'),"I")) {
echo "<em>Liczba uŜytkowników:</em> ".$rowNum;
} else if (!strcmp($params->get('tag_label'),"U")) {
echo "<span style="text-decoration: underline;">Liczba uŜytkowników:</span> ".$rowNum;
} else {
echo "Liczba uŜytkowników: ".$rowNum;
}
Jak widać w widoku wyświetlana jest uzyskana liczba rekordów. W zaleŜności od parametru
‘tag_label’ przyjmujemy róŜna notyfikację HTML. Oczywiście drugi plik widoku wygląda w sposób
analogiczny.
Dzięki temu udało nam się stworzyć moduł, który w zaleŜności od konfiguracji spełniać moŜe róŜne
funkcje w portalu. Tworząc dwie instancje tego modułu uzyskujemy dwa okienka (jedno wyświetla nam
liczbę artykułów w systemie, drugie liczbę aktywnych uŜytkowników). Dodatkowo w zaleŜności od
działania aplikacji moŜe być wyświetlany róŜny widok modułu. MoŜemy sobie w ten sposób, na przykład, zdefiniować ekran błędu i wywołać go jeśli aplikacja zadziała nie prawidłowo.
1.9. Moduły – pakiety językowe
Bardzo waŜnym elementem instalacji Joomla! są pakiety językowe. Za ich pomocą jesteśmy w stanie
zmieniać język strony bez konieczności zmiany struktury kodu aplikacji. Takie rozwiązanie daje nam
moŜliwość lokalizacji czy teŜ inaczej internacjonalizacji aplikacji. Zasada postępowania jest dosyć
prosa, naleŜy stworzyć pakiet językowy, w tym przypadku jest to zestaw słów i zwrotów uŜywanych w
naszym module. Plik językowy (dla kaŜdego języka musimy stworzyć odrębny plik) jest umieszczany
w odpowiednim miejscu systemu a aplikacja odwołuje się do jego elementów w zaleŜności od tego jaki
język jest ustawiony w witrynie. Jak to sie dzieje w szczegółach zostanie przedstawione poniŜej.
PoniŜszy listing przedstawia pakiet językowy dla naszego modułu. Zasada budowy jest bardzo prosta,
kaŜda linia ma charakter „etykieta = wartość”. Pierwszy wyraz, to etykieta, której wartość jest reprezentowana w systemie za pomocą zdefiniowanej dla danego języka wartości. Dla kolejnych języków
tworzymy identyczne pliki z etykietami, do których przypisujemy wartości odpowiednie w danym języku. Istotną kwestią jest to, Ŝeby plik językowy był kodowany za pomocą UTF-8, inaczej moŜemy mieć
problemy z wyświetlaniem znaków regionalnych (takich jak polskie litery).
# $Id: $
# TabInfo module language package
# Note : All ini files need to be saved as UTF-8 - No BOM
TT=Table:
PARAMTABDESC=Select table
ARTICLES=Articles
USERS=Users
TL=Style:
PARAMLABELDESC=Select style
NORMAL=Normal
BOLD=Bold
ITALIC=Italic
UNDERLINE=Underline
PoniŜej został przedstawiony fragment pliku konfiguracyjnego mod_tabinfo.xml naszego modułu w
którym odwołujemy się do etykiet.
<param name="tag_label" type="list" default="0" label="TL" description="PARAMLABELDESC">
<option value="N">NORMAL</option>
<option value="B">BOLD</option>
<option value="I">ITALIC</option>
<option value="U">UNDERLINE</option>
</param>
W panelu administracyjnym naszego modułu dla powyŜej zdefiniowanego parametru zamiast etykiety
„TL” wyświetli nam się wartość „Style:” (oczywiście jeśli językiem strony administracyjnej będzie język
angielski). JeŜeli stworzymy inny pakiet językowy, np. polski i w panelu administracyjnym wybierzemy
język polski to dla tej etykiety wyświetli nam się opis „Styl czcionki:” – na przykład.
Do etykiet moŜemy równieŜ odwoływać się równieŜ w kodzie modułu, tak jak zostało to przedstawione
poniŜej. Dzięki czemu nie tylko „Back-end” ale równieŜ „Front-end” naszego modułu moŜe być wyświetlany w danym języku.
echo JText::_( 'UNDERLINE' );
Ostatnią kwestią do omówienia jest sposób instalacji modułów wraz za pakietem językowym. Fragment skryptu instalacyjnego został przedstawiony poniŜej:
<languages folder="language">
<language tag="pl-PL">pl-PL.mod_tabinfo.ini</language>
<language tag="en-GB">en-GB.mod_tabinfo.ini</language>
</languages>
Oczywiście pakiety językowe moŜna instalować oddzielnie, ale to nie jest tematem tego wywodu. Pełną wersję modułu z pakietem językowym moŜna pobrać ze strony.