mslonik.pl

Nie znalazłem artykułu, który temat omawiał by wystarczająco wyczerpująco i jednoznacznie. Ponieważ w trakcie prac nad jednym z dodatków napotkałem na konieczność dogłębnego zrozumienia, jak działa instalator Joomla!, więc postanowiłem spisać swoje wnioski. Może komuś się przydadzą.

Inne nazwy tego pliku to: deskryptor, plik instalacyjny, plik konfiguracyjny, plik .xml.

W artykule krótko omawiam składnię i sposób korzystania z pliku manifestu .xml w przypadku tworzenia rozszerzeń do środowiska Joomla! 1.5.x typu dodatek (ang. plugin).

Zapraszam do lektury!

Plik manifestu to mówiąc najprościej instrukcja, dzięki której wbudowany w środowisko J! instalator będzie wiedział gdzie umieścić informacje zgromadzone w paczce instalacyjnej.

Gdzie znajdziemy instalator? Znajdziemy go na zapleczu naszej witryny. Menu -> Rozszerzenia -> Instalator.

Paczki instalacyjne dodatków dla J! to pliki skompresowane do archiwum .zip. Przyjrzyjmy się takiej przykładowej paczce. Zachęcam do ściągnięcia przykładowej paczki jakiegoś dodatku, najlepiej takiego, którego działanie znamy i rozumiemy.

W nazwie często zakodowana jest wersja środowiska J! oraz wersja dodatku. Załóżmy na potrzeby tego artykułu, że zajmujemy się fikcyjnym dodatkiem o jakże sympatycznie brzmiącej nazwie 'ewulka'. Jak więc może wyglądać nazwa pliku dodatku? Na przykład tak:

ewulka_J1.5-2.11.zip

ewulka_2.11_PL.zip

ewulka-2.11_J1.5.zip

tymczasowy.zip

Nazwa nie ma więc większego znaczenia, ale ze względów porządkowych warto trzymać się jakiejś konwencji i systematycznie jej przestrzegać. Zalecam pierwszy z wymienionych przykładów.

Ponieważ .zip jest dosyć popularnym typem archiwum, więc możemy je rozpakować posługując się np. swoim ulubionym menedżerem plików i obejrzeć jego zawartość. Prawdopodobnie będzie ono wyglądało następująco:

paczka_J15_1.21.zip:

katalog

plik.xml

plik.php

Katalog jest nieobowiązkowy, czyli w przypadku małych dodatków może go po prostu nie być. Uwaga na nazwy. Jeżeli nasz dodatek nazwiemy 'ewulka', to taką samą nazwę powinien nosić katalog oraz wspomniane pliki:

ewulka_J1.5-2.11.zip:

ewulka

ewulka.xml

ewulka.php

Warto się trzymać tej konwencji, bo nazwy klas czy funkcji w kodzie dodatku bazują na nazwie pliku .php. Dla zainteresowanych, szczegóły zostały opisane tutaj. Z tego samego powodu kodowanie wersji dodatku w nazwie plików czy katalogu wewnątrz pliku jest złym pomysłem.

Co my tu mamy. W katalogu mogą być inne podkatalogi i często tak właśnie jest. Zdarza się, że obok głównego katalogu (ewulka) znajdziemy też katalog z wersjami językowymi dodatku o nazwie languages. Katalog ten zawiera pliki z rozszerzeniem .ini.

ewulka_J1.5-2.11.zip:

ewulka

languages

ewulka.xml

ewulka.php

Uwaga: złym pomysłem jest kodowanie wersji dodatku w nazwie katalogów lub plików wewnątrz paczki. Wersja jest przechowywana w tytułowym pliku manifestu (.xml).

Plik .php (ewulka.php) zawiera kod, skrypt dodatku. Działanie dodatku jest zdefiniowane właśnie w tym pliku.

Plik .xml (ewulka.xml) zawiera manifest dodatku, czyli instrukcję dla instalatora i deinstalatora.

Zajmijmy się teraz w szczegółach plikiem manifestu .xml. Jego zawartość jest napisana w języku znaczników .xml. Mówiąc najprościej kolejne parametry pliku są umieszczone pomiędzy znacznikami: <otwierającym> i </zamykającym>. Dopuszczalne jest zagnieżdżanie znaczników. Szczególna para znaczników, o której warto pamiętać, to:

<!-- ... -->

Wszystko co, znajdzie się pomiędzy tymi znacznikami (np. powyższe trzy kropki) zostanie potraktowane jako komentarz.

Zaczynamy. Tworzymy przykładowy plik 'ewulka.xml' i przekopiowujemy do niego następującą zawartość:

<?xml version="1.0" encoding="utf-8"?>
<!-- upgrade = shall be able to overwrite existing files -->
<install version="1.5" type="plugin" group="content" method="upgrade">
    <name>ewulka</name>
    <!-- The following elements are optional and free of formatting conttraints -->   
    <creationDate>2010-04-05</creationDate>
    <author>mslonik</author>
    <authorEmail> Adres poczty elektronicznej jest chroniony przed robotami spamującymi. W przeglądarce musi być włączona obsługa JavaScript, żeby go zobaczyć. </authorEmail>
    <authorUrl>http://mslonik.pl</authorUrl>
    <copyright>http://mslonik.pl</copyright>
    <license>GNU wer. 3</license>
    <!--  The version string is recorded in the components table -->
    <version>1.0</version>
    <!-- The description is optional and defaults to the name -->
    <description>SLIMBOXDESCINPLUGIN</description>
    <!-- Site Main File Copy Section -->
    <!-- Note the folder attribute: This attribute describes the folder
         to copy FROM in the package to install therefore files copied
         in this section are copied from /site/ in the package -->
    <files>
        <filename plugin="ewulka">ewulka.php</filename>
        <folder>pierwszy</folder>
    </files>

    <languages folder="languages">
        <language tag="pl-PL">pl-PL.plg_content_ewulka.ini</language>
    </languages>

    <params>
    </params>
</install>

Skąd instalator wie, które pliki zainstalować? Skąd instalator wie, które pliki usunąć? Gdzie instalator kopiuje pliki?

Na powyższe pytania niestety nie ma prostej odpowiedzi. Brakuje bowiem czytelnego mechanizmu, który pozwoliłby poinformować instalator co gdzie przenieść. Zadanie na pewnym poziomie ogólności wydaje się dosyć proste:

• Na etapie instalacji chcemy przenieść plik (lub katalog) z paczki do struktury plików i katalogów środowiska J!
• Na etapie usuwania chcemy usunąć tylko te pliki, które pierwotnie zostały przekopiowane do struktury plików i katalogów środowiska J!.

Czas już odpowiedzieć na pytanie dokąd zostaną przeniesione nasze pliki i foldery. Ponieważ po znaczniku <install> podaliśmy parametr type="plugin", więc pliki i foldery znajdą się w katalogu:

(...)/plugins

Dalej doprezyzowując, jeżeli po znaczniku <install> podaliśmy parametr group="nazwa_gurpy", to znajdą się one w katalogu:

(...)/plugins/nazwa_grupy

Zarówno informacje o źródle, jak i przeznaczeniu oraz liście plików do usunięcia są przechowywane w pliku .xml pomiędzy znacznikami

<files>

...

</files>

W tym samym pliku .xml może być tylko jedna taka sekcja.

Co tam możemy znaleźć? Dwa rodzaje znaczników:

<filename> ... </filename>

<folder> ...</folder>

Pierwszy typ znacznika (filename) pozwala nam selektywnie przekopiować pliki z paczki w miejsce przeznaczenia. Tylko pliki, które zostaną przez nas wprost podane zostaną przekopiowane do miejsca przeznaczenia. Musimy jednak podać pełną ścieżkę dostępu do danego pliku. Instalator utworzy dokładnie takie same katalogi i umieści w nich wskazany przez nas plik.

Szczególną rolę odgrywa następująca, obowiązkowa formuła:

<filename plugin="ewulka">ewulka.php</filename>

Co się stanie podczas usuwania dodatku? Cóż, instalator nie potrafi usuwać katalogów. Usunie tylko pliki wskazane pomiędzy znacznikami 'filename'.

Przykład: instalacja dodatku.

W paczce ewulka.zip tworzymy następujące drzewo katalogów wraz z plikami:

ewulka.zip/pierwszy/drugi/trzeci/pasztet.txt

ewulka.zip/pierwszy/drugi/trzeci/foka.txt

W manifeście dopisujemy sekcję 'filename':

<filename>pierwszy/drugi/trzeci/pasztet.txt</filename>

W efekcie instalator stworzy wszystkie katalogi potrzebne, by ścieżka dostępu wyglądała następująco:

(...)/plugins/content/pierwszy/drugi/trzeci

Pliki 'pasztet.txt' oraz 'foka.txt' nie zostaną zainstalowane.

Przykład: usuwanie dodatku.

W manifeście podaliśmy następującą ścieżkę:

<filename>pierwszy/drugi/trzeci/pasztet.txt</filename>

W trakcie usuwania dodatku usunięty zostanie tylko plik

(...)/plugins/content/pierwszy/drugi/trzeci/pasztet.txt,

a nie zostaną usunięte katalogi 'pierwszy', 'drugi' oraz 'trzeci'.

Drugi typ znacznika (folder) pozwala na przeniesienie od razu całego katalogu wraz z całą zawartością. Zamiast więc pracowicie nazywać poszczególne pliki, od razu skopiuje wszystkie. Nie będziemy więc mieć kontroli nad każdym pojedynczym plikiem, ale będziemy mieć kontrolę nad całymi katalogami.

Przykład: instalacja dodatku.

W paczce ewulka.zip tworzymy następujące drzewo katalogów wraz z plikami:

ewulka.zip/pierwszy/drugi/trzeci/pasztet.txt

ewulka.zip/pierwszy/drugi/trzeci/czwarty/foka.txt

ewulka.zip/kolejny/podkatalog/pustak.txt

W manifeście dopisujemy sekcję 'files':

<files>pierwszy</files>

W efekcie instalator utworzy katalogi i przekopiuje pliki:

(...)/plugins/content/pierwszy/drugi/trzeci/pasztet.txt

(...)/plugins/content/pierwszy/drugi/trzeci/czwarty/foka.txt

Przykład: usuwanie dodatku.

W manifeście podaliśmy następującą ścieżkę:

<files>pierwszy</files>

W trakcie usuwania dodatku usunięty zostanie katalog '(...)/plugins/content/pierwszy' oraz wszystkie podkatalogi i pliki.

Polecam drugi sposób. Jest moim zdaniem wygodniejszy.

Niestety od tej reguły jest wyjątek. Nieco inaczej instalator traktuje tzw. pliki językowe, czyli pliki zawierające tłumaczenie rozszerzenia na dany język. Pliki te mają rozszerzenia .ini. Informacje o tym, gdzie te pliki się znajdują w paczce instalacyjnej są przekazywane pomiędzy tagami 'languages' poprzez parametr "folder". Parametr "folder" informuje program instalacyjny, gdzie w paczce instalacyjnej znajdują się pliki językowe. Położenie plików językowych, czyli miejsce, w które zostaną one przeniesione z paczki instalacyjnej, jest ustalone:

(...)/administrator/language

W tym katalogu znajdują się podkatalogi o nazwach identycznych jak przekazane w parametrze 'tag' tagu 'language'. To do nich przenoszone są pliki językowe.

Podsumowując:

Ważną z punktu widzenia dbałości o bezpieczeństwo jest umieszczanie we wszystkich folderach, które umieszczamy w zasobach J! pliku 'index.html' o następującej zawartości:

<html><body bgcolor="#FFFFFF"></body></html>

Dlaczego należy to zrobić? Plik  'index.html' nie pozwala na wyświetlenie zawartości katalogu podczas prób nieautoryzowanego przeglądania zawartości katalogów umieszczonych w zasobach serwera www. Gdyby nie było pliku 'index.html', to niektóre z serwerów wyświetliłyby zawartość katalogu, czego zazwyczaj sobie nie życzymy.

Lektura uzupełniająca:

1. http://docs.joomla.org/How_to_create_a_content_plugin
2. http://developer.joomla.org/tutorials/184-how-to-create-a-joomla-plugin.html
3. http://docs.joomla.org/Category:Plugins
4. http://docs.joomla.org/Components:xml_installfile

Po polsku:

1. http://wiki.joomla.pl/index.php/Plik_templateDetails.xml/Do_czego_s%C5%82u%C5%BCy_plik_templateDetails.xml%3F
2. http://wiki.joomla.pl/index.php/Plik_templateDetails.xml/Manifest_XML_-_zestawienie_znacznik%C3%B3w