Moduł

Uwaga: Wsparcie dla modułów zostało dodane od wersji 1.0.3.

Moduł jest samowystarczalną jednostką aplikacji, która zawiera modele, widoki, kontrolery oraz inne wpierające komponenty. W wielu aspektach, moduły przypominają aplikację. Główna różnica jest taka, że moduł nie może istnieć sam i musi rezydować w aplikacji. Użytkownicy posiadają dostęp do kontrolerów w modułach w ten sam sposób jak w kontrolerze aplikacji.

Moduły są użyteczne w kilku scenariuszach. Dla dużych aplikacji, możemy ją podzielić na kilka modułów, każdy z nich może być pisany oraz zarządzany osobno. Część wspólnie używanych funkcjonalności, takich jak zarządzanie użytkownikami, zarządzanie komentarzami, mogą być opracowywane w postaci modułów, które można łatwo ponownie wykorzystać w przyszłych projektach.

1. Tworzenie modułu ¶

Moduł jest zorganizowany w folderze, którego nazwa służy jako jego unikalne ID. Struktura folderu modułu jest podobna do tej z folderu głównego aplikacji. Poniżej pokażemy typową strukturę modułu nazwanego forum:

forum/
   ForumModule.php            klasa modułu
   components/                posiada komponenty użytkownika do ponownego użycia
      views/                  zawiera pliki widoków dla widżetów
   controllers/               zawiera pliki klas kontrolerów
      DefaultController.php   plik domyślnego kontrolera klasy
   extensions/                zawiera zewnętrzne rozszerzenia
   models/                    zawiera pliki modeli klas
   views/                     zawiera pliki widoku kontrolera oraz układów
      layouts/                zawiera pliki układów widoku
      default/                zawiera plik widoku dla DefaultController (domyślnego kontrolera)
         index.php            plik widoku index

Moduł musi posiadać klasę modułu, która dziedziczy z CWebModule. Nazwa klasy zależy od wyniku wyrażenia ucfirst($id).'Module', gdzie $id odpowiada ID modułu (lub folderowi modułu). Klasa modułu służy jako główne miejsce dla przechowywania informacji współdzielonych wewnątrz kodu modułu. Na przykład, możemy użyć CWebModule::params do przechowywania parametrów modułu oraz CWebModule::components do dzielenia komponentów aplikacji na poziomie modułu.

Wskazówka: Możemy użyć narzędzia yiic do stworzenia podstawowego szkieletu nowego modułu. Na przykład, aby utworzyć powyższy moduł forum forum możemy wykonać następujące polecenie w oknie linie poleceń:

% cd WebRoot/testdrive
% protected/yiic shell
Yii Interactive Tool v1.0
Please type 'help' for help. Type 'exit' to quit.
>> module forum

2. Używanie modułów ¶

Aby używać modułu, najpierw umieść moduł w katalogu modules w folderze głównym aplikacji. Następnie zadeklaruj ID modułu we właściwości modules aplikacji. Na przykład, w celu używania powyższego modułu forum, możemy używać następującej konfiguracji aplikacji:

return array(
    ......
    'modules'=>array('forum',...),
    ......
);

Moduł może również zostać skonfigurowany poprzez wartości inicjalne właściwości. Sposób użycia jest bardzo podobny do tego z konfiguracji komponentów aplikacji. Na przykład, moduł forum może mieć właściwość nazwaną postPerPage (ilość postów na stronę) w swojej klasie, która może zostać skonfigurowana w [konfiguracji aplikacji(/doc/guide/basics.application#application-configuration) następująco:

return array(
    ......
    'modules'=>array(
        'forum'=>array(
            'postPerPage'=>20,
        ),
    ),
    ......
);

Dostęp do instancji modułu można uzyskać poprzez właściwość module aktualnie aktywnego kontrolera. Poprzez instancję modułu, możemy uzyskać dostęp do informacji dzielonych na poziomie modułu. Na przykład, w celu uzyskania dostępu do powyższej informacji o ilości postów na stronę postPerPage, możemy użyć następującego wyrażenia:

$postPerPage=Yii::app()->controller->module->postPerPage;
// lub następująco jeśli $this oznacza instancję kontrolera
// $postPerPage=$this->module->postPerPage;

Dostęp do akcji kontrolera w module można uzyskać poprzez trasę IDmodułu/IDkontrolera/IDakcji. Na przykład, zakładając, że powyższy moduł forum posiada kontroler nazwany PostController, używany trasy forum/post/create aby odnieść się do akcji create w tym kontrolerze. Odpowiadający tej trasie adres URL będzie następujący http://www.example.com/index.php?r=forum/post/create.

Wskazówka: Jeśli kontroler jest podkatalogiem katalogu controllers możemy wciąż używać powyższego formatu trasy. Na przykład, zakładając, że kontroler PostController znajduje się wewnątrz forum/controllers/admin, możemy odnieść się do akcji create używając forum/admin/post/create.

3. Zagnieżdżone moduły ¶

Moduły mogą być zagnieżdżone. Oznacza to, że jeden moduł może posiadać inne moduły. Pierwszego nazywamy modułem rodzica a drugiego modułem dziecka. Moduły dzieci muszą znajdować się w katalogu modules moduły rodzica. Aby uzyskać dostęp do akcji kontrolera w module dziecka, powinniśmy używać trasy IDModułuRodzica/IDModułuDziecka/IDKontrolera/IDAkcji.