0 follower

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

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

В 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 повинен знайти файл скіна, коли віджет створюється вперше.

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

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

Found a typo or you think this page needs improvement?
Edit it on github !