Joomla@jogger.pl

Własne style modułów

Pewne fragmenty kodu w szablonie powtarzają się dość często - pomiędzy kodem tworzącym układ szablonu a kodem generowanym przez moduł z reguły znajduje się jeszcze dodatkowa otoczka w postaci dodatkowych kontenerów. Używane są do różnych celów - do prezentacji tytułu modułu, do stworzenia zaokrąglonych rogów wokół modułu czy też otoczki znanej z trybu debugowania szablonu. Joomla! standardowo oferuje sześć takich styli - ich spis wraz z dokładnym opisem i strukturą znajdziemy na tej stronie.

Czasem jednak potrzebujemy czegoś więcej - dodatkowych elementów lub zupełnie innej struktury niż ta oferowana standardowo. Oczywiście w Joomla! nie zapomniano o zapotrzebowaniu na takie rozwiązania - możemy stworzyć dowolną ilość własnych styli modułów, które spełnią nasze potrzeby.

Teoria

Zacznijmy może od tego jak określamy styl jaki ma być użyty dla danej pozycji modułów.

W kodzie szablonu tworząc nową pozycję modułów korzystamy z zapisu:

<jdoc:include type="modules" name="NAZWA_POZYCJI" style="STYL" />

To właśnie atrybut style w powyższym znaczniku odpowiada za przypisanie konkretnego stylu do danej pozycji modułów.

Przykładowo zapis:

<jdoc:include type="modules" name="topnav" style="xhtml" />

przypisze do pozycji z modułami o nazwie topnav styl xhtml.

Oczywiście należy tutaj pamiętać o jednej bardzo ważnej rzeczy - wspomniana "otoczka" zostanie dołączona do każdego modułu ODDZIELNIE. Innymi słowy - jeżeli będziemy mieli styl, który otacza moduły kontenerem z klasą "module" to w sytuacji gdy na jednej pozycji mamy 2 lub więcej modułów zostanie wygenerowany kod:

<div class="module">
    <!-- kod pierwszego modułu na danej pozycji -->
</div>
<div class="module">
    <!-- kod drugiego modułu -->
</div>

Zamiast:

<div class="module">
    <!-- kod pierwszego modułu na danej pozycji -->
    <!-- kod drugiego modułu -->
</div>

Dlatego raczej nie należy traktować styli modułów jako narzędzia do dodawania dodatkowego kodu dla konkretnych fragmentów layoutu, no chyba, że mamy pewność iż na danej pozycji będzie opublikowany tylko jeden moduł.

Powyższy problem oczywiście nie istnieje jeżeli korzystamy z osadzania modułów poprzez:

<jdoc:include type="module" name="NAZWA_MODUŁU" style="STYL" />

Najważniejsze to wiedzieć gdzie w ogóle umieścić kod odpowiadający za nasze style modułów - w tym wypadku jest to plik html/modules.php w katalogu głównym naszego szablonu (katalog html w szablonach odpowiada za przechowywanie wszelkich plików nadpisujących zainstalowane rozszerzenia).

Definicję nowego stylu tworzymy poprzez utworzenie funkcji o określonej deklaracji:

function modChrome_NAZWA( $module, &$params, &$attribs )

Funkcja taka nie zwraca żadnej wartości - od razu wyświetla kod modułu otoczony odpowiednimi kontenerami.

Pierwszy argument to obiekt modułu, który będzie wyświetlony, drugi argument przechowuje odwołanie do konfiguracji naszego modułu (obiekt klasy JParameter) a trzeci argument jest ściśle powiązany ze zmienną $options z poprzedniego wpisu, ale o tym za chwilę.

Obiekt modułu przechowuje kilka ważnych z punktu widzenia stylu modułu informacji, z których trzy będą dla nas kluczowe:

• $module->title zawiera tytuł modułu.
• $module->content zawiera zawartość modułu
• $module->showtitle zawiera informację o tym czy wyświetlać tytuł modułu

Klasa JParameter posiada metodę get, która zwraca nam wartość parametru o danej nazwie. Na przykład:

$params->get('test', 0);

Zwróci nam wartość parametru "test", a jeżeli on nie istnieje to zostanie zwrócona domyślna wartość podana jako drugi parametr - 0.

Jeżeli zaś chodzi o tablicę $attribs to ma ona postać taką jak podawaliśmy jako wartość tablicy $options w wpisie lub stanowi ona tablice dodatkowych atrybutów znacznika jdoc:include. Daje to nam szerokie pole do popisu gdyż możemy utworzyć znacznik o następującej postaci:

<jdoc:include type="module" name="NAZWA_MODUŁU" style="STYL" textColor="#000" backgroundColor="#fff" />

W powyższym wypadku tablica $attribs przyjmie postać:

Array ( 
    [name] => NAZWA_MODUŁU 
    [style] => STYL 
    [textColor] => #000
    [backgroundColor] => #fff 
)

Jak więc widać możemy tworzyć w pełni konfigurowalne style modułów, dzięki czemu nie trzeba tworzyć kilku odmian tego samego stylu - wystarczy podać odpowiednie parametry.

Tworzymy własny styl modułu

Stworzymy prosty styl modułu, który będzie posiadał następujące cechy:

• nagłówek modułu będzie posiadał dodatkowy element pozwalający na uzyskanie zaokrąglonych rogów nagłówka.
• nasz styl będzie uwzględniać opcję sufiksu dla modułu udostępnianą przez zdecydowaną większość modułów dla Joomla!
• dzięki dodatkowym atrybutom będzie można określić id dla głównego kontenera modułu

Nasz styl nazwiemy "simple".

Poniżej pełny kod naszego stylu wraz z opisem.

function modChrome_simple($module, &$params, &$attribs)
{
        // Sprawdzamy czy zdefiniowano atrybut 'id' - jeżeli tak
        // to generujemy kod atrybutu z jego wartością
        $id = (isset($attribs['id'])) ? ' id="'.$attribs['id'].'"' : '';
        
        // Pobieramy wartość parametru sufiksu modułu
        $suffix = $params->get('moduleclass_sfx');
        
        // Zaczynamy generowanie kodu otaczajączego moduł
        // od głównego kontenera
        echo '<div class="module'.$suffix.'"'.$id.'>';
        
        // sprawdzamy czy włączono pokazywanie tytułu modułu
        if ($module->showtitle != 0)
        {
                // wyświetlamy tytuł
                echo '<h3><span>'.$module->title.'</span></h3>'; 
        }

        // generujemy treść modułu otoczoną kontenerem
        echo '<div class="module_content">';
        echo $module->content;
        echo '</div>';

        // domykamy główny kontener
        echo '</div>';
}

Jak widać do pobrania wartości opcji konfiguracyjnej określającej sufiks modułu wystarczy następujący kod:

$params->get('moduleclass_sfx')

Sufiksy są niezwykle przydatne, gdyż na bazie jednego układu/stylu modułów, możemy określić dowolną liczbę stylowań np. dla klas:

• module_menu
• module_text
• module_small

itd.

Sprawdzanie czy pokazywanie tytułu jest włączone to wręcz obowiązkowa pozycja każdego stylu modułów wykorzystującego pokazywanie tytułu modułu.

Samą treść otaczamy oczywiście w jeszcze jeden kontener "module_content" by ułatwić oddzielenie jej od tytułu modułu.

Zapis:

<jdoc:include type="modules" name="header" style="simple" id="test" />

Spowoduje otoczenie modułów z pozycji "header" kontenerem z id "test" (i oczywiście pozostałym kodem naszego stylu).

Inne ciekawe możliwości

Warto pamiętać, że kod zaprezentowany w tym wpisie to tylko wierzchołek góry lodowej możliwości jakie oferuje nam nadpisywanie styli modułów - dzięki nadpisywaniu możemy uzyskać naprawdę mnóstwo efektów - zwijane bloki modułów, zaawansowane stylowanie nagłówków modułów czy odpowiednie filtrowanie zawartości modułu zawartej w $module->content.

W wypadku bardziej wyszukanych potrzeb warto zastanowić się nad wykorzystaniem dodatkowej klasy i szablonów w celu zwiększenia czytelności kodu. Taką klasę po prostu dołączamy do pliku modules.php

Warto przejrzeć kody źródłowe różnych szablonów by zobaczyć jak ich autorzy wykorzystali możliwość definiowania własnych styli modułów - może to być źródłem wielu ciekawych rozwiązań, które często nie tylko poszerzają możliwości szablonu, ale po prostu ułatwiają jego tworzenie i późniejsze utrzymanie.