Yii: Including resources into the page

Yii has a special class named CClientScript that can help to include scripts, CSS, and other resources into the page.

How to do it...

We will start with including a script. There are three types of scripts, namely, external scripts, core scripts, and inline scripts.

1. External script is a script located in a file and accessible through its own URL. For example, to include a script with URL http://example.com/js/main.js, you can use the following code:

Yii::app()->clientScript->registerScriptFile("http://example.com/js/main.js");

2. In order to control the place where script will be inserted, you can pass one of the following constants as the second parameter:

CClientScript::POS_HEAD	In the head section right before the title element
CClientScript::POS_BEGIN	At the beginning of the body section
CClientScript::POS_END	At the end of the body section

3. Core scripts are the ones bundled with Yii, such as jQuery. You can include a core script in the following way:

Yii::app()->clientScript->registerCoreScript('jquery');

4. All packages are listed in framework/web/js/packages.php:

return array(
            'jquery' => array(
                'js' => array(YII_DEBUG ? 'jquery.js' : 'jquery.min.js'),
            ),
            'yii' => array(
                'js' => array('jquery.yii.js'),
                'depends' => array('jquery'),
            ),
            'yiitab' => array(
                'js' => array('jquery.yiitab.js'),
                'depends' => array('jquery'),
            ),
            'yiiactiveform' => array(
                'js' => array('jquery.yiiactiveform.js'),
                'depends' => array('jquery'),
            ),
            'jquery.ui' => array(
                'js' => array('jui/js/jquery-ui.min.js'),
                'depends' => array('jquery'),
            ),
            ...
        );

5. In this list, keys of the array such as jquery, yii, yiitab, yiiactiveform are the names you can use with registerClientScript and the corresponding arrays are the real script file names relative to framework/web/js/source that are actually loaded.
6. Inline scripts are the scripts contained in a page body. Typically, these are ones different at every request. You can include these type of scripts in the following way:

Yii::app()->clientScript->registerScript('myscript', 'echo "Hello, world!";', CClientScript::POS_READY);

The first parameter is the unique script ID you have chosen. The second parameter is the script itself. The third one tells Yii where to include a script. Additionally there are two more positions to ones used for registerScriptFile:

CClientScript::POS_LOAD	In the window.onload() function
CClientScript::POS_READY	In the jQuery's ready function

Now, let's move on to CSS. There are two types of CSS: inline and external (no core type this time).

1. In order to include an external CSS, you can use the following code:

Yii::app()->clientScript->registerCssFile('http://example.com/css/main.css');

Additionally, this method takes a second parameter which allows you to specify which media type you want to include CSS for, such as screen or print. There is no position parameter, as the only valid place to include a CSS is inside a head tag. Inline CSS should be avoided wherever possible, but in case you really need it, you can include it in the following way:

Yii::app()->registerCss('myCSS', 'body {margin: 0; padding: 0}', 'all');

2. In the preceding code, myCSS is the unique ID. Then, we have the actual CSS code and a media type.

How it works...

The Yii's CClientScript methods which we have reviewed do not include scripts and CSS instantly. Instead, resources are stored until application controller calls the render method. Then, it finds a proper place in layout and inserts all needed script and CSS blocks and tags. If we include a resource with the same name or URL twice, then it will be included only once. This allows us to efficiently use resources in a widget, view partial, or any reusable piece of code.

There's more...

We have reviewed the most common resource types: JavaScript and CSS. However, there is more.

Using custom script packages

While using Yii, you can leverage package features to manage script dependencies in the same way core dependencies are managed. The feature is described well at the following API page:

http://www.yiiframework.com/doc/api/CClientScript#packages-detail

Registering linked resources

Yii::app()->clientScript->registerLinkTag(
                'alternate', 'application/rss+xml', $this->createUrl('rss/articles')
        );

CClientScript offers another method that allows you to register a custom <link tag. For example, it can be useful to add an RSS link for a specific controller action as follows:

Registering meta tags

In addition, CClientScript allows registering of meta tags such as description or keywords by using the registerMetaTag method. For example, in order to specify a document encoding, you can use the following code:

Yii::app()->clientScript->registerMetaTag(' text/html;charset=utf-8', null, 'Content-Type');

Further reading

For further information, refer to the following URLs:

• http://www.yiiframework.com/doc/api/CClientScript
• http://www.yiiframework.com/doc/guide/1.1/en/topics.performance

Categories: PHP and Yii