Helper usage

h2. Integrating with your application

To integrate AssetCompress with your CakePHP application, first download and install the plugin, and create an ini file. Once you have an ini file you can load the helper and start compressing some assets.

pre.. public $helpers = array( 'AssetCompress.AssetCompress' );

p. After adding the helper to your $helpers array, you use it in your views to link assets together into target build files. The two methods for doing this are @css()@ and @script()@. Much like their @HtmlHelper@ counter parts, these methods allow you to link files into your pages. However, they also allow you to specify the target build file. All files added to a 'build' file will be compressed together into one file. Each build file will be delivered as a separate asset. Files in build files will be combined in the order you add them. I normally add files from the view into one build file, and files from the layout or application global files into another build file. This minimizes the number of HTTP request made but still allows you to minimize each files size. In the head of my layout I do the following:

pre.. $assetCompress->css('base'); $assetCompress->css('geshi');

$assetCompress->script('mootools_packed');
$assetCompress->script('mootools_more_packed');
$assetCompress->script('mark-story');
$assetCompress->script('hashgrid');

echo $assetCompress->includeAssets();
echo $scripts_for_layout;

p. This will create a @default.css@ and @default.js@ containing the concatenation and processed versions of the files linked in.

h3. Auto include view and controller Javascript files

The AssetCompressHelper can also automatically include view and controller specific javascript files. You can disable this behaviour by setting @$assetCompress->autoInclude = false;@ from your views. When enabled it will attempt to include a underscored version of the controller and action name from @WEBROOT/js/views/@ with the build target of @$controller_$action.js@. You will also need to have @WEBROOT/js@ in your ini file's @searchPaths@ for this feature to work. View file specific Javascript should be place in a directory that is named after the underscored inflection of the controller name. If your controller is called @NinjaTurtlesController@ you files should be in @ninja_turtles/@.

h3. Timestampping assets made with AssetCompress

By adding @timestamp = true@ to either the @[Javascript]@ or @[Css]@ sections in your ini file, you can enable build file timestampping. Timestamps on build files provide an easy way to invalidate browser caching, as the file names change when the build time file is updated. Unlike some implementation of timestampped assets, AssetCompress does not use the filemtime of the files. Instead it uses a special @asset_compress_build_timestamp@ file in @app/tmp@. This file contains the timestamp of the cache file purge. This was done because both the helper and the models that generate the cache files needed a way to agree on the timestamp to use. You can clear the timestamp using either the @clearBuildTimestamp()@ method on either model, or using the @asset_compress@ console tool.