TClientScriptLoader

The TClientScriptLoader publish a collection of javascript files as assets. For example, suppose we have a directory name "mylib" in the protected/pages directory of our application.

assets/ protected/ pages/ mylib/ file1.js file2.js file3.js file4.js packages.php

The PackagePath property can be an existing asset directory or a namespace path to the directory containing javascript files. For example, to publish the javascript files in the mylib directory, we can specify the PackagePath as follows. The first tag TClientScriptLoader relies on the asset template tag and assumes that the page template containing the TClientScriptLoader tag instance is in the protected/pages directory. The second TClientScriptLoader tag uses the namespace notation to specify the path.

<com:TClientScriptLoader PackagePath=<%~ mylib %> /> <com:TClientScriptLoader PackagePath="Application.pages.mylib" />

When the files in the PackagePath are published as assets, a script loader php file "clientscripts.php" is automatically copied to that asset directory. The script loader, combines multiple javascript files and serve up as gzip if possible.

Grouping Javascript Files

Allowable scripts and script dependencies can be grouped by using a "packages.php" file with the following format. This "packages.php" is optional, if absent the file names without ".js" extension are used. The "packages.php" must be in the directory given by PackagePath.

<?php $packages = array( 'package1' => array('file1.js', 'file2.js'), 'package2' => array('file3.js', 'file4.js')); $deps = array( 'package1' => array('package1'), 'package2' => array('package1', 'package2')); //package2 requires package1 first. return array($packages,$deps); //must return $packages and $deps in an array ?>

The first element of the array returned by the packages.php should contain an array of javascripts files relative to the packages.php that corresponds to a particular grouping. For example, in the above packages.php, the grouping 'package1' combines two javascript files, namely, 'file1.js' and 'file2.js'.

The second element of the array returned by the packages.php should contain an array of grouping dependencies ordered in the way that the groups should be combined. For example, grouping 'package1' only depends on the 'package1' grouping files (i.e. 'file1.js' and 'file2.js'). While 'package2' depends on both 'package1' and 'package2' groupings. That is, 'package2' will combine, in order, 'file1.js', 'file2.js', 'file3.js', and 'file4.js'.

Loading Javascript Packages

To load a particular javascript file or package, set the PackageScripts property with value 'package1' to load the 'package1' scripts. A maximum of 25 packages separated by commas is allowed. Dependencies of the packages are automatically resolved by the script loader php file.

<com:TClientScriptLoader PackagePath=<%~ mylib %> PackageScripts="package2" /> <script type="text/javascript"> //javascript code utilizing javascript code loaded in 'package2' above </script>

Each <com:TClientScriptLoader> generates an HTML <script> element to load the required javascript files.

Removing Javascript Comments

The DebugMode property when false removes comments and white spaces from the published javascript files. If the DebugMode property is not set, the debug mode is determined from the application mode.

Note: If the DebugMode is false either explicitly or when the application mode is non-debug, then cache headers are also sent to inform the browser and proxies to cache the file. Moreover, the post-processed (comments removed and zipped) are saved in the assets directory for the next requests. That is, in non-debug mode the scripts are cached in the assets directory until they are deleted.

Compressing Javascript with GZip

The EnableGzip property (default is true) enables the published javascripts to be served as zipped if the browser and php server allows it.

$Id: ClientScript.page 1650 2007-01-24 06:55:32Z wei $