Skip to content

Commit 86528a6

Browse files
weaverryanweaverryan
committed
Merge pull request symfony#459 from richardmiller/adding_assetic_article
Adding general assetic cookbook article
2 parents 63f55c1 + ca1bf53 commit 86528a6

File tree

1 file changed

+227
-0
lines changed

1 file changed

+227
-0
lines changed

‎cookbook/assetic/asset_management.rst

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
How to Use Assetic for Asset Management
2+
=======================================
3+
4+
Assetic is an asset management library which is packaged with the standard
5+
Symfony2 distribution, it has a bundle to allow it to be easily used
6+
in Symfony2 directly from Twig or PHP templates. It works with assets and
7+
filters. The assets are files such as CSS, JavaScript and images files.
8+
There are various filters that can be applied to these files before they
9+
are served to the browser. This allows a separation between the asset files
10+
stored in the application and the files actually presented to the user.
11+
Without using Assetic or another asset manager you are just directly serving
12+
up the files that are stored in the application:
13+
14+
.. configuration-block::
15+
16+
.. code-block:: html+jinja
17+
18+
<script src="{{ asset('js/script.js') }}" type="text/javascript" />
19+
20+
.. code-block:: php
21+
22+
<script src="<?php echo $view['assets']->getUrl('js/script.js') ?>"
23+
type="text/javascript" />
24+
25+
Assets
26+
------
27+
28+
Using Assetic provides many advantages over directly serving the files.
29+
The files do not need to be stored where they are served from and can be
30+
drawn from various sources such as within a bundle:
31+
32+
.. configuration-block::
33+
34+
.. code-block:: html+jinja
35+
36+
{% javascripts '@AcmeFooBundle/Resources/public/js/*'
37+
%}
38+
<script src="{{ asset_url }}"></script>
39+
{% endjavascripts %}
40+
41+
.. code-block:: html+php
42+
43+
<?php foreach ($view['assetic']->javascripts(
44+
array('@AcmeFooBundle/Resources/public/js/*')) as $url): ?>
45+
<script src="<?php echo $view->escape($url) ?>"></script>
46+
<?php endforeach; ?>
47+
48+
You can also combine several files into one. This helps to reduce the number
49+
of HTTP requests which is good for front end performance, as most browsers
50+
will only process a limited number at a time slowing down page load times.
51+
It also allows you to maintain the files more easily by splitting them into
52+
manageable parts. This can also help with re-usability as you can easily
53+
split project specific files from those which can be used in other applications
54+
but still serve them as a single file:
55+
56+
.. configuration-block::
57+
58+
.. code-block:: html+jinja
59+
60+
{% javascripts '@AcmeFooBundle/Resources/public/js/*'
61+
'@AcmeBarBundle/Resources/public/js/form.js'
62+
'@AcmeBarBundle/Resources/public/js/calendar.js'
63+
%}
64+
<script src="{{ asset_url }}"></script>
65+
{% endjavascripts %}
66+
67+
.. code-block:: html+php
68+
69+
<?php foreach ($view['assetic']->javascripts(
70+
array('@AcmeFooBundle/Resources/public/js/*',
71+
'@AcmeBarBundle/Resources/public/js/form.js',
72+
'@AcmeBarBundle/Resources/public/js/calendar.js')) as $url): ?>
73+
<script src="<?php echo $view->escape($url) ?>"></script>
74+
<?php endforeach; ?>
75+
76+
77+
This does not only apply to your own files you can also use Assetic to
78+
combine third party assets, such as jQuery with your own into a single file:
79+
80+
.. configuration-block::
81+
82+
.. code-block:: html+jinja
83+
84+
{% javascripts '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js'
85+
'@AcmeFooBundle/Resources/public/js/*'
86+
%}
87+
<script src="{{ asset_url }}"></script>
88+
{% endjavascripts %}
89+
90+
.. code-block:: html+php
91+
92+
<?php foreach ($view['assetic']->javascripts(
93+
array('@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
94+
'@AcmeFooBundle/Resources/public/js/*')) as $url): ?>
95+
<script src="<?php echo $view->escape($url) ?>"></script>
96+
<?php endforeach; ?>
97+
98+
Filters
99+
-------
100+
101+
Additionally to this Assetic can apply filters to the assets before they
102+
are served. This includes tasks such as compressing the output for smaller
103+
file sizes which is another valuable front end optimisation. Other filters
104+
include compiling JavaScript file from CoffeeScript files and SASS to CSS.
105+
106+
Many of the filters do not do the work directly but use other libraries
107+
to do it, this so you will often have to install that software as well.
108+
The great advantage of using Assetic to invoke these libraries is that
109+
instead of having to run them manually when you have worked on the files,
110+
Assetic will take care of this for you and remove this step altogether
111+
from your development and deployment processes.
112+
113+
To use a filter you must specify it in the Assetic configuration
114+
as they are not enabled by default. For example to use the JavaScript YUI
115+
Compressor the following config needs to be added:
116+
117+
.. configuration-block::
118+
119+
.. code-block:: yaml
120+
121+
# app/config/config.yml
122+
assetic:
123+
filters:
124+
yui_js:
125+
jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar"
126+
127+
.. code-block:: xml
128+
129+
<!-- app/config/config.xml -->
130+
<assetic:config>
131+
<assetic:filter
132+
name="yui_js"
133+
jar="%kernel.root_dir%/Resources/java/yuicompressor.jar" />
134+
</assetic:config>
135+
136+
.. code-block:: php
137+
138+
// app/config/config.php
139+
$container->loadFromExtension('assetic', array(
140+
'filters' => array(
141+
'yui_js' => array(
142+
'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar',
143+
),
144+
),
145+
));
146+
147+
148+
You can then specify using the filter in the template:
149+
150+
.. configuration-block::
151+
152+
.. code-block:: html+jinja
153+
154+
{% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %}
155+
<script src="{{ asset_url }}"></script>
156+
{% endjavascripts %}
157+
158+
.. code-block:: html+php
159+
160+
<?php foreach ($view['assetic']->javascripts(
161+
array('@AcmeFooBundle/Resources/public/js/*'),
162+
array('yui_js')) as $url): ?>
163+
<script src="<?php echo $view->escape($url) ?>"></script>
164+
<?php endforeach; ?>
165+
166+
167+
A more detail guide to configuring and using Assetic filters as well as
168+
details of Assetic's debug mode can be found in :doc:`/cookbook/assetic/yuicompressor`.
169+
170+
Controlling the URL used
171+
------------------------
172+
173+
If you wish to you can control the URLs which Assetic produces. This is
174+
done from the template and is relative to the public document root:
175+
176+
.. configuration-block::
177+
178+
.. code-block:: html+jinja
179+
180+
{% javascripts '@AcmeFooBundle/Resources/public/js/*'
181+
output='js/combined.js'
182+
%}
183+
<script src="{{ asset_url }}"></script>
184+
{% endjavascripts %}
185+
186+
.. code-block:: html+php
187+
188+
<?php foreach ($view['assetic']->javascripts(
189+
array('@AcmeFooBundle/Resources/public/js/*'),
190+
array(),
191+
array('output' => 'js/combined.js')
192+
) as $url): ?>
193+
<script src="<?php echo $view->escape($url) ?>"></script>
194+
<?php endforeach; ?>
195+
196+
Caching the output
197+
------------------
198+
199+
The process of creating the files served up can be quite slow especially
200+
when using some of the filters which invoke third party software to the
201+
actual work. Even when working in the development environment the slow
202+
down in the page loads if this was to be done each time would quickly get
203+
frustrating. Fortunately in the dev environment Assetic caches the output
204+
so this will not happen, rather than having to clear the cache manually
205+
though, it monitors for changes to the assets and regenerates the files
206+
as needed. This means you can work on the asset files and see the results
207+
on page load but without having to suffer continual slow page loads.
208+
209+
For production, where you will not be making changes to the asset files,
210+
performance can be increased by avoiding the step of checking for changes.
211+
Assetic allows you to go further than this and avoid touching Symfony2
212+
and even PHP at all when serving the files. This is done by dumping all
213+
of the output files using a console command. These can then be served directly
214+
by the web server as static files, increasing performance and allowing the
215+
web server to deal with caching headers. The console command to dump the files
216+
is:
217+
218+
.. code-block:: bash
219+
220+
php app/console assetic:dump
221+
222+
.. note::
223+
224+
Once you have dumped the output you will need to run the console
225+
command again to see any new changes. If you run it on your development
226+
server you will need to remove the files in order to start letting Assetic
227+
process the assets on the fly again.

0 commit comments

Comments
 (0)