Tematy

Tematy są usystematyzowanym sposobem personalizacji wyglądu stron aplikacji webowej. Poprzez zastosowanie nowego tematu cały wygląd aplikacji może być jednocześnie i znacząco zmieniony.

W ramach Yii każdy temat reprezentowany jest przez katalog zawierający pliki widoków, pliki układów (ang. layout) i powiązane z nimi pliki zasobów, takie jak obrazy, pliki CSS, Javascript, itp. Nazwa tematu jest też nazwą jego katalogu. Wszystkie tematy znajdują się we wspólnym katalogu WebRoot/themes. W dowolnej chwili tylko jeden z nich może być aktywny.

Wskazówka: Domyślny katalog tematów WebRoot/themes może być zastąpiony innym. Po prostu skonfiguruj odpowiednio atrybuty basePath oraz baseUrl komponentu aplikacji themeManager.

Aby aktywować jakiś temat ustaw atrybut theme aplikacji webowej na nazwę tematu, który chcesz użyć. Czynność tą możesz wykonać zarówno w konfiguracji aplikacji, jak i w trakcie uruchamiania, poprzez akcję kontrolera.

Uwaga: Nazwa tematu jest wrażliwa na wielkość liter. Jeżeli próbujesz aktywować temat, który nie istnieje Yii::app()->theme zwróci null.

Zawartość katalogu tematu powinna być zorganizowana w taką samą strukturę jak ta w ścieżce głównej aplikacji. Przykładowo, wszystkie pliki widoków muszą być umieszczone w views, pliki układów (ang. layout) widoku w views/layouts, a pliki widoków systemowych w views/system. Na przykład gdy będziemy chcieli zamienić widok create kontrolera PostController z widokiem tematu classic powinniśmy zapisać nowy plik jako WebRoot/themes/classic/views/post/create.php.

Dla widoków należących do kontrolera w module, odpowiadający mu plik widoku tematu powinien być również umieszczony w katalogu views. Na przykład, uprzednio omawiany kontroler PostController jest w module nazwanym forum, powinniśmy więc zapisać plik widoku create jako WebRoot/themes/classic/views/forum/post/create.php. W module forum zagnieżdżony jest inny moduł nazwany support, w tym wypadku plikiem widoku powinien być WebRoot/themes/classic/views/support/forum/post/create.php.

Uwaga: Ponieważ katalog views może zawierać wrażliwe z punktu widzenia bezpieczeństwa dane, powinien być zabezpieczony przed dostępem użytkowników internetu.

Gdy wywołujemy metodę render lub renderPartial aby wyświetlić widok, odpowiadające temu widokowi pliki, jak również pliki układu (layout) szukane będą w katalogu aktywnego tematu. Jeżeli zostaną odnalezione, będą renderowane. W przeciwnym razie aplikacja powraca do domyślnej lokalizacji określonej przez atrybuty viewPath i layoutPath.

Wskazówka: Wewnątrz widoku tematu musimy często dołączać pliki zasobów innych tematów. Np. możemy chcieć wyświetlić plik obrazu znajdujący się w katalogu images tematu. Korzystając z właściwości baseUrl aktualnie aktywnego tematu możemy wygenerować adres URL dla tego obrazka w sposób następujący:

Yii::app()->theme->baseUrl . '/images/FileName.gif'

1. Skórki ¶

Uwaga: Funkcja skórek jest dostępna od wersji 1.1.0.

Używając tematów możemy szybko zmieniać wygląd widoków. Możemy używać skórek do systematycznego dostosowywania wyglądu widżetów używanych w widoku.

Skórka jest tavblicą par nazwa-wartość, która może zostać użyta do zainicjalizowania właściwości widżetu. Skórka należy do klasy widżetu, a klasa widżetu może posiadać
wiele skórek identyfikowanych przez ich nazwę. Na przykład, możemy mieć skórkę dla widżetu CLinkPager nazwanej classic.

Aby móc skorzystać z funkcjonalności skórek musimy najpierw zmodyfikować konfigurację aplikacji poprzez zainstalowanie komponentu widgetFactory:

return array(
    'components'=>array(
        'widgetFactory'=>array(
            'class'=>'CWidgetFactory',
        ),
    ),
);

Następnie tworzymy potrzebne skórki. Skórki należa do tego samej klasy widżetu są przechowywane w pojedynczym skrypcie pliku, którego nazwa jest taka jak nazwa klasy widżetu. Wszystkie pliki skórek przechowywane są domyślnie w katalogu protected/views/skins. Jeśli chcesz zmienić go na inny katalog, możesz skonfigurować właściwość skinPath komponentu widgetFactory. Na przykład możemy stworzyć w katalogu protected/views/skins plik o nazwie CLinkPager.php, którego zawartość jest następująca:

<?php
return array(
    'default'=>array(
        'nextPageLabel'=>'&gt;&gt;',
        'prevPageLabel'=>'&lt;&lt;',
    ),
    'classic'=>array(
        'header'=>'',
        'maxButtonCount'=>5,
    ),
);

W powyższym przykładzie, utworzyliśmy skórki dla widżetu CLinkPager: domyślną default oraz klasyczną classic. Pierwsza skórka stosowana jest do wszystkich widżetów CLinkPager dla których nie określiliśmy bezpośrednio ich właściwości skin, gdy zaś druga jest skórką stosowaną do widżetu CLinkPager, którego właściwość skin jest określona jako classic. Na przykład, w następującym kodzie widoku, pierwszy pager będzie używał skórki default gdy zaś drugi użyje skórki classic:

<?php $this->widget('CLinkPager'); ?>
 
<?php $this->widget('CLinkPager', array('skin'=>'classic')); ?>

Jeśli utworzymy widżet wraz z zestawem inicjalnych wartości właściwości, będą one miały pierwszeństwo oraz zostaną złączone z każdą zastosowaną skórką. Na przykład, następujący kod widoku utworzy pager, którego inicjalne wartości będą tablicą array('header'=>'', 'maxButtonCount'=>6, 'cssFile'=>false), która jest wynikiem połączenia inicjalnych wartości właściwości określonych w widoku oraz skórki classic.

<?php $this->widget('CLinkPager', array(
    'skin'=>'classic',
    'maxButtonCount'=>6,
    'cssFile'=>false,
)); ?>

Zauważ, że funkcjonalność skórek nie wymaga stosowanie tematów. Jednakże, jeśli temat jest aktywny, Yii również będzie poszukiwało skórek w katalogu skins dla katalogu tematu widoku (np. WebRoot/themes/classic/views/skins). W przypadku gdy skórka o tej samej nazwie istnieje zarówno w temacie jak i w katalogach widoków głównej aplikacji, skórka tematu będzie miała pierwszeństwo.

Jeśli widżet używa skórki, która nie istnieje, Yii pomimo tego faktu utwoży widżet tak jak to czyni zazwyczaj, bez zgłaszani błędu.

Info: Używanie skórek może zmiejszyć wydajność, ponieważ Yii musi znaleźć
plik skórki gdy widżet jest tworzony po raz pierwszy.