Yii Framework official guide series 44-topics: Theming)

Theming is a system that customizes the appearance of a webpage in a Web application. By adopting a new theme, the overall appearance of Web applications can be changed immediately and dramatically. In Yii, each topic is represented by a directory, including view...

Theming is a system that customizes the appearance of a webpage in a Web application. By adopting a new theme, the overall appearance of Web applications can be changed immediately and dramatically.

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

Tip: default topic root directoryWebRoot/themesCan be configured as other. You only need to configure the attributes basePath and baseUrl of the themeManager application for the value you want.

To activate a topic, set the theme attribute of the Web application to your desired name. It can be configured in application configuration or modified in the controller action during execution.

Note: topic names are case sensitive. If you try to start a topic that does not exist,yii: :app()->themeReturnsnull.

The content in the topic directory is organized in the same way as that in the application base path directory. For example, all view files must be located inviewsInviews/layoutsAnd the system view file inviews/system. For example, if we want to replacePostControllerOfcreateThe view file isclassicUnder the topic, we will save the new view fileWebRoot/themes/classic/views/post/create.php.

For the controller view file in the module, the corresponding topic view file will be placedviewsDirectory. For example, ifPostControllerIs namedforumIn the module, we should savecreateThe view file isWebRoot/themes/classic/views/forum/post/create.php. IfforumThe module is nested in anothersupportModule, the view file should beWebRoot/themes/classic/views/support/forum/post/create.php.

Note:viewsThe directory may contain sensitive and secure data and should be configured to prevent access by network users.

When we call render or renderPartial to display the view, the corresponding view file and layout file will be searched for in the currently active topic. If any, these files will be rendered by render. Otherwise, the system returns to the default position specified by viewPath and layoutPath.

Baseurl attribute, we can generate the following url for this image file,

yii">

Tip: in a topic view, we often need to link other topic resource files. For example, we may want to display a topicimagesThe image file in the directory. Using the baseurl attribute of the currently activated topic, we can generate the following url for this image file,

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

Below is an example of directory organization for an application with two themesbasicAndfancy.

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',    ......);

ThenbasicTheme will be in effect, which means the application's layout will use the one under the directorythemes/basic/views/layouts, And the site's index view will use the one underthemes/basic/views/site. In case a view file is not found in the theme, it will fall back to the one underprotected/viewsDirectory.

1. theme pendant

Starting from version 1.1.5, views used by a widget can also be themed. in particle, when we callCWidget: render () to render a widget view, Yii will attempt to search under the theme folder as well as the widget view folder for the desired view file.

To theme the viewxyzFor a widget whose class name isFoo, We shoshould first create a folder namedFoo(Same as the widget class name) under the currently active theme's view folder. If the widget class is namespaced (available in PHP 5.3.0 or abve), such\app\widgets\Foo, We shoshould create a folder namedapp_widgets_Foo. That is, we replace the namespace separators with the underscore characters.

We then create a view file namedxyz.phpUnder the newly created folder. To this end, we shocould have a filethemes/basic/views/Foo/xyz.php, Which will be used by the widget to replace its original view, if the currently active theme isbasic.

2. customize global pendants

Note:This feature has been available since version 1.1.3.

When using a widget provided by third party or Yii, we often need to customize it for specific needs. for example, we may want to change the value of CLinkPager: maxButtonCount from 10 (default) to 5. we can accomplish this by passing the initial property values when calling CBaseController: widget to create a widget. however, it becomes troublesome to do so if we have 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 application 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 widget customization for both CLinkPager and CJuiDatePicker widgets by grouping the CWidgetFactory: widgets property. note that the global customization for each widget is represented as a key-value pair in the array, where the key refers to the wightet class name while the value specifies the initial property value array.

Now, whenever we create a CLinkPager widget in a view, the above property values will be assigned to the widget, and we only 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 setmaxButtonCountTo be 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 of views, we can use skins to systematically customize the outlook of the widgets used in the views.

A skin is an array of name-value pairs that can be used to initialize the properties of a widget. A skin belongs to a widget class, and a widget class can have multiple skins identified by their names. for example, we can have a skin for the CLinkPager widget and the skin is namedclassic.

In order to use the skin feature, we first need to modify the application configuration by processing ing theCWidgetFactory: enableSkin property to be true forwidgetFactoryApplication component:

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

Please note that in versions prior to 1.1.3, you need to use 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 are stored in a single PHP script file whose name is the widget class name. All these skin files are stored underprotected/views/skins, By default. If you want to change this to be a different directory, you may configureskinPathProperty ofwidgetFactoryComponent. As an example, we may create underprotected/views/skinsA file namedCLinkPager.phpWhose content is as follows,

 array(        'nextPageLabel'=>'>>',        'prevPageLabel'=>'<<',    ),    'classic'=>array(        'header'=>'',        'maxButtonCount'=>5,    ),);

In the above, we create two skins for the CLinkPager widget:defaultAndclassic. The former is the skin that will be applied to any CLinkPager widget that we do not explicitly specify itsskinProperty, while the latter is the skin to be applied to a CLinkPager widget whoseskinProperty is specifiedclassic. For example, in the following view code, the first pager will usedefaultSkin while the secondclassicSkin:

 widget('CLinkPager'); ?>
 widget('CLinkPager', array('skin'=>'classic')); ?>

If we create a widget with a set of initial property values, they will take precedence and be merged with any applicable skin. for example, the following view code will create a pager whose initial values will bearray('header'=>'', 'maxButtonCount'=>6, 'cssFile'=>false), Which is the result of merging the initial property values specified in the view andclassicSkin.

 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 will also look for skins underskinsDirectory of the theme's view directory (e.g.WebRoot/themes/classic/views/skins). In case a skin with the same name exists in both the theme and the main application view directories, the theme skin will take precedence.

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

Info:Using skin may degrade the performance because Yii needs to look for the skin file the first time a widget is being created.

Skin is very similar to the global widget customization feature. The main differences are as follows.

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

• A widget can have multiple skins;

• Skin is themeable;

• Using skin is more expensive than using global widget customization.

The above is the Yii Framework official guide series 44-topic: Theming (Theming) content. For more information, see PHP Chinese website (www.php1.cn )!