Theming is a systematic way of customizing the outlook of pages in a Web application. By applying a new theme, the overall appearance of a Web application can be changed instantly and dramatically.
In Yii, each theme is represented as a directory consisting of view files,
layout files, and relevant resource files such as images, CSS files,
JavaScript files, etc. The name of a theme is its directory name. All
themes reside under the same directory WebRoot/themes
. At any time, only
one theme can be active.
Tip: The default theme root directory
WebRoot/themes
can be configured to be a different one. Simply configure the basePath and the baseUrl properties of the themeManager application component to be the desired ones.
To activate a theme, set the theme property of the Web application to be the name of the desired theme. This can be done either in the application configuration or during runtime in controller actions.
Note: Theme name is case-sensitive. If you attempt to activate a theme that does not exist,
Yii::app()->theme
will returnnull
.
Contents under a theme directory should be organized in the same way as
those under the application base
path. For example, all view files
must be located under views
, layout view files under views/layouts
, and
system view files under views/system
. For example, if we want to replace
the create
view of PostController
with a view in the classic
theme,
we should save the new view file as WebRoot/themes/classic/views/post/create.php
.
For views belonging to controllers in a module,
the corresponding themed view files should also be placed under the views
directory. For example, if the aforementioned PostController
is in a module
named forum
, we should save the create
view file as WebRoot/themes/classic/views/forum/post/create.php
. If the forum
module
is nested in another module named support
, then the view file should be
WebRoot/themes/classic/views/support/forum/post/create.php
.
Note: Because the
views
directory may contain security-sensitive data, it should be configured to prevent from being accessed by Web users.
When we call render or renderPartial to display a view, the corresponding view file as well as the layout file will be looked for in the currently active theme. And if found, those files will be rendered. Otherwise, it falls back to the default location as specified by viewPath and layoutPath.
Tip: Inside a theme view, we often need to link other theme resource files. For example, we may want to show an image file under the theme's
images
directory. Using the baseUrl property of the currently active theme, we can generate the URL for the image as follows,Yii::app()->theme->baseUrl . '/images/FileName.gif'
Below is an example of directory organization for an application with two 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 the basic
theme will be in effect, which means the application's layout will use
the one under the directory themes/basic/views/layouts
, and the site's index view will
use the one under themes/basic/views/site
. In case a view file is not found in the theme,
it will fall back to the one under the protected/views
directory.
Signup or Login in order to comment.