← Back to branch summary

~ubuntu-branches/debian/stretch/assetic/stretch

« back to all changes in this revision

Viewing changes to README.md

  • Committer: Package Import Robot
  • Author(s): David Prévot
  • Date: 2014-04-21 12:48:05 UTC
  • Revision ID: package-import@ubuntu.com-20140421124805-y9ri97838g33fo9z
Tags: upstream-1.1.2
Import upstream version 1.1.2

Show diffs side-by-side

added added

removed removed

Lines of Context:
README.md
 
1
# Assetic [![Build Status](https://travis-ci.org/kriswallsmith/assetic.png?branch=master)](https://travis-ci.org/kriswallsmith/assetic) ![project status](http://stillmaintained.com/kriswallsmith/assetic.png) #
 
2
 
 
3
Assetic is an asset management framework for PHP.
 
4
 
 
5
``` php
 
6
<?php
 
7
 
 
8
use Assetic\Asset\AssetCollection;
 
9
use Assetic\Asset\FileAsset;
 
10
use Assetic\Asset\GlobAsset;
 
11
 
 
12
$js = new AssetCollection(array(
 
13
    new GlobAsset('/path/to/js/*'),
 
14
    new FileAsset('/path/to/another.js'),
 
15
));
 
16
 
 
17
// the code is merged when the asset is dumped
 
18
echo $js->dump();
 
19
```
 
20
 
 
21
Assets
 
22
------
 
23
 
 
24
An Assetic asset is something with filterable content that can be loaded and
 
25
dumped. An asset also includes metadata, some of which can be manipulated and
 
26
some of which is immutable.
 
27
 
 
28
| **Property** | **Accessor**    | **Mutator**   |
 
29
|--------------|-----------------|---------------|
 
30
| content      | getContent      | setContent    |
 
31
| mtime        | getLastModified | n/a           |
 
32
| source root  | getSourceRoot   | n/a           |
 
33
| source path  | getSourcePath   | n/a           |
 
34
| target path  | getTargetPath   | setTargetPath |
 
35
 
 
36
Filters
 
37
-------
 
38
 
 
39
Filters can be applied to manipulate assets.
 
40
 
 
41
``` php
 
42
<?php
 
43
 
 
44
use Assetic\Asset\AssetCollection;
 
45
use Assetic\Asset\FileAsset;
 
46
use Assetic\Asset\GlobAsset;
 
47
use Assetic\Filter\LessFilter;
 
48
use Assetic\Filter\Yui;
 
49
 
 
50
$css = new AssetCollection(array(
 
51
    new FileAsset('/path/to/src/styles.less', array(new LessFilter())),
 
52
    new GlobAsset('/path/to/css/*'),
 
53
), array(
 
54
    new Yui\CssCompressorFilter('/path/to/yuicompressor.jar'),
 
55
));
 
56
 
 
57
// this will echo CSS compiled by LESS and compressed by YUI
 
58
echo $css->dump();
 
59
```
 
60
 
 
61
The filters applied to the collection will cascade to each asset leaf if you
 
62
iterate over it.
 
63
 
 
64
``` php
 
65
<?php
 
66
 
 
67
foreach ($css as $leaf) {
 
68
    // each leaf is compressed by YUI
 
69
    echo $leaf->dump();
 
70
}
 
71
```
 
72
 
 
73
The core provides the following filters in the `Assetic\Filter` namespace:
 
74
 
 
75
 * `CoffeeScriptFilter`: compiles CoffeeScript into Javascript
 
76
 * `CompassFilter`: Compass CSS authoring framework
 
77
 * `CssEmbedFilter`: embeds image data in your stylesheets
 
78
 * `CssImportFilter`: inlines imported stylesheets
 
79
 * `CssMinFilter`: minifies CSS
 
80
 * `CssRewriteFilter`: fixes relative URLs in CSS assets when moving to a new URL
 
81
 * `DartFilter`: compiles Javascript using dart2js
 
82
 * `EmberPrecompileFilter`: precompiles Handlebars templates into Javascript for use in the Ember.js framework
 
83
 * `GoogleClosure\CompilerApiFilter`: compiles Javascript using the Google Closure Compiler API
 
84
 * `GoogleClosure\CompilerJarFilter`: compiles Javascript using the Google Closure Compiler JAR
 
85
 * `GssFilter`: compliles CSS using the Google Closure Stylesheets Compiler
 
86
 * `HandlebarsFilter`: compiles Handlebars templates into Javascript
 
87
 * `JpegoptimFilter`: optimize your JPEGs
 
88
 * `JpegtranFilter`: optimize your JPEGs
 
89
 * `JSMinFilter`: minifies Javascript
 
90
 * `JSMinPlusFilter`: minifies Javascript
 
91
 * `LessFilter`: parses LESS into CSS (using less.js with node.js)
 
92
 * `LessphpFilter`: parses LESS into CSS (using lessphp)
 
93
 * `OptiPngFilter`: optimize your PNGs
 
94
 * `PackagerFilter`: parses Javascript for packager tags
 
95
 * `PackerFilter`: compresses Javascript using Dean Edwards's Packer
 
96
 * `PhpCssEmbedFilter`: embeds image data in your stylesheet
 
97
 * `PngoutFilter`: optimize your PNGs
 
98
 * `Sass\SassFilter`: parses SASS into CSS
 
99
 * `Sass\ScssFilter`: parses SCSS into CSS
 
100
 * `ScssphpFilter`: parses SCSS using scssphp
 
101
 * `SprocketsFilter`: Sprockets Javascript dependency management
 
102
 * `StylusFilter`: parses STYL into CSS
 
103
 * `TypeScriptFilter`: parses TypeScript into Javascript
 
104
 * `UglifyCssFilter`: minifies CSS
 
105
 * `UglifyJs2Filter`: minifies Javascript
 
106
 * `UglifyJsFilter`: minifies Javascript
 
107
 * `Yui\CssCompressorFilter`: compresses CSS using the YUI compressor
 
108
 * `Yui\JsCompressorFilter`: compresses Javascript using the YUI compressor
 
109
 
 
110
Asset Manager
 
111
-------------
 
112
 
 
113
An asset manager is provided for organizing assets.
 
114
 
 
115
``` php
 
116
<?php
 
117
 
 
118
use Assetic\AssetManager;
 
119
use Assetic\Asset\FileAsset;
 
120
use Assetic\Asset\GlobAsset;
 
121
 
 
122
$am = new AssetManager();
 
123
$am->set('jquery', new FileAsset('/path/to/jquery.js'));
 
124
$am->set('base_css', new GlobAsset('/path/to/css/*'));
 
125
```
 
126
 
 
127
The asset manager can also be used to reference assets to avoid duplication.
 
128
 
 
129
``` php
 
130
<?php
 
131
 
 
132
use Assetic\Asset\AssetCollection;
 
133
use Assetic\Asset\AssetReference;
 
134
use Assetic\Asset\FileAsset;
 
135
 
 
136
$am->set('my_plugin', new AssetCollection(array(
 
137
    new AssetReference($am, 'jquery'),
 
138
    new FileAsset('/path/to/jquery.plugin.js'),
 
139
)));
 
140
```
 
141
 
 
142
Filter Manager
 
143
--------------
 
144
 
 
145
A filter manager is also provided for organizing filters.
 
146
 
 
147
``` php
 
148
<?php
 
149
 
 
150
use Assetic\FilterManager;
 
151
use Assetic\Filter\Sass\SassFilter;
 
152
use Assetic\Filter\Yui;
 
153
 
 
154
$fm = new FilterManager();
 
155
$fm->set('sass', new SassFilter('/path/to/parser/sass'));
 
156
$fm->set('yui_css', new Yui\CssCompressorFilter('/path/to/yuicompressor.jar'));
 
157
```
 
158
 
 
159
Asset Factory
 
160
-------------
 
161
 
 
162
If you'd rather not create all these objects by hand, you can use the asset
 
163
factory, which will do most of the work for you.
 
164
 
 
165
``` php
 
166
<?php
 
167
 
 
168
use Assetic\Factory\AssetFactory;
 
169
 
 
170
$factory = new AssetFactory('/path/to/asset/directory/');
 
171
$factory->setAssetManager($am);
 
172
$factory->setFilterManager($fm);
 
173
$factory->setDebug(true);
 
174
 
 
175
$css = $factory->createAsset(array(
 
176
    '@reset',         // load the asset manager's "reset" asset
 
177
    'css/src/*.scss', // load every scss files from "/path/to/asset/directory/css/src/"
 
178
), array(
 
179
    'scss',           // filter through the filter manager's "scss" filter
 
180
    '?yui_css',       // don't use this filter in debug mode
 
181
));
 
182
 
 
183
echo $css->dump();
 
184
```
 
185
 
 
186
Prefixing a filter name with a question mark, as `yui_css` is here, will cause
 
187
that filter to be omitted when the factory is in debug mode.
 
188
 
 
189
Caching
 
190
-------
 
191
 
 
192
A simple caching mechanism is provided to avoid unnecessary work.
 
193
 
 
194
``` php
 
195
<?php
 
196
 
 
197
use Assetic\Asset\AssetCache;
 
198
use Assetic\Asset\FileAsset;
 
199
use Assetic\Cache\FilesystemCache;
 
200
use Assetic\Filter\Yui;
 
201
 
 
202
$yui = new Yui\JsCompressorFilter('/path/to/yuicompressor.jar');
 
203
$js = new AssetCache(
 
204
    new FileAsset('/path/to/some.js', array($yui)),
 
205
    new FilesystemCache('/path/to/cache')
 
206
);
 
207
 
 
208
// the YUI compressor will only run on the first call
 
209
$js->dump();
 
210
$js->dump();
 
211
$js->dump();
 
212
```
 
213
 
 
214
Cache Busting
 
215
-------------
 
216
 
 
217
You can use the CacheBustingWorker to provide unique names.
 
218
 
 
219
Two strategies are provided: CacheBustingWorker::STRATEGY_CONTENT (content based), CacheBustingWorker::STRATEGY_MODIFICATION (modification time based)
 
220
 
 
221
``` php
 
222
<?php
 
223
 
 
224
use Assetic\Factory\AssetFactory;
 
225
use Assetic\Factory\Worker\CacheBustingWorker;
 
226
 
 
227
$factory = new AssetFactory('/path/to/asset/directory/');
 
228
$factory->setAssetManager($am);
 
229
$factory->setFilterManager($fm);
 
230
$factory->setDebug(true);
 
231
$factory->addWorker(new CacheBustingWorker(CacheBustingWorker::STRATEGY_CONTENT));
 
232
 
 
233
$css = $factory->createAsset(array(
 
234
    '@reset',         // load the asset manager's "reset" asset
 
235
    'css/src/*.scss', // load every scss files from "/path/to/asset/directory/css/src/"
 
236
), array(
 
237
    'scss',           // filter through the filter manager's "scss" filter
 
238
    '?yui_css',       // don't use this filter in debug mode
 
239
));
 
240
 
 
241
echo $css->dump();
 
242
```
 
243
 
 
244
Static Assets
 
245
-------------
 
246
 
 
247
Alternatively you can just write filtered assets to your web directory and be
 
248
done with it.
 
249
 
 
250
``` php
 
251
<?php
 
252
 
 
253
use Assetic\AssetWriter;
 
254
 
 
255
$writer = new AssetWriter('/path/to/web');
 
256
$writer->writeManagerAssets($am);
 
257
```
 
258
 
 
259
Twig
 
260
----
 
261
 
 
262
To use the Assetic [Twig][3] extension you must register it to your Twig
 
263
environment:
 
264
 
 
265
``` php
 
266
<?php
 
267
 
 
268
$twig->addExtension(new AsseticExtension($factory, $debug));
 
269
```
 
270
 
 
271
Once in place, the extension exposes a stylesheets and a javascripts tag with a syntax similar
 
272
to what the asset factory uses:
 
273
 
 
274
``` html+jinja
 
275
{% stylesheets '/path/to/sass/main.sass' filter='sass,?yui_css' output='css/all.css' %}
 
276
    <link href="{{ asset_url }}" type="text/css" rel="stylesheet" />
 
277
{% endstylesheets %}
 
278
```
 
279
 
 
280
This example will render one `link` element on the page that includes a URL
 
281
where the filtered asset can be found.
 
282
 
 
283
When the extension is in debug mode, this same tag will render multiple `link`
 
284
elements, one for each asset referenced by the `css/src/*.sass` glob. The
 
285
specified filters will still be applied, unless they are marked as optional
 
286
using the `?` prefix.
 
287
 
 
288
This behavior can also be triggered by setting a `debug` attribute on the tag:
 
289
 
 
290
``` html+jinja
 
291
{% stylesheets 'css/*' debug=true %} ... {% stylesheets %}
 
292
```
 
293
 
 
294
These assets need to be written to the web directory so these URLs don't
 
295
return 404 errors.
 
296
 
 
297
``` php
 
298
<?php
 
299
 
 
300
use Assetic\AssetWriter;
 
301
use Assetic\Extension\Twig\TwigFormulaLoader;
 
302
use Assetic\Extension\Twig\TwigResource;
 
303
use Assetic\Factory\LazyAssetManager;
 
304
 
 
305
$am = new LazyAssetManager($factory);
 
306
 
 
307
// enable loading assets from twig templates
 
308
$am->setLoader('twig', new TwigFormulaLoader($twig));
 
309
 
 
310
// loop through all your templates
 
311
foreach ($templates as $template) {
 
312
    $resource = new TwigResource($twigLoader, $template);
 
313
    $am->addResource($resource, 'twig');
 
314
}
 
315
 
 
316
$writer = new AssetWriter('/path/to/web');
 
317
$writer->writeManagerAssets($am);
 
318
```
 
319
 
 
320
---
 
321
 
 
322
Assetic is based on the Python [webassets][1] library (available on
 
323
[GitHub][2]).
 
324
 
 
325
[1]: http://elsdoerfer.name/docs/webassets
 
326
[2]: https://github.com/miracle2k/webassets
 
327
[3]: http://twig.sensiolabs.org