Теми оформлення

Теми оформлення є традиційним способом налаштувати зовнішній вигляд сторінок веб-додатку. Застосувавши нову тему, ми можемо змінити зовнішній вигляд всього додатка за лічені секунди.

В Yii кожна тема представлена ​​як папка, що містить файли представлень, макетів та інших необхідних файлів, таких, як CSS, JavaScript та ін. Назва папки відповідно визначає назву теми. Всі теми зберігаються у папці WebRoot/themes, при цьому бути активною, тобто використовуватися у поточний момент, може тільки одна з тем.

Підказка: Папку, де за замовчуванням зберігаються теми — WebRoot/themes — можна легко змінити шляхом встановлення властивостей basePath та baseUrl компонента themeManager на бажані.

1. Використання теми ¶

Для активації теми потрібно встановити значення theme рівним імені відповідної теми. Це можна проробити шляхом конфігурації додатку або прямо під час виконання у діях контролера.

Примітка: Імʼя теми чутливо до регістру, і, якщо спробувати активувати неіснуючу тему, властивість Yii::app()->theme поверне null.

2. Створення теми ¶

Вміст папки з темами повинен бути організований точно так само, як і вміст базової директорії додатку, тобто, всі файли представлень повинні знаходитися у папці views, макети представлень у папці views/layouts, а файли системних представлень у папці views/system. Наприклад, якщо необхідно замінити представлення create контролера PostController на представлення теми classic, потрібно зберегти новий файл представлення як WebRoot/themes/classic/views/post/create.php.

Для представлень контролерів у модулях, відповідні файли оформлених представлень потрібно також помістити у папку views. Наприклад, якщо згаданий вище контролер PostController входить у модуль forum, необхідно зберегти файл представлення create як WebRoot/themes/classic/views/forum/post/create.php. Якщо модуль forum є складовою частиною іншого модуля support, то файл представлення повинен бути збережений як WebRoot/themes/classic/views/support/forum/post/create.php.

Примітка: Папка views може містити чутливі дані, з точки зору безпеки, тому необхідно обмежити доступ до папки ззовні сервера.

У момент виклику методу render або renderPartial для відображення представлення відбувається звернення до відповідних файлів представлень і макетів активної теми. Якщо файли знайдені, почнеться формування сторінки, у противному випадку, будуть використовуватися файли оформлення за замовчуванням, місце розташування яких встановлюється властивостями viewPath та layoutPath.

Підказка: Часто у представленнях теми доводиться посилатися на інші файли теми, наприклад, для відображення картинки, що знаходиться у папці теми images. Використовуючи властивість baseUrl активної теми, можна сформувати коректне посилання на зображення наступним чином:

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

Нижче наведено приклад організації директорій додатку з двома темами basic та fancy:

WebRoot/
    assets
    protected/
        .htaccess
        components/
        controllers/
        models/
        views/
            layouts/
                main.php
            site/
                index.php
    themes/
        basic/
            views/
                .htaccess
                layouts/
                    main.php
                site/
                    index.php
        fancy/
            views/
                .htaccess
                layouts/
                    main.php
                site/
                    index.php

У налаштуваннях додатку, якщо ми будемо використовувати:

return array(
    'theme'=>'basic',
    …
);

то буде застосовуватися тема basic. Тобто головний макет (layout) буде братися з themes/basic/views/layouts, а представлення index — із themes/basic/views/site. Якщо файл представлення не знайдений у темі, буде використаний файл з protected/views.

3. Темізація віджетів ¶

Починаючи з версії 1.1.5, представлення, які використовуються у віджетах, можна темізувати. При виклику CWidget::render() для виведення представлення, Yii зробить спробу знайти його у темах перед тим, як завантажити з директорії віджету.

Для темізаціі представлення xyz віджета з імʼям класу Foo, необхідно створити директорію Foo (з тим же імʼям, що і у класу) усередині директорії з представленнями активної теми. Якщо клас віджету знаходиться у просторі імен (починаючи з PHP 5.3.0), такому як \app\widgets\Foo, то необхідно створити директорію app_widgets_Foo. В імені ми замінюємо роздільники простору імен на підкреслення.

Після цього створюємо файл представлення xyz.php у щойно доданої директорії. До цього моменту ми маємо файл themes/basic/views/Foo/xyz.php, який і буде використовуватися віджетом замість його власного представлення, якщо активна тема — basic.

4. Глобальне налаштування віджетів ¶

Примітка: дана можливість доступна з версії 1.1.3.

При використанні віджета, як стандартного, так і стороннього, часто потрібно його налаштування. Наприклад, може знадобитися змінити значення CLinkPager::maxButtonCount з 10 (за замовчуванням) на 5. Ми можемо зробити це, передавши початкові значення при виклику CBaseController::widget для створення віджета. Проте, робити це скрізь, де ми використовуємо CLinkPager досить незручно.

$this->widget('CLinkPager', array(
    'pages'=>$pagination,
    'maxButtonCount'=>5,
    'cssFile'=>false,
));

При використанні глобального налаштування, необхідно вказати початкові значення лише у одному місці — у файлі конфігурації додатка. Для цього налаштовуємо widgetFactory наступним чином:

return array(
    'components'=>array(
        'widgetFactory'=>array(
            'widgets'=>array(
                'CLinkPager'=>array(
                    'maxButtonCount'=>5,
                    'cssFile'=>false,
                ),
                'CJuiDatePicker'=>array(
                    'language'=>'ru',
                ),
            ),
        ),
    ),
);

Вище ми вказали глобальні налаштування віджетів CLinkPager та CJuiDatePicker за допомогою відповідних властивостей CWidgetFactory::widgets. Варто відзначити, що глобальні налаштування вказуються у вигляді пар ключ-масив значень, де ключ відповідає класу віджета, а масив значень задає початкові значення властивостей цього класу.

Тепер кожного разу, коли ми використовуємо віджет CLinkPager у представленні, його властивостям будуть присвоєні зазначені вище початкові значення. Таким чином, щоб використовувати віджет буде достатньо наступного коду:

$this->widget('CLinkPager', array(
    'pages'=>$pagination,
));

Ми можемо перевизначити початкові значення, якщо у цьому є необхідність. Приміром, якщо у якомусь представленні ми хочемо задати maxButtonCount рівним 2, можна зробити наступне:

$this->widget('CLinkPager', array(
    'pages'=>$pagination,
    'maxButtonCount'=>2,
));

5. Скіни ¶

У той час, як при використанні теми ми можемо швидко змінювати вигляд представлень, ми також можемо використовувати скіни для налаштування вигляду віджетів, що використовуються у представленнях.

Скін — це масив пар імʼя-значення, який може використовуватися для ініціалізації властивостей віджету. Скін належить до класу віджета, а клас віджета може мати кілька скінів, ідентифікованих іменем. Наприклад, у нас може бути скін classic для віджета CLinkPager.

Для використання даної можливості нам, в першу чергу, необхідно змінити файл конфігурації додатку, виставивши властивість CWidgetFactory::enableSkin компонента widgetFactory у true:

return array(
    'components'=>array(
        'widgetFactory'=>array(
            'enableSkin'=>true,
        ),
    ),
);

У версіях Yii до 1.1.3 необхідно використовувати наступну конфігурацію:

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

Потім ми створюємо необхідні скіни. Скіни, що належать одному класу віджета, зберігаються у одному файлі PHP, імʼя якого збігається із назвою класу віджету. Всі файли скінів за замовчуванням зберігаються у директорії protected/views/skins. Для зміни директорії необхідно налаштувати властивість skinPath компонента widgetFactory. Наприклад, ми можемо створити у директорії protected/views/skins файл CLinkPager.php, код якого поданий нижче:

<?php
return array(
    'default'=>array(
        'nextPageLabel'=>'next',
        'prevPageLabel'=>'prev',
    ),
    'classic'=>array(
        'header'=>'',
        'maxButtonCount'=>5,
    ),
);

У коді вище ми створюємо для віджету CLinkPager два скіни: default та classic. Перший скін буде застосовуватися до будь-якого віджету CLinkPager, у якого явно не вказана властивість skin, а другий — до віджету, властивість skin якого має значення classic. Наприклад, у наступному коді представлення першим віджет буде використовувати скін default, а другий — скін classic:

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

Якщо ми створюємо віджет з набором первинних значень, вони будуть мати пріоритет і будуть обʼєднані з будь-якими застосовуваними скінами. Наприклад, наступний код представлення створить посторінкову розбивку, чиї початкові значення — це масив array('header'=>'', 'maxButtonCount'=>6, 'cssFile'=>false), який є результатом злиття первинних значень, зазначених у представленні, і скіна classic.

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

Зауважимо, що скінізація НЕ вимагає використання теми. Однак, якщо тема активна, Yii також буде шукати скіни у директорії skins представлень теми (наприклад, WebRoot/themes/classic/views/skins). У випадку, якщо скін з таким же імʼям існує і у директорії представлення теми і у основній директорії представлення додатку, скін теми буде мати пріоритет.

Якщо віджет використовує неіснуючий скін, Yii як і раніше буде створювати віджет як звичайно, без будь-яких помилок.

Інформація: Використання скіна може привести до зниження продуктивності, оскільки Yii повинен знайти файл скіна, коли віджет створюється вперше.

Використання скінів дуже схоже на глобальну конфігурацію віджетів. Головні відмінності наступні:

• Скіни більшою мірою відносяться до зміни властивостей, що відповідають за зовнішній вигляд віджету;
• У віджета може бути кілька скінів;
• Скін можна темізувати;
• Використання скінів більш затратно, ніж використання глобальної конфігурації.