Rola pliku templateDetails.xml

Skrypt templateDetails.xml spełnia trzy funkcje:

• integruje szablon z Joomla! i Mambo,
• instruuje instalatora, gdzie i jakie pliki umieścić podczas instalacji.
• udostępnia w panelu administracyjnym informacje o szablonie.

Struktura pliku

Skrypt składa się z dwóch elementów - nagłówka oraz elementu głównego: mosinstall, w którym można wyodrębnić dwie części:

• informacyjną - zawiera dane szablonu,
• konfiguracyjną - określa rozmieszczenie plików szablonu

Kod

Oto przykładowy kod:

<?xml version="1.0" encoding="iso-8859-2"?>
<mosinstall type="template" version="1.0.0">
  <name>nazwa_identyfikująca</name>
  <creationDate>2006-08-01</creationDate>
  <author>Nazwa projektanta - Autora, pracowni</author>
  <copyright>GNU/GPL</copyright>
  <authore-mail>adres e-mail autora</authore-mail>
  <authorUrl>www.domena.pl</authorUrl>
  <version>1.0</version>
  <description>Szablon dla Joomla!</description>
  <files>
     <filename>index.php</filename>
     <filename>template_thumbnail.png</filename>
  </files>
  <images>
     <filename>images/header.jpg</filename>
  </images>
  <css>
     <filename>css/template_css.css</filename>
  </css>
</mosinstall>

Objaśnienia

Skrypt instalacyjny napisany jest w języku XML. Każdy znacznik musi więc być zamknięty. Poniżej znajdziesz szczegółowe objaśnienie poszczególnych elementów.

Nagłówek

W nagłówku skryptu umieszczona jest instrukcja dla programu przetwarzającego:

<?xml version="1.0" encoding="iso-8859-2"?>

Informuje ona procesor, że plik został napisany zgodnie ze specyfikacją XML w wersji 1.0 (aktualnie jedyna możliwa) oraz że kodowany jest zgodnie ze standardem iso-8859-2. Można by również podać uniwersalną stronę kodową UTF-8 lub opuścić tę część instrukcji. Jeśli jej nie ma, program przetwarzający przyjmuje, że zostało zastosowane uniwersalne domyślne kodowanie - właśnie UTF-8.

Element główny

Element główny rozpoczyna linia druga, a kończy ostatnia:

<mosinstall type="template" version="1.0.0">
</mosinstall>

Znacznik mosinstall poleca zainstalować szablon, a więc umieścić wyszczególnione w dalszej części pliki na serwerze internetowym w katalogu templates/00_podstawa. Argument template wskazuje instalatorowi, że jest to właśnie szablon, a nie moduł czy komponent. Argument version określa numer wersji Joomla! lub Mambo, dla której szablon został stworzony. W praktyce nie ma to większego znaczenia, bowiem od kilku lat koncepcja szablonów dla tych systemów nie uległa zmianie.

Kończąca instrukcję ostatnia linia kodu zawiera jedynie słowo kluczowe mosinstall poprzedzone ukośnikiem i ujęte, jak wszystkie instrukcje w ostre nawiasy.

Część informacyjna

  <name>00_podstawa</name>

Trzecia linia określa nazwę szablonu, a równocześnie nazwę katalogu, w którym instalator ma umieścić pliki. Na podstawie tej instrukcji zakładany jest katalog główny szablonu. W gruncie rzeczy jest to więc nie tylko informacja, ale i instrukcja konfiguracyjna.

Instalator zakłada poprawnie nazwany katalog także wówczas, gdy nazwa szablonu składa się z więcej niż jednego wyrazu. Łączy wtedy słowa tworzące nazwę w jedno za pomocą dolnych łączników.

Jeśli instalujesz szablony ręcznie, zwróć uwagę, aby nazwa katalogu odpowiadała nazwie szablonu. W przeciwnym przypadku Joomla! lub Mambo zgłoszą komunikat, że szablon nie został znaleziony lub wybrany.

  <creationDate>2006-08-01</creationDate>
  <author>Stefan Wajda</author>
  <copyright>GNU/GPL</copyright>
  <authore-mail>
 Ten adres email jest ukrywany przed spamerami, włącz obsługę JavaScript w przeglądarce, by go zobaczyć
 </authore-mail>
  <authorUrl>www.joomla.pl</authorUrl>
  <version>1.0</version>

Kolejnych sześć linii zawiera dane szablonu. Nie są one konieczne, by z szablonu korzystać. Prezentowane są w panelu administracyjnym. Mogą być również wykorzystane przez składniki Joomla! i Mambo lub programy zewnętrzne.

• Linia 4: Zawiera datę stworzenia szablonu. Data może być zapisana w dowolnym formacie, np. maj 2006, 08 czerwca 1978, 01/01/2004, May 2005 itd.
• Linia 5: Zawiera nazwę autora: pełne imię i nazwisko lub tylko imię czy pseudonim.
• Linia 6: To oznaczenie praw własności do szablonu i warunków korzystania z niego. Może zawierać nazwę firmy - projektanta, jeśli prawa własności są zastrzeżone. Powinna zawierać nazwę dokumntu zawierającego zasady i warunki korzystania z szablonu. W przypadku bezpłatnych szablonów jest to zwykle Powszechna Licencja Publiczna GNU GPL. Czasem licencja Common Creative. Oczywiście, może być każda inna.
• Linia 7: Zawiera adres poczty elektronicznej autora szablonu, na wypadek, gdyby zdarzyły się jakieś problemy.
Linia 8: Zawiera adres strony internetowej projektanta.
• Linia 9: Oznacza wersję szablonu: pierwsza cyfra oznacza numer główny wersji, cyfry lub litery następne kolejne podwersje, informujące, że w stosunku do wersji podstawowej zostały wprowadzone poprawki, ale zachowany został zasadniczy kształt projektu.

<description>Podstawa szablonu dla Joomla.</description>

• Linia 10: opisuje zwięźle szablon, jego właściwości i walory.

Część konfiguracyjna

  <files>
     <filename>index.php</filename>
     <filename>template_thumbnail.png</filename>
  </files>
  <images>
     <filename>images/header.jpg</filename>
  </images>
  <css>
     <filename>css/template_css.css</filename>
  </css>

Linie te wskazują na pliki składowe i ich lokalizację w katalogu szablonu. Mamy tutaj trzy sekcje - obejmowane przez znaczniki files, images i css.

• Linia 11: Znacznik rozpoczynający wyszczególnianie plików. Angielskie słowo <files>, oznaczające 'pliki', ujęte w ostre nawiasy
• Linia 12-13: Instrukcje wskazujące instalatorowi, że w głównym katalogu szablonu należy umieścić:
  • plik index.php
  • plik template_thumbnail.png

Nazwy plików ujęte są w znacznik rozpoczynający <filename> i w znacznik kończący </filename> (różnią się ukośnikiem). Plik template_thumbnail.png to miniatura zrzutu ekranu prezentująca szablon. Umieszczamy ją również w głównym katalogu szablonu. Nie wyszczególniamy tu skryptu templateDetails.xml. Instalator umieszcza bowiem ten właśnie plik jako pierwszy.

• Linia 14: Znacznik zamykający wyszczególnianie plików - </files>, tym razem z ukośnikiem.
• Linia 15: Znacznik wskazujący instalatorowi, że ma założyć podkatalog /images, rozpoczynający wyszczególnianie plików, które należy umieścić w tym katalogu,
• Linia 16: Instrukcja wskazująca instalatorowi, że ma umieścić plik logo.jpg w katalogu /images/. Stąd w początkowy i kończowy znacznik <filename>images/header.jpg</filename> wpisana jest zarówno nazwa podkatalogu, jak i nazwa pliku, a więc ścieżka względna do pliku.
• Linia 17: Znacznik zamykający instrukcje dotyczące utworzenia katalogu /images i umieszczanie w nich plików.
• Linia 18-20: Są skonstruowane podobnie, tyle że dotyczą katalogu /css i umieszczanego w nim pliku z arkuszem stylów.

Przygotowanie pliku konfiguracyjnego szablonu nie jest, jak widać, skomplikowane.

Jeśli skrypt ma posłużyć także do instalacji szablonu, trzeba tylko dokładnie sprawdzić, czy wyszczególnione zostały w nim wszystkie pliki składowe.

Aby plik został odczytany poprawnie przez intsalatora, musi zostać zakodowany zgodnie z instrukcją umieszczoną w pierwszej linii. Niektóre edytory HTML, np. polski Pajączek na podstawie tej instrukcji zapiszą plik w zadeklarowanym kodowaniu. W przypadku innych trzeba określić sposób kodowania podczas zapisu albo dokonać odpowiedniej konwersji, korzystając z programu narzędziowego lub odpowiedniego edytora. Ot, dlaczego warto korzystać z odpowiedniego oprogramowania.

Uwagi, źródła

Jeżeli masz sugestie odnośnie treści lub chcesz zgłosić poprawki do tego rozdziału, skomentuj go albo umieść wiadomość na forum: Dokumentacja - Propozycje, zmiany, poprawki

Dziękujemy!

Stefan Wajda, Zespół Dokumentacji PCJ