Co to jest parametr modułu

Moduły w joomli to wg mnie jedna z najprzyjemniejszych rzeczy z punktu widzenia programisty. Wystarczy napisać 2 pliki, by można było zainstalować a następnie użyć jakiś kawałek kodu. Dzisiaj po krótce opiszę jak bardzo szybko dodać do istniejącego już modułu (zainstalowanego nawet) jakiś dodatkowy parametr.

Ale co to jest w ogóle parametr? Joomla w panelu admina w ustawieniach modułu po prawej stronie wyświetla zwykle krótszą lub dłuższą listę dodatkowych ustawień, z jakich możemy skorzystać przystosowując moduł do naszych potrzeb. Na przykład moduł “mod_mainmenu” wykorzystywany do renderowania Menu na stronie posiada ich całkiem sporo:

Jak widać parametry owe są pogrupowane w trzy grupy. Możemy w ten sposób indywidualnie dostosować do naszych potrzeb każdą kopię modułu “mod_mainmenu” wykorzystywaną w portalu.

Ale skąd moduł wie, jakie parametry są dostępne dla danego modułu?

Jest to bardzo proste. Zerknijmy do katalogu modules w naszej instalacji joomla. Jest w nim napewno katalog mod_mainmenu a w nim:

• katalog [tmpl]
• helper.php
• index.html
• legacy.php
• mod_mainmenu.php
• mod_mainmenu.xml

Nie będziemy się teraz zajmować budową modułu oraz pisaniem go. To znajdzie się w innych artykułach. Dzisiaj zajmujemy się tylko parametrami, a te znajdują się… w pliku mod_mainmenu.xml.

Jest to plik instalacyjny modułu, w którym znajduje się para znaczników:

 

<install type="module" version="1.5.0">

</install>

gdzieś na końcu znajdują się 3 grupy parametrów (<params></params>), a w każdej z nich lista parametrów.

Każdy parametr to znacznik xml <param> z parametrami (parametrami znacznika)

• name – z tej nazwy korzystamy pobierając potem w module wartość parametru
• type – definiujemy typ pola.
  • text – pole tekstowe jednolinijkowe
  • textarea – pole tekstowe wielolinijkowe
• default – wartość wpisywana w pole domyślnie
• label – etykieta widoczna obok pola
• description – dłuższy opis wyświetlający się po najechaniu myszką na pole

dodatkowo można skorzystać z 

• rows – ilość wierszy w przypadku textarea
• cols – ilość kolum (praktycznie – szerokość pola)

Aby stworzyć w ten sposób parametr który będzie przechowywał tytuł piszemy:

<param name="title" type="text" default="" 
label="Tytuł" description="Tytuł który będzie wyświetlany w module"/>

Możemy także stworzyć pole specjalne:

• <param name=”indent_image1″ type=”imagelist” directory=”/images/M_images” default=”” label=”Indent Image 1″ description=”Image for the first sub-level” /> – lista obrazków z katalogu
• <param name=”@spacer” type=”spacer” default=”” label=”” description=”” /> – linia pozioma

Listy wyboru:

<param name="indent_image" type="list" default="0" label="Indent Image"
description="Choose which indent image system to utilise">
			<option value="0">Template</option>
			<option value="1">Joomla! default images</option>
			<option value="2">Use params below</option>
			<option value="3">None</option>
</param>

Oraz liste opcji (radiobuttons):

<param name="full_active_id" type="radio" default="0" 
label="Full Active highlighting" description="PARAMFULLACTIVEHIGHLIGHTING">

			<option value="0">No</option>
			<option value="1">Yes</option>
</param>

W ten sposób definiujemy listę parametrów dla modułu. 

A jak tego użyć?

Równie prosto. W pliku z kodem modułu, czyli mod_nazwamodułu.php, o raz w plikach includowanych wystarczy że skorzystamy z obiektu $params zawierającego wszystkie parametry, które zostały ustawione dla naszego modułu:

echo $params->get('desc', 'Brak');

jako pierwszy parametr metody get() podajemy nazwę parametru który chcemy pobrać. Jako drugą podajemy wartość jaka ma zostać zwrócona w przypadku niepowodzenia, lub też pustego wyniku. I już. 

W ten sposób możemy bardzo łatwo dodać dodatkowy parametr na przykład do modułu mainmenu (problemem może się okazać sama budowa modułu mainmenu, która na początku moze się wydawać lekko zamotana). 

Pozdrawiam, Maciej

Kiedy skrypt napotyka żądanie wyrenderowania jakiegoś modułu, wtedy za pomocą klasy JModuleHelper pobierana jest zawartość pliku modules/mod_nazwamodulu/mod_nazwamodulu.php – to tak w uproszczeniu, bo jeszcze w zależności od templatki moduł może być ubierany w jakieś divy albo tabelkę. A więc do programisty teoretycznie należy napisanie pliku mod_nazwamodulu.php. Praktycznie – też tak jest. Należy jednak pamiętać o pewnych “trendach” jakich powinno się trzymać pisząc moduły. Przez kilka następnych artykułów będziemy uczyć się właśnie tych trendów. Będziemy też powoli przyswajać budowę samej Joomli. Nie będziemy natomiast uczyć się PHP. To mam nadzieję już w jakimś stopniu jest opanowane

Po pierwsze – Plan

Musimy się najpierw zastanowić co chcemy zrobić i jakoś to rozplanować. Nasz moduł nie będzie zbyt skomplikowany. Jego działanie polegać będzie na wypisaniu na ekran “Hello world”. Całość więc zakodujemy po prostu w pliku mod_hello.php – ponieważ tak będzie nazywał się nasz komponent – mod_hello.

mod_hello

zobaczmy na poniższy kod

<?php
/**
 * Moduł mod_helloworld - stworzony na potrzeby www.morony.pl
 * autor Maciej Mucha, maciej@morony.pl
 */

defined('_JEXEC') or die('Direct Access to this
		 location is not allowed.');

echo 'Hello World!';

Jest to zwykły plik php. Wyjaśnienia wymaga linia sprawdzająca istnienie stałej ‘_JEXEC’. Jest to stała zdefiniowana w pliku index.php. Joomla cała opiera się właśnie na tym pliku. tzn wszystkie adresy naszej strony to index.php?… Nie ma więc potrzeby otwierania bezpośrednio jakiegokolwiek innego pliku (może to być nawet niebezpieczne). Sprawdzamy więc czy plik został wczytany za pomocą pliku index.php. Jeśli nie – wtedy blokujemy dostęp. tą klauzulę możemy znaleźć prakrycznie w każdym pliku php wchodzącym w skład joomli.

Kiedy jesteśmy już pewni że strona została wczytana prawidłowo przechodzimy do właściwego kodu. W tym przypadku kod nie wymaga chyba tłumaczenia 🙂

Skrypt się skończył.. A gdzie tag zamykający skrypt php? Nie jest on wymagany. A ponieważ plik który napisalismy ma być ładowany do innego pliku, wszelkie spacje czy inne białe znaki były by bardzo niepożądane, A takie zostały by wczytane gdyby wystąpiły po “?>”. Jest to praktyka przyjęta w Joomla 1.5, i będziemy ją stosować za każdym razem.

Pięknie – skrypt napisany. Ale co z tego? jak go teraz wgrać aby był dostępny z poziomu panelu administracyjnego? W Joomli służą do tego pliki instalacyjne XML.

Plik instalacyjny

nasz plik instalacyjny będzie wyglądał tak:

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
	<name>Hello World</name>
	<author>Maciej Mucha - www.morony.pl</author>
	<creationDate>December 2008</creationDate>
	<copyright>Maciej Mucha - www.morony.pl</copyright>
	<license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL
              </license>
	<authorEmail>maciej@morony.pl</authorEmail>
	<authorUrl>http://www.morony.pl</authorUrl>
	<version>1.5.0</version>
	<description>Moduł służący do wyświetlenia 
               informacji "Hellow World"</description>

	<files>
		<filename module="mod_hello">mod_hello.php</filename>
		<filename module="mod_hello">index.html</filename>
	</files>
</install>

O co tu chodzi? To proste, najpierw podajemy kilka informacji o sobie i o skrypcie które będą widoczne w panelu admina, oraz listę plików, które instalator przekopiuje na dysk.

Co jest ważne:

• <install type=”module” version=”1.5.0″> – informacja o tym że instalujemy moduł, kompatybilny z joomlą 1.5.x i wyższe
• <name>Hello World</name> – nazwa modułu wyswietlana w panelu administracyjnym
• <filename module=”mod_hello”>mod_hello.php</filename> – parametr module=”mod_hello” zostanie przyjęty jako nasza nazwa modułu oraz katalog w kórym będzie dostępny moduł. Nie mylić z przyjazną nazwą wyświetlaną.
• <?xml version=”1.0″ encoding=”utf-8″?> – ważne jest aby plik został zakodowany w kodowaniu które zadeklarowaliśmy. W przeciwnym wypadku instalator wurzuci błąd.
• <filename module=”mod_hello”>index.html</filename> – w dobrym tonie jest, aby w każdym katalogu joomli znajdował się plik index.html o treści”<html><body bgcolor=”#ffffff”></body></html>

Instalujemy!

Aby móc przystąpić do instalacji musimy jeszcze spakować pliki (razem z plikiem instalacyjnym, który zapisujemy jao mod_hello.xml). Najlepiej do pliku mod_hello.zip. Następnie instalujemy komponent. 

1. Wybieramy instalator

2. Wybieramy plik i klikamy instaluj

3. Cieszymy się z zainstalowanego modułu.

Uruchamiamy moduł

1. Wybieramy moduły z menu

2. Tworzymy nowy moduł

3. Z listy wybieramy nasz moduł

4. Ustawiamy parametry wyświetlania modułu

5. Jeśli wszystko zrobiliśmy dobrze, powinniśmy zobaczyć coś takiego – działający moduł

Poprawki

To że moduł nam się zainstalował, nie znaczy jeszcze że będzie działał. Może się okazać, ze popełniliśmy jakiegoś babola i nasz moduł wywala błąd php. Nie musimy wtedy powtarzać całej procedury od początku. Wystarczy, że podmienimy odpowiedni moduł na serwerze i już (no i oczywiście potem w paczce z modułem, kiedy już będzie działał. 

Podsumowanie

Jak widać napisanie prostego modułu dla Joomli nie jest czymś szczególnie trudnym (choć nasz moduł nie robił za wiele). W następnych artykułach dowiemy się już jak napisać coś pożytecznego.

Pozdrawiam,

Much

Kiedy Piszę jakiś komponent albo moduł dla joomli są pewne partie kodu, które się często powtarzają. Postanowiłem je zebrać w jedno miejsce.

Blokowanie bezpośredniego dostępu do plików:

defined('_JEXEC') or die('Restricted access');

W pliku index.php zdefiniowana została stała _JEXEC – sprawdzamy czy ona istnieje, a więc czy uzytkownik załadował plik index.php

Blokowanie dostępu do treści niezalogowanym użytkownikom

$user =& JFactory::getUser();
if($user->guest){
	// kod dla niezalogowanego
} else {
	// kod dla zalogowanego
}

Do zmiennej $user zostaje załadowany objekt (klasy JUser) przechowujący dane a temat zalogowanego uzytkownika. Pole guest przechowuje informacje o tym czy uzytkownik jest zalogowany (boolean)

Informacje o zalogowanym użytkowniku

$user =& JFactory::getUser();
	$name = $user->name; // Imię
	$username = $user->username; // Nick
	$email = $user->email; // e-mail
	$id = $user->id; // unikalne ID
	$lastVisit=$user->lastvisitDate; // Data ostatniej wizyty
	$registerDate=$user->registerDate; // Data rejestracji
	$guest=$user->guest; // Czy gość (boolean)

Tworzenie zmiennej do wykorzystania w templatce przy wykorzystaniu modelu MVC

$zmienna='cokolwiek';
$this->AssignRef('zmienna' $zmienna);

Wykorzystanie zmiennej w templatce przy wykorzystaniu modelu MVC

<b><?php echo $this->zmienna; ?></b>

Pobranie wartości z pliku językowego

JText :: _('PLEASE LOG IN');

W odpowiednim pliku językowym zostanie znaleziona poniższa linia oraz pobrana będzie jej wartość. Jest to plik ini

PLEASE LOG IN=Proszę, zaloguj się.

Kolejne pomocne partie kodu będę dopisywł systematycznie.

Pozdrawiam,

Much