Skip to content

Commit e01e427

Browse files
weaverryanweaverryan
committed
[Assetic] Proofreading the Assetic section, rewriting parts, adding more details, evolving it
1 parent e03cc06 commit e01e427

File tree

1 file changed

+94
-71
lines changed

1 file changed

+94
-71
lines changed

‎cookbook/assetic/asset_management.rst

Lines changed: 94 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,12 @@
44
How to Use Assetic for Asset Management
55
=======================================
66

7-
Assetic combines two major ideas: assets and filters. The assets are files
8-
such as CSS, JavaScript and image files. The filters are things that can
9-
be applied to these files before they are served to the browser. This allows
10-
a separation between the asset files stored in the application and the files
11-
actually presented to the user.
7+
Assetic combines two major ideas: :ref:`assets<cookbook-assetic-assets>` and
8+
:ref:`filters<cookbook-assetic-filters>`. The assets are files such as CSS,
9+
JavaScript and image files. The filters are things that can be applied to
10+
these files before they are served to the browser. This allows a separation
11+
between the asset files stored in the application and the files actually presented
12+
to the user.
1213

1314
Without Assetic, you just serve the files that are stored in the application
1415
directly:
@@ -33,12 +34,27 @@ load them from anywhere) before serving them. This means you can:
3334
3435
* Run image optimizations on your images
3536
37+
.. _cookbook-assetic-assets:
38+
3639
Assets
3740
------
3841
3942
Using Assetic provides many advantages over directly serving the files.
4043
The files do not need to be stored where they are served from and can be
41-
drawn from various sources such as from within a bundle:
44+
drawn from various sources such as from within a bundle.
45+
46+
You can use Assetic to process both :ref:`CSS stylesheets<cookbook-assetic-including-css>`
47+
and :ref:`JavaScript files<cookbook-assetic-including-javascript>`. The philosophy
48+
behind adding either is basically the same, but with a slightly different syntax.
49+
50+
.. _cookbook-assetic-including-javascript:
51+
52+
Including JavaScript Files
53+
~~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
To include JavaScript files, use the ``javascript`` tag in any template.
56+
This will most commonly live in the ``javascripts`` block, if you're using
57+
the default block names from the Symfony Standard Distribution:
4258
4359
.. configuration-block::
4460
@@ -58,24 +74,7 @@ drawn from various sources such as from within a bundle:
5874
5975
.. tip::
6076

61-
To bring in CSS stylesheets, you can use the same methodologies seen
62-
in this entry, except with the `stylesheets` tag:
63-
64-
.. configuration-block::
65-
66-
.. code-block:: html+jinja
67-
68-
{% stylesheets 'bundles/acme_foo/css/*' %}
69-
<link rel="stylesheet" href="{{ asset_url }}" />
70-
{% endstylesheets %}
71-
72-
.. code-block:: html+php
73-
74-
<?php foreach ($view['assetic']->stylesheets(
75-
array('bundles/acme_foo/css/*')
76-
) as $url): ?>
77-
<link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
78-
<?php endforeach; ?>
77+
You can also include CSS Stylesheets: see :ref:`cookbook-assetic-including-css`.
7978

8079
In this example, all of the files in the ``Resources/public/js/`` directory
8180
of the ``AcmeFooBundle`` will be loaded and served from a different location.
@@ -85,55 +84,76 @@ The actual rendered tag might simply look like:
8584

8685
<script src="/app_dev.php/js/abcd123.js"></script>
8786

87+
This is a key point: once you let Assetic handle your assets, the files are
88+
served from a different location. This *will* cause problems with CSS files
89+
that reference images by their relative path. See :ref:`cookbook-assetic-cssrewrite`.
90+
91+
.. _cookbook-assetic-including-css:
92+
93+
Including CSS Stylesheets
94+
~~~~~~~~~~~~~~~~~~~~~~~~~
95+
96+
To bring in CSS stylesheets, you can use the same methodologies seen
97+
above, except with the ``stylesheets`` tag. If you're using the default
98+
block names from the Symfony Standard Distribution, this will usually live
99+
inside a ``stylesheets`` block:
100+
101+
.. configuration-block::
102+
103+
.. code-block:: html+jinja
104+
105+
{% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %}
106+
<link rel="stylesheet" href="{{ asset_url }}" />
107+
{% endstylesheets %}
108+
109+
.. code-block:: html+php
110+
111+
<?php foreach ($view['assetic']->stylesheets(
112+
array('bundles/acme_foo/css/*'),
113+
array('cssrewrite')
114+
) as $url): ?>
115+
<link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
116+
<?php endforeach; ?>
117+
118+
But because Assetic changes the paths to your assets, this *will* break any
119+
background images (or other paths) that uses relative paths, unless you use
120+
the :ref:`cssrewrite<cookbook-assetic-cssrewrite>` filter.
121+
88122
.. note::
89123

90-
This is a key point: once you let Assetic handle your assets, the files are
91-
served from a different location. This *will* cause problems with CSS files
92-
that reference images by their relative path. However, this can be fixed
93-
by using the ``cssrewrite`` filter, which updates paths in CSS files
94-
to reflect their new location.
95-
96-
Unfortunately, the ``cssrewrite`` filter does not work when using the
97-
``@AcmeFooBundle`` syntax to reference the assets. This is a known
98-
limitation. A workaround is to use the ``output`` option to change the
99-
location the files are served from to a path from which the relative paths
100-
work, e.g.:
101-
102-
.. configuration-block::
103-
104-
.. code-block:: html+jinja
105-
106-
{% stylesheets
107-
output='bundles/acmefoo/css/compiled.css'
108-
'@AcmeFooBundle/Resources/public/css/*'
109-
%}
110-
<link rel="stylesheet" href="{{ asset_url }}" />
111-
{% endstylesheets %}
112-
113-
.. code-block:: html+php
114-
115-
<?php foreach ($view['assetic']->stylesheets(
116-
array('@AcmeFooBundle/Resources/public/css/*'),
117-
array(),
118-
array('output' => 'bundles/acmefoo/css/compiled.css')
119-
) as $url): ?>
120-
<link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
121-
<?php endforeach; ?>
122-
123-
Of course, this assumes that all the CSS files you serve in this block use
124-
relative paths that start from the same location, which is not always
125-
convenient. This is the reason this is called a *workaround* and not a
126-
*solution*.
124+
Notice that in the original example that included JavaScript files, you
125+
referred to the files using a path like ``@AcmeFooBundle/Resources/public/file.js``,
126+
but that in this example, you referred to the CSS files using their actual,
127+
publicly-accessible path: ``bundles/acme_foo/css``. You can use either, except
128+
that there is a known issue that causes the ``cssrewrite`` filter to fail
129+
when using the ``@AcmeFooBundle`` syntax for CSS Stylesheets.
130+
131+
.. _cookbook-assetic-cssrewrite:
132+
133+
Fixing CSS Paths with the ``cssrewrite`` Filter
134+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135+
136+
Since Assetic generates new URLs for your assets, any relative paths inside
137+
your CSS files will break. To fix this, make sure to use the ``cssrewrite``
138+
filter with your ``stylesheets`` tag. This parses your CSS files and corrects
139+
the paths internally to reflect the new location.
140+
141+
You can see an example in the previous section.
142+
143+
.. caution::
144+
145+
When using the ``cssrewrite`` filter, don't refer to your CSS files using
146+
the ``@AcmeFooBundle``. See the note in the above section for details.
127147

128148
Combining Assets
129149
~~~~~~~~~~~~~~~~
130150

131-
You can also combine several files into one. This helps to reduce the number
132-
of HTTP requests, which is great for front end performance. It also allows
133-
you to maintain the files more easily by splitting them into manageable parts.
134-
This can help with re-usability as you can easily split project-specific
135-
files from those which can be used in other applications, but still serve
136-
them as a single file:
151+
One feature of Assetic is that it will combine many files into one. This helps
152+
to reduce the number of HTTP requests, which is great for front end performance.
153+
It also allows you to maintain the files more easily by splitting them into
154+
manageable parts. This can help with re-usability as you can easily split
155+
project-specific files from those which can be used in other applications,
156+
but still serve them as a single file:
137157

138158
.. configuration-block::
139159

@@ -158,16 +178,17 @@ them as a single file:
158178
<script src="<?php echo $view->escape($url) ?>"></script>
159179
<?php endforeach; ?>
160180
161-
In the `dev` environment, each file is still served individually, so that
162-
you can debug problems more easily. However, in the `prod` environment, this
163-
will be rendered as a single `script` tag.
181+
In the ``dev`` environment, each file is still served individually, so that
182+
you can debug problems more easily. However, in the ``prod`` environment,
183+
this will be rendered as a single ``script`` tag, which contains the contents
184+
of all of the JavaScript files.
164185

165186
.. tip::
166187

167188
If you're new to Assetic and try to use your application in the ``prod``
168189
environment (by using the ``app.php`` controller), you'll likely see
169190
that all of your CSS and JS breaks. Don't worry! This is on purpose.
170-
For details on using Assetic in the `prod` environment, see :ref:`cookbook-assetic-dumping`.
191+
For details on using Assetic in the ``prod`` environment, see :ref:`cookbook-assetic-dumping`.
171192

172193
And combining files doesn't only apply to *your* files. You can also use Assetic to
173194
combine third party assets, such as jQuery, with your own into a single file:
@@ -193,6 +214,8 @@ combine third party assets, such as jQuery, with your own into a single file:
193214
<script src="<?php echo $view->escape($url) ?>"></script>
194215
<?php endforeach; ?>
195216
217+
.. _cookbook-assetic-filters:
218+
196219
Filters
197220
-------
198221

0 commit comments

Comments
 (0)