wp-optimize / vendor / kriswallsmith / assetic / docs / en / define.md

define.md in WP-Optimize – Cache, Compress images, Minify & Clean database to boost page speed & performance 3.2.5, at vendor/kriswallsmith/assetic/docs/en/define.md

146 lines 5.2 KB

Raw Download Zip

1	Defining Assets "On The Fly"
2	----------------------------
3
4	The second approach to using Assetic involves defining your application's
5	assets "on the fly" in your templates, instead of in an isolated PHP file.
6	Using this approach, your PHP template would look something like this:
7
8	<script src="<?php echo assetic_javascripts('js/*', 'yui_js') ?>"></script>
9
10	This call to `assetic_javascripts()` serves a dual purpose. It will be read by
11	the Assetic "formula loader" which will extract an asset "formula" that can be
12	used to build, dump and output the asset. It will also be executed when the
13	template is rendered, at which time the path to the output asset is output.
14
15	Assetic includes the following templating helper functions:
16
17	* `assetic_image()`
18	* `assetic_javascripts()`
19	* `assetic_stylesheets()`
20
21	Defining assets on the fly is a much more sophisticated technique and
22	therefore relies on services to do the heavy lifting. The main one being the
23	asset factory.
24
25	### Asset Factory
26
27	The asset factory knows how to create asset objects using only arrays and
28	scalar values as input. This is the same string syntax used by the `assetic_*`
29	template helper functions.
30
31	use Assetic\Factory\AssetFactory;
32
33	$factory = new AssetFactory('/path/to/web');
34	$js = $factory->createAsset(array(
35	'js/jquery.js',
36	'js/jquery.plugin.js',
37	'js/application.js',
38	));
39
40	### Filter Manager
41
42	You can also apply filters to asset created by the factory. To do this you
43	must setup a `FilterManager`, which organizes filters by a name.
44
45	use Assetic\FilterManager;
46	use Assetic\Filter\GoogleClosure\ApiFilter as ClosureFilter;
47
48	$fm = new FilterManager();
49	$fm->set('closure', new ClosureFilter());
50	$factory->setFilterManager($fm);
51
52	$js = $factory->createAsset('js/*', 'closure');
53
54	This code creates an instance of the Google Closure Compiler filter and
55	assigns it the name `closure` using a filter manager. This filter manager is
56	then injected into the asset factory, making the filter available as `closure`
57	when creating assets.
58
59	### Debug Mode
60
61	The asset factory also introduces the concept of a debug mode. This mode
62	allows you to omit certain filters from assets the factory creates depending
63	on whether it is enabled or not.
64
65	For example, the YUI Compressor is awesome, but it is only appropriate in a
66	production environment as it is very difficult to debug minified Javascript.
67
68	use Asset\Factory\AssetFactory;
69
70	$factory = new AssetFactory('/path/to/web', true); // debug mode is on
71	$factory->setFilterManager($fm);
72	$js = $factory->createAsset('js/*', '?closure');
73
74	By prefixing the `closure` filter's name with a question mark, we are telling
75	the factory this filter is optional and should only be applied with debug mode
76	is off.
77
78	### Asset Manager and Asset References
79
80	The asset factory provides another special string syntax that allows you to
81	reference assets you defined elsewhere. These are called "asset references"
82	and involve an asset manager which, similar to the filter manager, organizes
83	assets by name.
84
85	use Assetic\AssetManager;
86	use Assetic\Asset\FileAsset;
87	use Assetic\Factory\AssetFactory;
88
89	$am = new AssetManager();
90	$am->set('jquery', new FileAsset('/path/to/jquery.js'));
91
92	$factory = new AssetFactory('/path/to/web');
93	$factory->setAssetManager($am);
94
95	$js = $factory->createAsset(array(
96	'@jquery',
97	'js/application.js',
98	));
99
100	### Extracting Assets from Templates
101
102	Once you've defined a set of assets in your templates you must use the
103	"formula loader" service to extract these asset definitions.
104
105	use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
106	use Assetic\Factory\Resource\FileResource;
107
108	$loader = new FunctionCallsFormulaLoader($factory);
109	$formulae = $loader->load(new FileResource('/path/to/template.php'));
110
111	These asset formulae aren't much use by themselves. They each include just
112	enough information for the asset factory to create the intended asset object.
113	In order for these to be useful they must be wrapped in the special
114	`LazyAssetManager`.
115
116	### The Lazy Asset Manager
117
118	This service is a composition of the asset factory and one or more formula
119	loaders. It acts as the glue between these services behind the scenes, but can
120	be used just like a normal asset manager on the surface.
121
122	use Assetic\Asset\FileAsset;
123	use Assetic\Factory\LazyAssetManager;
124	use Assetic\Factory\Loader\FunctionCallsFormulaLoader;
125	use Assetic\Factory\Resource\DirectoryResource;
126
127	$am = new LazyAssetManager($factory);
128	$am->set('jquery', new FileAsset('/path/to/jquery.js'));
129	$am->setLoader('php', new FunctionCallsFormulaLoader($factory));
130	$am->addResource(new DirectoryResource('/path/to/templates', '/\.php$/'), 'php');
131
132	### Asset Writer
133
134	Finally, once you've create an asset manager that knows about every asset
135	you've defined in your templates, you must use an asset writer to actually
136	create the files your templates are going to be referencing.
137
138	use Assetic\AssetWriter;
139
140	$writer = new AssetWriter('/path/to/web');
141	$writer->writeManagerAssets($am);
142
143	After running this script, all of the assets in your asset manager will be
144	loaded into memory, filtered with their configured filters and dumped to your
145	web directory as static files, ready to be served.
146