--=REKLAMA=--

J3.2

Tworzenie prostego modułu/Tworzenie prostego modułu

Z Joomla!WikiPL

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.

Struktura plikó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.

Tworzenie mod_helloworld.php

Plik mod_helloworld.php będzie odpowiedzialny za trzy zadania:

  • dołączenia pliku helper.php zawierającego klasę używaną do pobierania niezbędnych danych
  • wywołanie odpowiedniej metody klasy pomocniczej do pobierania danych
  • dołączenia szablonu wyświetlanego na wyjściu modułu.

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 );

Ukończony plik mod_helloworld.php

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.

Tworzenie helper.php

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.

Tworzenie tmpl/default.php

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.

Tworzenie mod_helloworld.xml

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.

Podsumowanie

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.

© Ten materiał jest dokładnym albo swobodnym tłumaczeniem artykułu http://docs.joomla.org/J3.2:Creating_a_simple_module udostępnionego na licencji JEDL na witrynie: Oficjalnej dokumentacji Joomla!.Pierwszy autor oryginału: Wilsonge.
© Tłumaczenie: Robertm. Tłumaczenie wykonano na warunkach licencji JEDL.