Theming your Zii Widgets

One aspect of User Interface Design has to do with the coherence of the design and the use of the colors between the different User Interface Components used.

Normally a site or web application is designed with a specific aesthetic, and normally obeys to the identity of the application.

Yii offers a way to integrate User Interface Controls named Zii Widgets, based on JQuery UI to our applications, but they come with a default design.

This design can be easily changed with a series of simple steps, that were told by Sebas to me.

We have searched several times on the site, the forum, tutorials, but couldn't find a specific place where you could get this information, in a simple and effective way.

That's why I decided to share this acquired knowledge, passed by Sebas, and written by me.

1 - Create a Zii Widgets Design 

Every Zii Widgets use JQuery UI.

The easiest form is to use the tool provided by JQuery UI to create the designs or "themes" that better fit our web application.

We have to navigate to JQuery UI Theme Roller, and play with it until we get our own design.

Once we did that, we have to download the "theme". Theme Roller asks you to select the version. Version 1.8.6 was available when the article was written, and is compatible with Yii 1.1.5.

2 - Include the necessary files into Yii 

The next step is to copy the necessary files in one of the public folders of our application: the created resources, CSS and images, will be used by Zii Widgets (JQuery UI) to give our configured theme to our user interface.

In my case, I created a 'jqueryui' folder inside css: /css/jqueryui This folder will be assigned to CJuiWidget's property themeUrl.

Then I created an other folder, with the name of the theme I want to use, in my case, 'fc'. The name of this folder will be assigned to CJuiWidget's property theme.

Then, inside fc folder (or the name you used for your theme), you have to copy some of the files inside the archive you downloaded from Theme Roller.

It is only necessary to copy the files inside the /css/custom-theme/ folder into the 'fc' folder.

Finally, you have to change the filename of the CSS file, from 'jquery-ui-1.8.6.custom.css', to 'jquery-ui.css'.

3 - Configure the Zii Widget components to use our "theme" 

The last step involves configuring the Zii Widget components, so that they use the theme.

Each component needs to be configured. The best way is to do it in the main configuration file: /protected/config/main.php

Following is a sample of my configuration:

$config = array(
'components' => array(
        // enables theme based JQueryUI's
        'widgetFactory' => array(
            'widgets' => array(
                'CJuiAutoComplete' => array(
                    'themeUrl' => '/css/jqueryui',
                    'theme' => 'fc',
                ),
                'CJuiDialog' => array(
                    'themeUrl' => '/css/jqueryui',
                    'theme' => 'fc',
                ),
                'CJuiDatePicker' => array(
                    'themeUrl' => '/css/jqueryui',
                    'theme' => 'fc',
                ),
            ),
        ),

This way, the three components, CJuiAutoComplete, CJuiDialog and CJuiDatePicker, will use the defined theme.