-
Notifications
You must be signed in to change notification settings - Fork 125
Helper usage
The AssetCompressHelper allows you to easily link to and define build files in your views. First start off by linking the helper in your Controller:
<?php
public $helpers = array(
'AssetCompress.AssetCompress'
);
After adding the helper to your $helpers
array, you can use the helper in two ways. First, you can link to build files defined in your Configuration file. Second, you can use the helper to define dynamic build files, that can then be linked into your HTML.
Once you've defined build files, either through the Configuration file, or as dynamic build files, you can output the HTML tags that link the assets to your page. $this->AssetCompress->css()
and $this->AssetCompress->script()
let you create those tags.
<?php
echo $this->AssetCompress->css('site.css', $options);
echo $this->AssetCompress->script('libs.js', $options);
Both of these methods work in a similar way. If asset caching is disabled, a compressed asset is generated on the fly using the built-in controller. If asset caching is enabled, and the helper is able to locate the generated build file, it will link to that file instead. This process is transparent, and depends on the Configuration values set. $options
allows you to set any attributes on the generated tag, and includes the special key raw
.
If you need to generate Asset tags with URL's with the host name you can use the full option:
<?php
echo $this->AssetCompress->css('site.css', array('full' => true));
echo $this->AssetCompress->script('libs.js', array('full' => true));
Sometimes when you are having trouble debugging an issue, its helpful to include all the component files for a build file. You can use the raw
option to force the helper to generate tags pointing to all the parts of build file instead of the build file:
<?php
echo $this->AssetCompress->css('site.css', array('raw' => true));
If site.css had been defined as using the following files:
- reset.css
- grid.css
- styles.css
The above call, would generate 3 <link />
tags.
Note including 'raw' assets will skip all processing steps, so files that need a pre-processing step applied, may not work correctly.
When quickly building out features, or testing whether or not a new build file will help performance, its often useful to define build files on the fly in your views. You can do this using the 'addCss()', and 'addScript()' methods:
<?php
$this->AssetCompress->addScript(array('jquery.js', 'jquery-ui.js'), 'jquery-combined.js');
This will create a new build file called jquery-combined.js
and the result will be the two files combined. You can choose to omit the build file name as well, and an md5 of the component filenames will be used.
<?php
$this->AssetCompress->addScript(array('jquery.js', 'jquery-ui.js'));
By default AssetCompress merges everything into a single build file called :hash-default
. This is a magic build file whose name will be the md5() of all the filenames included in it. You can also create your own magic build files by prefixing the build target with :hash-
.
Note: The addCss()
method works the same as addScript()
.
Once you've defined some build files in your views, you will probably want to include them in either the head or bottom of the body in your layout. Since you may or may not know the names of the build files - due to md5 names. There are generic methods to include all dynamically defined build files:
<?php
echo $this->AssetCompress->includeJs();
echo $this->AssetCompress->includeCss();
You can also include all of the runtime defined assets - both javascript and css - using
$this->AssetCompress->includeAssets()
. The result of these methods is one file for each build file declared using addCss()
and addScript()
. Files defined in the Configuration file will not be included using includeJs
, includeCss
, or includeAssets
.will create a css file with hash of the included css files, and a javascript file named after the hash of the include javascript files. These files will contain the concatenation and processed versions of the files linked.
Here's a slightly more detailed example involving CakePHP layout (.ctp) files, while conforming to the Yahoo Best Practices (YSlow) guidelines which promote the loading of external scripts AFTER the page content has been loaded::
<?php
// Combine & Minify CSS
$this->AssetCompress->addCss('style');
$this->AssetCompress->addCss('jquery-ui');
// Combine & Minify JS
$this->AssetCompress->addScript('jquery/jquery.min');
$this->AssetCompress->addScript('jquery/plugins/jquery-ui.min');
echo $html->docType('xhtml-trans');
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title><?php echo $title_for_layout ?></title>
<?php echo $this->AssetCompress->includeCss(); ?>
<?php echo $html->meta( 'icon', $html->url( '/favicon.ico' ) ); ?>
</head>
<body>
<?php
echo $content_for_layout;
echo $this->AssetCompress->includeJs();
echo $scripts_for_layout;
echo $this->Js->writeBuffer(); // Any Buffered Scripts
?>
</body>
</html>
Note Dynamic build files will only work through the controller while debug > 0. Before deploying you should run the shell to generate static assets.
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 paths[]
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
your files should be in ninja_turtles/
.