--=REKLAMA=--

Podstawy działania komponentu

Z Joomla!WikiPL

Dokument opisuje całkowite podstawy funkcjonowania komponentu. Jest napisany z myślą o początkujących programistach, żeby pomóc im zrozumieć, jak działa komponent Joomla!.

Wprowadzenie

Platforma Joomla! rozpoczyna swoją pracę przez odwołanie do pliku index.php. Joomla! jest zaprojektowany w taki sposób, żeby wyświetlać zawartość z plików komponentów. Kiedy wywołujesz stronę index.php?option=com_<name>, Joomla! próbuje wyświetlić plik components/com_<name>/<name>.php z folderu, w którym jest zainstalowany Joomla!. Jeśli komponent nazywa się 'com_read', powinien istnieć folder 'com_read', a w tym folderze plik 'read.php'. Nazwijmy ten plik 'plikiem podstawowym'. To w tym pliku zdefiniowane jest, czy należy użyć starego, płaskiego modelu (zwracającego kod HTML żądanej strony), czy użyć modelu MVC (Model-Vew-Controller - Model-Widok-Kontroler).

Model MVC ma dwa składniki: plik oraz klasę. Joomla! zazwyczaj wyszuka odpowiedni plik, a jeśli go znajdzie, spróbuje utworzyć klasę zawartą w tym pliku. Jeśli będzie brakowało któregoś z tych składników, próba wywołania strony nie powiedzie się.

Twój plik controller.php

Wszystko zaczyna się od zawarcia odnośnika do pliku kontrolera w naszym pliku bazowym. Plik kontrolera może być dowolnie nazwany, ale umownie zazwyczaj nazywa się 'controller.php'. Typowy kod w pliku bazowym (<name>.php) wygląda zazwyczaj tak:

require_once(JPATH_COMPONENT . '/controller.php');

Plik controller.php możesz utworzyć w dowolnym miejscu, ponieważ odwołanie do niego będzie zawsze za pomocą ścieżki. Jeśli Twój kod wygląda dokładnie tak, jak ten powyżej, to 'controller.php' powinien być zapisany w tym samym miejscu (folderze) co plik bazowy. 'JPATH_COMPONENT' zawiera ścieżkę do wykonywalnego pliku bazowego komponentu.

Utwórz więc plik 'controller.php' i odwołuj się do biblioteki kontrolera, importując ją w taki sposób:

jimport('joomla.application.component.controller');

Teraz, mając utworzony plik 'controller.php' i zaimportowaną klasę 'JControllerLegacy', musisz zdefiniować klasę, która będzie rozszerzeniem dla 'JControllerLegacy'. Jest to składnik klasy, o którym wspominałem wcześniej. Tutaj będą zdefiniowane konkretne akcje. Możesz nazwać tą klasę dowolnie, ale zgodnie z konwencją przyjętą w komponencie. Napisz:

class <name>Controller extends JControllerLegacy
{
}

Na tym etapie powinieneś mieć dwa pliki: plik bazowy i plik kontrolera. Plik bazowy ładuje kontroler, a kontroler definiuje klasę. Jak na razie prosto i przyjemnie. Następnym krokiem będzie stworzenie obiektu naszej klasy i zmuszenie go do pracy. Dodaj poniższy kod do pliku bazowego:

// wywołuje kontroler zdefiniowany w <name>
$controller = JControllerLegacy::getInstance('<name>');
 
// wykonuje żądane zadanie
$controller->execute(JFactory::getApplication()->input->getCmd('task'));
 
// przekierowuje, jeśli jest to ustawione w kontrolerze
$controller->redirect();

Od tego momentu wszystko zaczyna działać samo. Do tej pory mogłeś nazywać pliki i klasy (poza plikiem bazowym) jak chciałeś i umieszczać je w dowolnym folderze, ponieważ odwoływałeś się do nich za pomocą ścieżki lub wywoływałeś klasę, podając jej nazwę w kodzie (tak właściwie to tylko jeden plik i jedna klasa, ale mogłeś!). Od tej chwili Joomla! będzie ładować Twoje pliki i wywoływać klasy automatycznie. Dlatego musisz uważnie zapisywać pliki w odpowiednich folderach, odpowiednio je nazywać i odpowiednio definiować klasy. Nawet zwykła literówka spowoduje błąd Joomla!.

Pobieranie danych

Skąd Joomla! pobiera dane do działania? Odpowiedź jest prosta: z żądań GET lub POST. Ale nie napisałeś w żądaniu nic poza 'option=com_<name>'. Więc skąd się bierze 'zadanie' w zapytaniu? Czy faktycznie masz tak wymowną zmienną 'zadanie'?

Tak, i na tym polega 'problem': niezależnie czy wpiszesz żądanie czy nie, Joomla! zawsze użyje domyślnych wartości, żeby wypełnić żądanie, powodując że niektóre błędy mogą być trudne do zlokalizowania.

Instrukcja controller->execute() spowoduje, że Joomla! spróbuje wysłać żądanie, które w tym wypadku będzie domyślnym zadaniem 'wyświetlania', ponieważ nie podałeś żadnego innego.

class <name>Controller extends JControllerLegacy
 
{
  function display()
  {
    echo 'displaying';
  }
}

jeśli wysłane żądanie zawiera parametr 'task=jump', kontroler spróbuje wywołać metodę (funkcję) o nazwie 'jump' w klasie kontrolera:

class <name>Controller extends JControllerLegacy
{
  function jump()
  {
    echo 'jumping';
  }
}

Widok

Do tej pory zajmowaliśmy się pierwszą częścią modelu MVC - kontrolerem. Teraz pora podjąć decyzję - kończysz w tym miejscu albo przechodzisz do kolejnej części modelu, a mianowicie do widoku (View).

Różne zadania kontrolera to jego metody zapisane w 'controller.php'. Wszystkie potrzebne zmienne są dostępne w Joomla!, więc z łatwością można je pobierać.

Nie ma przymusu używania zmiennej 'task' do dostarczania żądania ponieważ można używać do tego wartości dowolnej zmiennej jako parametr metody wykonawczej. Jednak zgodnie z niepisaną zasadą, zazwyczaj używane jest 'task' i jest specjalnie traktowane przez system. Najlepszym pomysłem będzie trzymanie się tej zasady.

Do wywołania widoku używa się metody __construct() z JControllerLegacy. Robi się to przez wstawienie w swojej metodzie wywołania parent::__construct() w ostatniej linii. Minimalny kod, jaki powinien być zawarty w pliku kontrolera, to:

jimport('joomla.application.component.controller');
 
class <name>Controller extends JControllerLegacy
{
}

Co to jest widok? Widok to pewien podzbiór danych. Jest to to samo pojęcie jak w żargonie SQL. Dostarczasz różne części danych w różnych widokach. Możesz więc mieć szczegółowy lub częściowy widok danych.

Ponieważ możesz mieć zdefiniowanych wiele widoków, Joomla! używa folderu 'views' w folderze Twojego komponentu, żeby wszystko było uporządkowane

<name> folder główny
  controller.php
  <nazwa_komponentu>.php
  'views' folder
     view1 folder
     view2 folder
     ...

W folderze 'views' znajdują się podfoldery. Każdy z nich odpowiada za inny widok. Joomla! zawiera plik 'view.html.php', który powinien też być w folderze Twojego widoku. Jest to nieco skomplikowane dlatego postaram się wyjaśnić.

Kiedy budujesz żądanie, zawierasz w nim zmienną 'view', która jest informacja dla modelu MVC, który widok ma wyświetlić. jeśli nie dołączyłeś takiej zmiennej to najwyższa pora to zrobić, ponieważ nie ma czegoś takiego jak widok domyślny. Twój URL powinien wyglądać mniej więcej tak:

http://example.com/index.php?option=com_<name>&view=<myview>[&task=<mytask>]

Część żądania z parametrem 'task' może istnieć, ale nie musi. Należy jedynie pamiętać, że jeśli je pominiemy zostaniemy skierowani do 'task=display'. Wtedy Joomla! pobiera plik '<site root dir>/components/<name>/views/<myview>/view.html.php'. Jeśli ta ścieżka będzie niepoprawna lub plik nie będzie istniał, Joomla! zgłosi błąd. Przez prostą podmianę wartości 'view', zmieniamy widoki, które Joomla! wyświetli.

Każde żądanie widoku wymaga określenia formatu, w jakim widok ma zostać podany. Jest kilka doskonale znanych formatów, takich jak html (jest to format domyślny, jeśli inny nie został określony), rss lub inne. Możesz też zdefiniować własny format. Jeśli nic nie zdefiniujemy, w żądaniu w 'format=<myformat>', zostanie ustawiona wartość 'html'.

Format 'html' pozwala Joomla! przygotować odpowiedź na żądanie w dowolnym szablonie witryny, którego używa Twoja strona. Wynikowo dostaniesz kompletną stronę HTML. W ten sposób przy minimalnym wysiłku z Twojej strony, otrzymujesz gotową stronę z załadowanymi modułami i wszystkim, co skonfigurowałeś.

Konkretny format, którego potrzebujesz musi być podany jako środkowa część nazwy pliku w folderze widoku (wcześniej mówiliśmy o pliku 'view.html.php'). Jeśli wybierzesz inny format, na przykład rss, plik powinien mieć nazwę 'view.rss.php'. Proste, prawda?

Jak wspomniałem wcześniej, możesz stosować formaty inne niż 'html' a Joomla! będzie w stanie ubrać je w odpowiednie skórki. Możesz wybrać 'pdf', żeby wyświetlić dane w formie PFD czy nawet 'ajax' żeby wyświetlić odpowiedzi ajaxa na wyświetlanej stronie. Wystarczy przygotować adres w postaci:

http://example.com/index.php?option=com_<name>&view=<myview>&format=ajax

żeby Joomla! wyszukał i załadował plik 'view.ajax.php' z folderu <site root dir>/components/<name>/views/<myview>/, z którym możesz zrobić, co tylko chcesz. To dosyć proste.

W każdym razie, żeby osiągnąć cel, niezbędna będzie pewna ilość kodu w pliku 'view.<format>.php'. Masz już plik widoku, teraz potrzebna będzie klasa widoku. Musisz rozszerzyć klasę 'JView' swoją własną klasą, trzymając się zasad, o których była mowa wcześniej. W takim wypadku, nazwa Twojej klasy musi być tak zbudowana, żeby łączyła nazwę komponentu, słowo 'View' oraz nazwę widoku. Mniej więcej tak: <name>View<myview>. Jeśli Twój komponent nazywa się 'travels' a widok nazywa się 'detail' (URL ...?option=com_travels&view=detail), to twoja klasa widoku będzie taka:

class TravelsViewDetail extends JViewLegacy
{
  function display($tpl=null)
  {
    echo 'blah, blah';
  }
}

W ramach tej klasy musisz dostarczyć dane, które chcesz wyświetlić w swoim komponencie, w tym konkretnym przypadku. Możesz to zrobić po prostu, wpisując bezpośrednio kod HTML lub przez odwołanie do 'echo' wewnątrz tagów php, lub bardziej subtelnie - używając 'układu' (o tym później).

Czy można mieć inne funkcje poza wyświetlaniem? Nie wiem. To jest pytanie, na które musi odpowiedzieć któryś guru. Skąd pochodzi funkcja wyświetlania? Tego też nie wiem. Mam nadzieję, że ktoś inny tutaj pomoże.

Teraz możesz iść dalej. Do tej chwili masz przygotowaną platformę, która rozkłada twoje żądanie w tai sposób, że pozwala tworzyć niewielkie i bardzo specyficzne pliki, które mogą być odpowiedzią tylko na specyficzne żądania. W ten sposób pliki, które mają być przetworzone, są bardzo małe i dopasowane do sytuacji. Dzięki temu cały proces przygotowania strony jest przyspieszony przez to, że Joomla! nie musi przetwarzać ogromnych ilości kodu, który i tak nie jest potrzebny w danej sytuacji.

Skoro dotarłeś do tego momentu, możemy zagłębić się szczegółowo w następną warstwę: końcowy układ dla dostarczonych danych.

'Układ' to sposób prezentacji danych dla widoku. Te same dane, mogą być pokazane w różnej formie graficznej, więc ten sam kod (zawarty wewnątrz funkcji wyświetlania naszej klasy widoku) może wyświetlać te same dane w różny sposób używając po prostu różnych plików. Dane widoku są 'wstrzykiwane' do skórki układu i używają kodu tej skórki do wizualnego formatowania, żeby wyświetlić użytkownikowi informacje w odpowiedni sposób.

Tak jak poprzednio, jeśli nie określisz układu, Joomla! wyświetli domyślny układ. Żeby używać własnych układów należy stworzyć nowy folder 'tmpl' w folderze właściwego widoku. W nowym folderze należy stworzyć plik <mylayout>.php, nic więcej ani mniej. Jeśli używasz domyślnego widoku, plik będzie się nazywał 'default.php'.

Odpowiedni układ może być wywołany w żądaniu poprzez dodanie zmiennej 'layout=<mylayout>'.

Żeby użyć układu, twoja klasa widoku musi wywołać 'parent::display();' i przekazać nazwę skórki układu jako parametr. Twoja klasa powinna być mniej więcej taka:

class <Name>View<Viewname> extends JViewLegacy
{
  function display($tpl=null)
  {
    // przygotowanie danych
    $data1 = ....
    $data2 = ....
    $moredata[] = array....
 
    // 'wstrzyknięcie' danych
    $this->variablename = $data1;
    $this->variablename2 = $data2;
    $this->variablename3 = $moredata;
 
    // Wywołanie układu skórki. Jeśli nie ma wartości tpl Joomla! pozuka pliku default.php
    $tpl = 'myTemplate';
    parent::display($tpl);
  }
}

Dzięki temu Joomla! będzie szukać pliku o nazwie 'myTemplate.php' w folderze 'tmpl', w folderze podanego widoku. Wewnątrz pliku skórki masz obiekt $this, który ma dostęp do zmiennych dodanych przez $this->variablename, których możesz użyć w swoich konstrukcjach żeby przekazać 'ostateczny' kod HTML.

Jak pewnie zauważyłeś, możesz mieć różne pliki z układami wewnątrz folderu 'tmpl', więc prosto możesz przekazać niewielkie, specyficzne pliki wynikowe.

Jeśli do tej pory byłeś uważny, to zauważyłeś, że nie mówimy nic na temat 'modelu' (Model) z MVC. Oto ostatnie miejsce na podjęcie decyzji. Możesz pracować bez tej części, możesz też zastosować kompletny model MCV, ale o tym w kolejnym artykule. Myślę, że na razie wystarczy nowych wiadomości.

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

Dziękujemy za wkład

» Stefan Wajda [zwiastun],