--=REKLAMA=--
Napisał Andrew Eddie, tłum. Stefan Wajda
Artykuł opublikował na blogu programistów Andrew Eddie, na wiki skopiował, nanosząc niewielką poprawkę Alan Langford. Tytuł oryginału: Understanding Output Overrides in "Joomla!" 1.5.
Projekty dla Internetu stają wobec wielu wymagań - od standardów dostępności po preferencje indywidualne. Nie próbując różnicować ich rangi, nie faworyzując żadnego z podejść, nie chowając głowy w piasek, Joomla! daje projektantom moc, siłę, możliwości, by przejąć pełną kontrolę nad wszystkimi aspektami wizualnymi witryn.
Od pewnego czasu Joomla! był krytykowany za niedostateczne przywiązywanie wagi do standardów dostępności i przestarzałe podejście do standardów sieciowych. Wraz z Joomla! 1.5 odpowiedzialność za tę stronę witryn, ale co więcej – pełna kontrola nad wizualnym aspektem wraca w ręce projektantów. Ponadto, z wyjątkiem plików składających się na pakiet instalacyjny Joomla!, metody dostosowania eliminują potrzebę stosowania przez projektantów sztuczek (haków), modyfikacji rdzennych plików Joomla!, które łatwo zastąpić podczas aktualizacji do nowszej wersji. Ponieważ pliki te umieszczane są w szablonie witryny, mogą one być zaprojektowanie przez autora szablonu bez obawy, że zostaną przypadkowo nadpisane przez administratora podczas aktualizacji. Celem tego poradnika jest wyjaśnienie, w jakich obszarach „wyjściowych” Joomla! może być dostosowywany przez projektanta szablonu. Nie jesteś zainteresowany żadną teorią? Przejdź od razu do części Oszukaj arkusz.
MVC to akronim angielskiego Model-View-Controller, co na język polski tłumaczy się jako Model-Widok-Kontroler, a najogólniej rzecz biorąc, odpowiada za ekstra elastyczność, którą otrzymali w swoje ręce projektanci witryn. Pewne części teorii niepotrzebne projektantom i skomplikowane, możemy pominąć, z wyjątkiem oznaczonej przez V – Widok. To część, która koncentruje się interfejsie użytkownika.
Składniki Joomla! prezentują przetworzone dane wyjściowe w różny sposób.
Komponenty, jak już wiesz, są dość złożone i potrafią pokazywać informację na kilka sposobów. Na przykład komponent Artykuły (com_content) potrafi wyświetlać pojedynczy artykuł albo artykuły w kategorii albo kategorie artykułów w sekcji. Każdy z tych sposobów reprezentujący odmienny typ danych (artykuł albo kategoria, albo sekcja) nazywamy widokiem (określenie pochodzi z terminologii MCV). Komponenty najczęściej będą miały wiele widoków. Jednakże „widok” nie pokazuje przetworzonych danych wyjściowych. To zadanie jest pozostawione szablonom (layouts), i możliwe jest, że widok będzie prezentowany przez rozmaite szablony. Najważniejszą rzeczą do zapamiętania jest tutaj, że komponenty mogą mieć wiele widoków i że każdy widok może być zaprezentowany za pomocą jednego lub większej ilości szablonów.
Każdy widok składa się z ustalonego zestawu informacji, każdy szablon może te informacje przedstawić w inny sposób. Na przykład widok kategorii w komponencie Artykuły składa się z kilku artykułów. Wykaz tych artykułów można pokazać za pomocą listy albo w tabeli (i na pewno inaczej również). Zatem ten widok może mieć szablon „list”, szablon „table”.
Z drugiej strony moduły są bardzo proste. One pokazują jedną rzecz w jeden sposób. Nie Muszą mieć widoków (nie są im potrzebne), ale obsługują szablony. Projektanci mogą nawet zapewnić obsługę wyboru szablonu za pomocą parametrów modułu.
Jest bardzo ważne, aby rozróżniać rolę szablonu witryny czy zaplecza oraz szablonów. W języku angielskim to rozróżnienie jest łatwiejsze, bo szablony witryny czy zaplecza nazywa się terminem template, a w drugim przypadku używa się terminu layouts. W języku polskim słowo layout tłumaczy się najczęściej jako układ, rozmieszczenie, rozplanowanie lub format, rzadziej wygląd czy wystrój.
Szablon witryny [template] lub zaplecza administracyjnego ustala strukturę strony internetowej, jest jej zrębem, szkieletem projektowym, frameworkiem. W tej strukturze wyznaczone są miejsca dla treści głównej (komponentu) i treści towarzyszących (modułów). To, co wyświetlane jest na stronie, jest wynikiem szablonu witryny oraz szablonu modułu albo kombinacją widoku i szablonu w przypadku komponentu. Gdyby użyć słowa format, to zdanie brzmiałoby przystępniej, acz niekoniecznie jaśniej: To, co wyświetlane jest na stronie, jest wynikiem szablonu witryny oraz formatu modułu albo kombinacją widoku i formatu w przypadku komponentu.
To objaśnienie niewiele nam jeszcze mówi, ale uzmysławia zapewne, że szablon witryny oraz szablon modułu czy komponentu to nie to samo, choć jedno i drugie odnosi się do formy prezentacji.
Słowem szablony [layouts] nazywamy ramowy sposób prezentacji modułu lub komponentu, ustalony w kodzie Joomla!, na który składa się pewien typowy element HTML obejmujący treść oraz standardowy układ treści, opisany znacznikami HTML.
Na ilustracji poniżej przedstawiono strukturę układu w typowym szablonie Joomla! (rhuk_milkyway, domyślnym w 1.5). Pozycje modułów możemy wyświetlić po dodaniu w adresie witryny parametru tp=1 (np. www.moja_domena.com/index.php?tp=1). Wyraźnie widać na ilustracji, gdzie w szablonie wyświetlany jest efekt wywołania modułów, a gdzie prezentowana jest treść główna. To natomiast, w jaki sposób zostały zaprezentowane treści każdego modułu oraz treść główna, to jak zostały rozmieszczone w zajmowanym przez siebie obszarze, pominąwszy wystrój specyficzny dla szablonu rhuk_milkyway, kontrolowane jest przez szablony – nie szablon witryny, ale przez szablony modułów i komponentu w przypadku treści głównej. Podkreślmy wyraźnie, że chodzi tutaj jedynie o wszystkie niespecyficzne dla szablonu rhuk_milkyway aspekty wyglądu. Gdybyśmy zastosowali inny szablon witryny, zmianie uległaby być może kolorystyka, krój czcionki, rozmiary i rozmieszczenie poszczególnych elementów na stronie, ale w wyglądzie modułów i treści głównej można by wskazać dokładnie takie same właściwości, np. punktowane listy w modułach, formularz głosowania w module Sondy, tytuł strony, tytuł artykułu, nazwę autora, datę i czas publikacji, przyciski PDF, Drukuj, i Email. To są właśnie cechy kontrolowane przez szablony, a nie przez szablon witryny.
(Ancillary Customisation)
Nie mają ścisłego związku z MCV dwa inne ważne aspekty wyglądu wymagające rozważenia, kiedy rozpatrujemy możliwości dostosowania kodu wynikowego (wyjściowego) Joomla!.
Obszar pierwszy związany jest z modułami. Poza szablonami komponentów, moduły zostały wyposażone w coś, co nazwaliśmy ramką albo profilem, stylem, po angielsku chrome. Jest to sposób, styl prezentacji modułu. Większość projektantów i prawdopodobnie wielu użytkowników jest obeznanych z różnymi wbudowanymi stylami modułów ((raw, xhtml, etc.; mieliśmy z nimi już do czynienia w szablonach dla Joomla! 1.0). W Joomla! 1.5 projektanci mogą definiować własne style ramek dla modułów. Na przykład można zaprojektować ramkę wyświetlającą wszystkie moduły w jakiejś pozycji z aranżacją zwijania i rozświetlania wykorzystującą Javascript. Na zrzucie ekranu powyżej można zobaczyć nazwy niektórych wbudowanych ramek (rounded, none oaz xhtml).
Obszar drugi związany jest z kontrolowaniem paginacji stron, gdy przeglądamy listy danych. Przyjrzymy mu się później.
Aby zrozumieć koncepcję przesłaniania szablonów (a. podmiany szablonów), musimy najpierw zrozumieć strukturę plików komponentu. We wszystkich spełniających różne role i zadania komponentach wieloczęściowych zobaczymy katalog /views/. Poniżej przedstawiamy fragment struktury katalogu komponentu com_content (Artykuły):
/components /com_content /views /articles /tmpl default.php (plik szablonu) form.php (plik szablonu) view.html.php (zawiera kod wynikowy HTML) view.pdf.php (zawiera kod wynikowy PDF) /category /tmpl blog.php (plik szablonu) blog_items.php (pod-szablon) default.php (plik szablonu) view.html.php (widok HTML) view.feed.php (widok kanału RSS)
Jak widać powyżej, każdy widok ma swój własny podkatalog w katalogu /views/. Komponent Artykuły aktualnie ma jeszcze trzy różne inne niepokazane tu widoki archive, frontpage oraz section.
Wewnątrz katalogu, jak np. katalogu /articles/ mamy kilka plików. Prawie zawsze jest wśród nich plik nazwany view.html.php. To – zgodnie z nazwą – plik zawierający wynikowy kod HTML widoku. Takich plików, jak view.html.php, może być więcej. Zależy to od formatu danych, jakie mają być wynikiem. Pliki nazywane są zgodnie z pewną specyficzną konwencją: view.typ_wyjscia.php, gdzie typ_wyjscia to np. html, rss, pdf, raw (nieprzetworzony) bądź error (więcej informacji zobacz JDocument w zasobach API, a także przejrzyj katalog /libraries/joomla/document/). Tym sposobem, jeśli chcemy otrzymać kod html, używamy pliku view.html.php. Jeśli efektem ma być kanał RSS, używany jest plik view.feed.php.
Wynik tych różnych typów formatu wyjściowego staną się bardziej oczywiste, kiedy w konfiguracji globalnej witryny zoptymalizujemy witrynę pod kątem wyszukiwarek, ustawiając wszystkie opcje odnoszące się do prostych adresów ustawimy na Tak, a więc Proste adresy, Korzystaj z mod_rewrite oraz Adresy z przyrostkiem. Efektem takiego ustawienia będą adresy jak poniżej:
http://domaena/sporty.html http://domena/sporty.feed http://domena/sporty/wioslarstwo.html http://domena/sporty/wioslarstwo.pdf
Dokładny adres jest uzależniony od ustawień witryny, ale istotę można zaobserwować w widocznych tutaj "rozszerzeniach" nazw plików. Do wygenerowania strony sporty.html, prezentującej kategorie użyty zostanie plik view.html.php, do wygenerowania strony sporty.feed prezentującej kategorie kanałów informacyjnych zostanie użyty plik view.feed.php. To zrozumiałe (oczywiste), że nie możemy aktualnie dostosowywać do swoich potrzeb dokumentów wynikowych pdf czy kanałów informacyjnych. Natomiast możliwe jest dostosowywanie kodu wynikowego html. I to jest właśnie miejsce, w którym do gry wchodzą szablony.
W katalogu /view jest katalog /tmpl/ z plikami szablonów. Każdy umieszczony tu plik reprezentuje szablon. Na przykład article/tmpl/default.php jest domyślnym szablonem artykułu, a article/tmpl/form.php jest szablonem formularza redakcyjnego, category/tmpl/default.php jest domyślnym szablonem strony prezentującej kategorie artykułów, a category/tmpl/blog.php szablonem przeglądu artykułów w kategorii.
Relację między widokami komponentu a szablonem zobaczymy najwyraźniej, dodając pozycje menu. Kolejny zrzut ekranu wyświetla stronę nowych pozycji menu. Gdy klikniemy na Artykuły (które prezentuje com_content), drzewo rozwinie się, by pokazać listę widoków i wewnątrz widoku wszystkich szablonów.
Zapewne zauważysz, że w katalogu /tmpl są jeszcze dodatkowe pliki (jak pagebreak.php w widoku artykułu), których nie ma na liście szablonów. Są one wymagane w plikach instrukcji XML (np. pagebreak.xml) aby ukryć (odróżnić) szablon (albo nawet widok) od pozycji menu. Ale to jest inny obszerny temat, który zostanie omówiony w innym poradniku.
Uzbrojeni w tę wiedzę o związkach poszczególnych części, jesteśmy gotowi, by stworzyć swój zamiennik szablonu [create our layout overrides.].
Zamienniki szablonu działają tylko w aktywnym szablonie witryny i są umieszczane w katalogu /html/ szablonu witryny. Na przykład, w przypadku szablonu rhuk_milkyway zamienniki są umieszczone w katalogu /templates/rhuk_milkyway/html/, w przypadku JA Purity w katalogu /templates/ja_purity/html/, a w przypadku Beez w katalogu /templates/beez/html/.
To jest ważne, aby rozumieć, że jeśli tworzysz zamienniki w jednym szablonie witryny, to w innych szablonach nie będą one dostępne. Przykładowo, do szablonu rhuk_milkyway nie dołączono żadnych plików zamieniających szablony komponentu. Jeśli korzystasz z tego szablonu, wszystkie komponenty widzisz w surowym, standardowym kształcie, stylizowane jedynie przez szablon witryny. Jeśli natomiast korzystasz z szablonu Beez, to przeciwnie – wygląd większości komponentów kontrolowany jest przez zamienniki standardowych szablonów. Z kolei w szablonie JA Purity mamy podmieniony jeden szablon komponentu i dwa modułów.
Zamiennik szablonu musi być umieszczony w szczególny sposób. Jeśli weźmiemy za przykład szablon Beez, zobaczymy następującą strukturę:
/templates /beez /html /com_content (nazwa katalogu dostosowywana jest do nazwy komponentu) /articles (nazwa katalogu dostosowana jest do nazwy widoku) default.php (nazwa pliku dostosowana jest do nazwy układu) form.php
Struktura dla zamiennika komponentu jest całkiem prosta: /html/com_nazwa_komponentu/nazwa_widoku/nazwa_pliku_szablonu.php. Zobaczmy kilka przykładów
W szablonie rhuk_milkyway nie ma żadnych zamienników szablonów dla komponentów. Jeśli chcemy zastąpić domyślny szablon artykułu, najpierw musimy skopiować plik:
/components/com_content/views/article/tmpl/default.php
do tej lokalizacji, tworząc wcześniej odpowiednie katalogi, jeśli nie istnieją:
/templates/rhuk_milkyway/html/com_content/article/default.php
Jeśli chcemy zastąpić domyślny szablon przeglądu kategorii artykułów, musimy skopiować plik:
/components/com_content/views/category/tmpl/blog.php
do:
/templates/rhuk_milkyway/html/com_content/category/blog.php
Po skopiowaniu plików mamy pełną swobodę dostosowywania ich do swoich potrzeb i wymagań. Nie musimy honorować żadnych ustawień, jeśli nie chcemy.
W katalogach niektórych widokach zauważymy, że szablony składają się z grupy plików rozpoczynających się od takiej samej nazwy. Na przykład w katalogu z widokiem kategorii. Szablon przeglądu ma aktualnie trzy części: główny plik szablonu blog.php oraz dwa pliki pod-szablonów, blog_item.php i blog_links.php. Zobacz, gdzie te subszablony są wczytywane w pliku blog.php za pomocą metody loadTemplate, na przykład:
echo $this->loadTemplate('item'); // albo echo $this->loadTemplate('links');
Kiedy wczytujemy podszablony, widok "wie", jaki to szablon, nie jest więc potrzebny żaden prefiks (a więc wczytujesz tylko item, nie blog_item). Ważne, aby zauważyć, że niemożliwe jest nadpisanie subszablonu bez skopiowania całego kompletu plików. Na przykład, jeśli chcesz zastąpić domyślne wyjście dla szablonu przeglądu, ale chcesz dostosować tylko podszablon, możesz skopiować jedynie
/components/com_content/views/category/tmpl/blog_item.php
do
/templates/rhuk_milkyway/html/com_content/category/blog_item.php
Gdy Joomla! przetwarza widok, automatycznie wie, że ma wczytać własny (macierzysty, natywny) com_content oraz blog_item.php z katalogu Twojego szablonu.
Moduły, jak komponenty, umieszczone są w konkretnej strukturze katalogu:
/modules /mod_latest_news /tmpl default.php (the layout) helper.php (a helper file containing data logic) mod_latest_news.php (the main module file) mod_latest_news.xml (the installation XML file)
Podobnie jak w przypadku komponentów, w głównym katalogu (w przykładzie jest /mod_latest_news<//tt>) jest podkatalog <tt>/tmpl. Jest w nim zasadniczo tylko jeden plik szablonu, ale mogłoby się zdarzyć – zależnie od projektanta modułu – że byłoby ich więcej.
Jak w przypadku komponentów, tak i w przypadku modułów zamienniki szablonów muszą być umieszczone w szczególny (określony) sposób. Jeśli weźmiemy za przykład szablon Beez, zobaczymy następującą strukturę:
/templates /beez /html /mod_latest_news.php (nazwa katalogu dostosowana jest do nazwy każdego modułu) default.php (nazwa pliku dostosowana jest do nazwy szablonu)
Struktura dla zamienników szablonów modułów jest bardzo prosta:
/html/mod_nazwa_modułu/nazwa_pliku_szablonu.php.
W szablonie rhuk_milkyway nie ma żadnych zamienników ramek modułów. Jeśli chcemy zastąpić domyślny szablon modułu Nowości [Latest News], najpierw musimy skopiować plik:
/components/mod_latest_news/default.php
do tej lokalizacji, tworząc wcześniej odpowiednie katalogi, jeśli nie istnieją:
/templates/rhuk_milkyway/html/mod_latest_news/default.php
Do podmiany ramek modułów trzeba podchodzić z pewną uwagą (troską), ponieważ jest kilka różnych sposobów powodowania ... Każdy moduł trzeba traktować indywidualnie.
W Joomla 1.0 istniało kilka ustalonych stylów prezentacji modułów w określonej pozycji. Oznaczane były liczbami:
To był doskonały system z wyjątkiem dwóch rzeczy
W Joomla 1.5 liczby są nadal przetwarzane, ale częściej styl reprezentowany jest przez słowo. Zmieniona została również składnia polecenia umieszczającego moduły w pozycji. Na przykład poniższy fragment kodu umieszcza moduły w pozycji left w stylu xhtml:
<jdoc:include type="modules" name="left" style="xhtml" />
Wbudowane style są teraz dostępne pod nazwami:
W kodzie źródłowym do tych stylów odnosi się słowo „chrome”. Domyślny szablon można znaleźć w szablonie systemowym w domyślnej instalacji Joomla!:
/templates/system/html/modules.php
Jest to plik opracowany w ramach projektu, więc nie powinieneś nigdy go modyfikować bezpośrednio, bo ryzykujesz, że utracisz swoje zmiany podczas aktualizacji Joomla!.
Wszystko, czego potrzebujesz, aby stworzyć własną ramkę albo styl modułu, to stworzyć lub zmodyfikować plik modules.php w katalogu /html/ (tym samym katalogu, w którym przechowywane są zamienniki szablonów komponentów – to jest ten sam katalog, o którym mówiliśmy...)
W szablonie rhuk_milkyway mamy aktualnie jako przykład dodatkowy szablon modułu (dodaje nowy styl „slider” – suwak). Można go znaleźć w następującym (poniższym) pliku:
/templates/rhuk_milkyway/html/modules.php
Stworzenie własnej ramki jest naprawdę łatwe. Rozpatrzmy fikcyjny przykład, który wyświetla w module listę definicji (oznaczoną DL, DT i DD).
Dodaj następującą funkcję do pliku /html/modules.php w katalogu swojego szablonu (jeśli taki plik nie istnieje, stwórz go)
/* * Module chrome that wraps the module in a definition list */ function modChrome_dlist($module, &$params, &$attribs) { ?> <dl class="<?php echo $params->get('moduleclass_sfx'); ?>"> <?php if ($module->showtitle != 0) : ?> <dt> <?php echo $module->title; ?> </dt> <?php endif; ?> <dd> <?php echo $module->content; ?> </dd> </dl> <?php }
Nazwiemy styl "dlist", dlatego funkcja musi być nazwana modChrome_dlist.
Funkcja wymaga trzech zmiennych odwołujących się do obiektu modułu, parametrów modułu i atrybutów modułu. Są trzy istotne własności modułów, na których się skoncentrujemy:
To jest bardzo prosty przypadek. Można, oczywiście, projektować o wiele bardziej złożone style, możliwe jest również korzystanie z dowolnych atrybutów dodawanych w znaczniku XML.
Na koniec przyjrzyjmy się zamiennikowi szablonu paska paginacji. Ten zamiennik kontroluje wyświetlanie ilości pozycji na stronie oraz odnośniki paginacji – do kolejnych stron, jak widać na ilustracji poniżej.
Szablon rhuk_milkyway dostarcza dobrze skomentowanego przykładu tego zamiennika. Plik znajduje się tutaj:
/templates/rhuk_milkyway/html/pagination.php
Skrypt definiujący klasę JPagination{}, a w niej wymienione poniżej funkcje znajduje się w katalogu bibliotek:
/libraries/joomla/html/pagination.php
Gdy będzie potrzebne stronicowanie, Joomla! będzie szukać tego pliku w domyślnym szablonie witryny. Jeśli go znajdzie, to ten plik zostanie wczytany (załadowany) i zastosowane zostaną zawarte w nim funkcje wyświetlania. (Jeśli go nie znajdzie, zastosuje standardowy szablon zdefiniowany w klasie JPagination{}.)
Są cztery funkcje, które mogą zostać użyte:
pagination_list_footer
Ta funkcja generuje i wyświetla licznik stron - numer wybranej pozycji (strony) i ogólną liczbę na liście.
pagination_list_render
Ta funkcja generuje listę dostępnych pozycji - stron: poprzednich oznaczonych np. Start, Poprz. oraz cyframi, bieżącej i następnych oznaczonych cyframi i napisami Nast. i Ostatni.
pagination_item_active
Ta funkcja wyświetla odnośniki do wszystkich innych stron, poza aktualnie wybraną.
pagination_item_inactive
Ta funkcja wyświetla jako zwykły tekst numer aktualnie wybranej strony.
Poniżej jest krótkie podsumowanie podstawowych założeń, które rozpatrzyliśmy, na przykładzie szablonu rhuk_milkyway.
Aby podmienić standardowe szablony treści komponentu (na przykład domyślny szablon artykułu), skopiuj:
/components/com_content/views/article/tmpl/default.php
do:
/templates/rhuk_milkyway/html/com_content/article/default.php
Czytaj więcej o kodzie wynikowym komponentu.
Aby podmienić standardowy szablon modułu (np. modułu Nowości [Latest News], korzystając z szablonu rhuk_milkyway template), skopiuj:
/components/mod_latest_news/default.php
do:
/templates/rhuk_milkyway/html/mod_latest_news/default.php
Czytaj więcej o kodzie wynikowym modułu.
Aby dodać nowe style modułu (ramki), dodaj następujący plik
/templates/rhuk_milkyway/html/modules.php
Czytaj więcej o ramkach modułu.
Aby dostosować do swoich wyobrażeń standardowy selektor stron oraz listę Paginacja, wyedytuj następujący plik:
/templates/rhuk_milkyway/html/pagination.php
Czytaj więcej o paginacji.
Dzięki zastosowaniu paradygmatu MVC Joomla! 1.5 stał się elastyczniejszy. Za pomocą kilku prostych czynności, jak kopiowanie pewnych plików do pewnych miejsc w swoim szablonie, projektant jest w stanie niemal w całości przesłonić generowany HTML, nadpisując go własnym. Jeśli masz jakieś pytania odnoszące się do koncepcji podmiany, zapraszamy - pomogą nam udoskonalić ten poradnik. Jeśli przetłumaczyłeś ten artykuł na inny język, prosimy, powiadom nas o tym.