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 d1ee96e

Browse filesBrowse files
weaverryanweaverryan
committed
Merge pull request #2263 from symfony/assetic
Assetic
2 parents d0ccf59 + 0ed1a84 commit d1ee96e
Copy full SHA for d1ee96e

File tree

Expand file treeCollapse file tree

1 file changed

+95
-39
lines changed
Filter options
Expand file treeCollapse file tree

1 file changed

+95
-39
lines changed

‎cookbook/assetic/asset_management.rst

Copy file name to clipboardExpand all lines: cookbook/assetic/asset_management.rst
+95-39Lines changed: 95 additions & 39 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,23 +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 *can* 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.
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.
95147

96148
Combining Assets
97149
~~~~~~~~~~~~~~~~
98150

99-
You can also combine several files into one. This helps to reduce the number
100-
of HTTP requests, which is great for front end performance. It also allows
101-
you to maintain the files more easily by splitting them into manageable parts.
102-
This can help with re-usability as you can easily split project-specific
103-
files from those which can be used in other applications, but still serve
104-
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:
105157

106158
.. configuration-block::
107159

@@ -126,16 +178,18 @@ them as a single file:
126178
<script src="<?php echo $view->escape($url) ?>"></script>
127179
<?php endforeach; ?>
128180
129-
In the `dev` environment, each file is still served individually, so that
130-
you can debug problems more easily. However, in the `prod` environment, this
131-
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+
(or more specifically, when the ``debug`` flag is ``false``), this will be
184+
rendered as a single ``script`` tag, which contains the contents of all of
185+
the JavaScript files.
132186

133187
.. tip::
134188

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

140194
And combining files doesn't only apply to *your* files. You can also use Assetic to
141195
combine third party assets, such as jQuery, with your own into a single file:
@@ -161,6 +215,8 @@ combine third party assets, such as jQuery, with your own into a single file:
161215
<script src="<?php echo $view->escape($url) ?>"></script>
162216
<?php endforeach; ?>
163217
218+
.. _cookbook-assetic-filters:
219+
164220
Filters
165221
-------
166222

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.