Yii Framework Official Guide Series 44--Special topic: theming (Theme)

Theming is a systematic way to customize the appearance of Web pages in a Web application. By adopting a new theme, the overall appearance of the Web application can be changed immediately and dramatically.

In Yii, each topic is represented by a directory that contains view files, layout files, and related resource files, slices, CSS files, JavaScript files, and so on. The name of the subject is his directory name. All topics are placed in the same directory WebRoot/themes . At any time, only one theme can be activated.

Tip: The default theme root directory WebRoot/themes can be configured as a different one. You only need to configure the properties of the Thememanager app part basepath and BaseURL as the value you want.

To activate a theme, set the properties of the Web application theme to the name you want. It can be configured in the application configuration or modified in the controller's actions during execution.

Note: Subject names are case-sensitive. If you try to start a non-existent theme yii: , it :app()->theme will be returned null .

The content in the theme directory is organized in the same way as the application base path directory. For example, all view files must be located views under, Layout view files under views/layouts , and System view files under views/system . For example, if we want to replace PostController the create view file with the classic theme, we will save the new view file as WebRoot/themes/classic/views/post/create.php .

For the controller view file inside the module, the corresponding theme view file will be placed in the views directory. For example, if the above PostController is in a forum module named, we should save the create view file as WebRoot/themes/classic/views/forum/post/create.php . If forum the module is nested in another named support module, then the view file should be WebRoot/themes/classic/views/support/forum/post/create.php .

Note: Because views the directory may contain security-sensitive data, it should be configured to prevent access by network users.

When we call the render or renderpartial display view, the corresponding view file and layout file will be found in the currently active theme. If found, these files will be rendered by render. Otherwise, go back to the preset position specified by Viewpath and Layoutpath.

BaseURL property, we can generate the following URL for this image file,

Yii ">

Tip: In a topic view, we often need to link other theme resource files. For example, we may want to display an image file in the directory under the topic images . Using the BaseURL property of the currently active theme, we can generate the following URL for this image file.

Yii:: App ()->theme->baseurl. '/images/filename.gif '

Below is a example of directory organization for a application with both themes basic and 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

In the application configuration, if we configure

Return Array (    ' theme ' = ' basic ',    ...);

Then basic the theme would be in effect, which means the application ' s layout would use the one under the directory themes/basic/views/layouts , a nd the site ' s index view would use the one under themes/basic/views/site . In case a view file was not found in the theme, it would fall back to the one under the protected/views directory.

1. Theme Widgets

Starting from version 1.1.5, views used by a widgets can also be themed. In particular, if we callcwidget::render () to render a widget view, Yii would attempt to search under the theme folder as well as the Widget View folder for the desired view file.

To theme the "View xyz for a" widget whose class name Foo is, we should first create a folder named Foo (same as the WI Dget class name) under the currently active theme ' s view folder. If the Widget class is namespaced (available in PHP 5.3.0 or above), such as \app\widgets\Foo , we should create a folder named app_widgets_Foo . That's, we replace the namespace separators with the underscore characters.

We then create a view file named xyz.php under the newly created folder. To this end, we should has a file themes/basic/views/Foo/xyz.php , which be is used by the widgets to replace its original view, if the currently a Ctive Theme is basic .

2. Customizing global Widgets

Note: This feature has been available since version 1.1.3.

When using a widgets provided by third party or YII, we often need to customize it for specific needs. For example, we could want to a change of the value of Clinkpager::maxbuttoncount from ten (default) to 5. We can accomplish the passing the initial property values when calling Cbasecontroller::widget to create a widget. However, it becomes troublesome to doing so if we had to repeat the same customization in every place we useclinkpager.

$this->widget (' Clinkpager ', Array (    ' pages ' = = $pagination,    ' Maxbuttoncount ' =>5,    ' cssfile ' = >false,));

Using the global widget customization feature, we only need to specify these initial values in a single place, i.e., the A Pplication configuration. This makes the customization of widgets more manageable.

To use the Global Widget customization feature, we need to configure the widgetfactory as follows:

Return Array (' Components    ' =>array ('        widgetfactory ' =>array ('            widgets ' =>array (                ' Clinkpager ' =>array (                    ' Maxbuttoncount ' =>5,                    ' Cssfile ' =>false,                ),                ' cjuidatepicker ' = Array (                    ' language ' = ' ru ',),),),)    ;

In the above, we specify the global widgets customization for both Clinkpager and cjuidatepicker widgets by configuring the Cwidgetfactory::widgets property. Note the global customization for each widget was represented as a key-value pair in the array, where the key refers T o the Wiget class name while the value specifies the initial property value array.

Now, whenever we create a Clinkpager widget with a view, the above property values would be assigned to the widget, and we on Ly need to write the following code in the view to create the widget:

$this->widget (' Clinkpager ', Array (    ' pages ' = $pagination,));

We can still override the initial property values when necessary. For example, if in some view we want to set maxButtonCount to is 2, we can do the following:

$this->widget (' Clinkpager ', Array (    ' pages ' = = $pagination,    ' Maxbuttoncount ' =>2,));

3. Skin

Note: The skin feature has been available since version 1.1.0.

While using a theme we can quickly change the outlook for views, we can use skins to systematically customize the Outlook O f The widgets used in the.

A skin is an array of name-value pairs so can be used to initialize the properties of a widget. A skin belongs to a widget class, and a widget class can has multiple skins identified by their names. For example, we can has a skin for the Clinkpager widget and the skin is named as classic .

In order to use the skin feature, we first need to modify the application configuration by configuring Thecwidgetfactory:: Enableskin property to Bes True for the widgetFactory application component:

Return Array (' Components    ' =>array ('        widgetfactory ' =>array ('            enableskin ' =>true,        ),    ),);

Please note this in versions prior to 1.1.3, the following configuration to enable widget skinning:

Return Array (' Components    ' =>array ('        widgetfactory ' =>array ('            class ' = ' cwidgetfactory        '), ),    ),);

We then create the needed skins. Skins belonging to the same widget class was stored in a single PHP script file whose name is the widget class name. All these skin files is stored under protected/views/skins , by default. If you want-to-different directory, you may configure the property of the skinPath widgetFactory component. As an example, we could create under protected/views/skins a file named CLinkPager.php whose content is as follows,

<?phpreturn Array ('    default ' =>array ('        nextpagelabel ' = ' &gt;&gt; ',        ' prevpagelabel ' = > ' &lt;&lt; ', '    Classic ' =>array (        ' header ' = ' ",        ' Maxbuttoncount ' =>5,    ) ,);

In the above, we create a skins for the Clinkpager widget: default and classic . The former is the skin of that would be a applied to any clinkpager widgets that we don't explicitly specify its property skin While the latter are the skin to being applied to a Clinkpager widgets whose property is skin specified as classic . For example, the following view code, the first pager would use the skin while the default second the classic skin:

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

If we create a widget with a set of initial values, they'll take precedence and is merged with any applicable s Kin. For example, the following view code would create a pager whose initial values would be array('header'=>'', 'maxButtonCount'=>6, 'cssFile'=>false) , which is the result of merging The initial property values specified in the view and the classic skin.

<?php $this->widget (' Clinkpager ', array (    ' skin ' = ' classic ',    ' Maxbuttoncount ' =>6,    ' Cssfile ' =>false,));?>

Note that the skin feature does not require using themes. However, when a theme is active, Yii would also look for skins under the skins directory of the theme ' s view directory (e.g .WebRoot/themes/classic/views/skins). In case a skins with the same name exists in both the theme and the main application view directories, the theme skin would Take precedence.

If a widget is using a skin, which does not exist, Yii would still create the widget as usual without any error.

Info: Using skin may degrade the performance because YII needs-look for the skins file the first time a widget is being create D.

Skin is very similar to the Global Widget customization feature. The main differences is as follows.

• Skin is more related with the customization of presentational property values;

• A widget can have multiple skins;

• Skin is themeable;

• The using skin is the more expensive than using global widget customization.

The above is the Yii Framework Official Guide Series 44--topic: theming (Theme) content, more relevant content please pay attention to topic.alibabacloud.com (www.php.cn)!

