Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 86528a6

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

File tree

Expand file treeCollapse file tree

1 file changed

+227
-0
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+227
-0
lines changed

‎cookbook/assetic/asset_management.rst

Copy file name to clipboard
+227Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.