kekrozsak/vendor/kriswallsmith/assetic/docs/en/define.md
Polonkai Gergely 082a0130c2 Initial commit with Symfony 2.1+Vendors
Signed-off-by: Gergely POLONKAI (W00d5t0ck) <polesz@w00d5t0ck.info>
2012-07-01 09:52:20 +02:00

146 lines
5.2 KiB
Markdown

Defining Assets "On The Fly"
----------------------------
The second approach to using Assetic involves defining your application's
assets "on the fly" in your templates, instead of in an isolated PHP file.
Using this approach, your PHP template would look something like this:
<script src="<?php echo assetic_javascripts('js/*', 'yui_js') ?>"></script>
This call to `assetic_javascripts()` serves a dual purpose. It will be read by
the Assetic "formula loader" which will extract an asset "formula" that can be
used to build, dump and output the asset. It will also be executed when the
template is rendered, at which time the path to the output asset is output.
Assetic includes the following templating helper functions:
* `assetic_image()`
* `assetic_javascripts()`
* `assetic_stylesheets()`
Defining assets on the fly is a much more sophisticated technique and
therefore relies on services to do the heavy lifting. The main one being the
asset factory.
### Asset Factory
The asset factory knows how to create asset objects using only arrays and
scalar values as input. This is the same string syntax used by the `assetic_*`
template helper functions.
use Assetic\Factory\AssetFactory;
$factory = new AssetFactory('/path/to/web');
$js = $factory->createAsset(array(
'js/jquery.js',
'js/jquery.plugin.js',
'js/application.js',
));
### Filter Manager
You can also apply filters to asset created by the factory. To do this you
must setup a `FilterManager`, which organizes filters by a name.
use Assetic\FilterManager;
use Assetic\Filter\GoogleClosure\ApiFilter as ClosureFilter;
$fm = new FilterManager();
$fm->set('closure', new ClosureFilter());
$factory->setFilterManager($fm);
$js = $factory->createAsset('js/*', 'closure');
This code creates an instance of the Google Closure Compiler filter and
assigns it the name `closure` using a filter manager. This filter manager is
then injected into the asset factory, making the filter available as `closure`
when creating assets.
### Debug Mode
The asset factory also introduces the concept of a debug mode. This mode
allows you to omit certain filters from assets the factory creates depending
on whether it is enabled or not.
For example, the YUI Compressor is awesome, but it is only appropriate in a
production environment as it is very difficult to debug minified Javascript.
use Asset\Factory\AssetFactory;
$factory = new AssetFactory('/path/to/web', true); // debug mode is on
$factory->setFilterManager($fm);
$js = $factory->createAsset('js/*', '?closure');
By prefixing the `closure` filter's name with a question mark, we are telling
the factory this filter is optional and should only be applied with debug mode
is off.
### Asset Manager and Asset References
The asset factory provides another special string syntax that allows you to
reference assets you defined elsewhere. These are called "asset references"
and involve an asset manager which, similar to the filter manager, organizes
assets by name.
use Assetic\AssetManager;
use Assetic\Asset\FileAsset;
use Assetic\Factory\AssetFactory;
$am = new AssetManager();
$am->set('jquery', new FileAsset('/path/to/jquery.js'));
$factory = new AssetFactory('/path/to/web');
$factory->setAssetManager($am);
$js = $factory->createAsset(array(
'@jquery',
'js/application.js',
));
### Extracting Assets from Templates
Once you've defined a set of assets in your templates you must use the
"formula loader" service to extract these asset definitions.
use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
use Assetic\Factory\Resource\FileResource;
$loader = new FunctionCallsFormulaLoader($factory);
$formulae = $loader->load(new FileResource('/path/to/template.php'));
These asset formulae aren't much use by themselves. They each include just
enough information for the asset factory to create the intended asset object.
In order for these to be useful they must be wrapped in the special
`LazyAssetManager`.
### The Lazy Asset Manager
This service is a composition of the asset factory and one or more formula
loaders. It acts as the glue between these services behind the scenes, but can
be used just like a normal asset manager on the surface.
use Assetic\Asset\FileAsset;
use Assetic\Factory\LazyAssetManager;
use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
use Assetic\Factory\Resource\DirectoryResource;
$am = new LazyAssetManager($factory);
$am->set('jquery', new FileAsset('/path/to/jquery.js'));
$am->setLoader('php', new FunctionCallsFormulaLoader($factory));
$am->addResource(new DirectoryResource('/path/to/templates', '/\.php$/'), 'php');
### Asset Writer
Finally, once you've create an asset manager that knows about every asset
you've defined in your templates, you must use an asset writer to actually
create the files your templates are going to be referencing.
use Assetic\AssetWriter;
$writer = new AssetWriter('/path/to/web');
$writer->writeManagerAssets($am);
After running this script, all of the assets in your asset manager will be
loaded into memory, filtered with their configured filters and dumped to your
web directory as static files, ready to be served.