Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge branch '2.0' into 2.1
  • Loading branch information
weaverryan committed Feb 27, 2013
2 parents b332099 + 16e732d commit f239d0e
Show file tree
Hide file tree
Showing 4 changed files with 100 additions and 41 deletions.
2 changes: 1 addition & 1 deletion components/http_foundation/introduction.rst
Expand Up @@ -310,7 +310,7 @@ method takes an instance of
:class:`Symfony\\Component\\HttpFoundation\\Cookie` as an argument.

You can clear a cookie via the
:method:`Symfony\\Component\\HttpFoundation\\Response::clearCookie` method.
:method:`Symfony\\Component\\HttpFoundation\\ResponseHeaderBag::clearCookie` method.

Managing the HTTP Cache
~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
134 changes: 95 additions & 39 deletions cookbook/assetic/asset_management.rst
Expand Up @@ -4,11 +4,12 @@
How to Use Assetic for Asset Management
=======================================

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

Without Assetic, you just serve the files that are stored in the application
directly:
Expand All @@ -33,12 +34,27 @@ load them from anywhere) before serving them. This means you can:
* Run image optimizations on your images
.. _cookbook-assetic-assets:
Assets
------
Using Assetic provides many advantages over directly serving the files.
The files do not need to be stored where they are served from and can be
drawn from various sources such as from within a bundle:
drawn from various sources such as from within a bundle.
You can use Assetic to process both :ref:`CSS stylesheets<cookbook-assetic-including-css>`
and :ref:`JavaScript files<cookbook-assetic-including-javascript>`. The philosophy
behind adding either is basically the same, but with a slightly different syntax.
.. _cookbook-assetic-including-javascript:
Including JavaScript Files
~~~~~~~~~~~~~~~~~~~~~~~~~~
To include JavaScript files, use the ``javascript`` tag in any template.
This will most commonly live in the ``javascripts`` block, if you're using
the default block names from the Symfony Standard Distribution:
.. configuration-block::
Expand All @@ -58,24 +74,7 @@ drawn from various sources such as from within a bundle:
.. tip::

To bring in CSS stylesheets, you can use the same methodologies seen
in this entry, except with the `stylesheets` tag:

.. configuration-block::

.. code-block:: html+jinja

{% stylesheets 'bundles/acme_foo/css/*' %}
<link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}
.. code-block:: html+php

<?php foreach ($view['assetic']->stylesheets(
array('bundles/acme_foo/css/*')
) as $url): ?>
<link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
<?php endforeach; ?>
You can also include CSS Stylesheets: see :ref:`cookbook-assetic-including-css`.

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

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

This is a key point: once you let Assetic handle your assets, the files are
served from a different location. This *will* cause problems with CSS files
that reference images by their relative path. See :ref:`cookbook-assetic-cssrewrite`.

.. _cookbook-assetic-including-css:

Including CSS Stylesheets
~~~~~~~~~~~~~~~~~~~~~~~~~

To bring in CSS stylesheets, you can use the same methodologies seen
above, except with the ``stylesheets`` tag. If you're using the default
block names from the Symfony Standard Distribution, this will usually live
inside a ``stylesheets`` block:

.. configuration-block::

.. code-block:: html+jinja

{% stylesheets 'bundles/acme_foo/css/*' filter='cssrewrite' %}
<link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}
.. code-block:: html+php

<?php foreach ($view['assetic']->stylesheets(
array('bundles/acme_foo/css/*'),
array('cssrewrite')
) as $url): ?>
<link rel="stylesheet" href="<?php echo $view->escape($url) ?>" />
<?php endforeach; ?>
But because Assetic changes the paths to your assets, this *will* break any
background images (or other paths) that uses relative paths, unless you use
the :ref:`cssrewrite<cookbook-assetic-cssrewrite>` filter.

.. note::

This is a key point: once you let Assetic handle your assets, the files are
served from a different location. This *can* cause problems with CSS files
that reference images by their relative path. However, this can be fixed
by using the ``cssrewrite`` filter, which updates paths in CSS files
to reflect their new location.
Notice that in the original example that included JavaScript files, you
referred to the files using a path like ``@AcmeFooBundle/Resources/public/file.js``,
but that in this example, you referred to the CSS files using their actual,
publicly-accessible path: ``bundles/acme_foo/css``. You can use either, except
that there is a known issue that causes the ``cssrewrite`` filter to fail
when using the ``@AcmeFooBundle`` syntax for CSS Stylesheets.

.. _cookbook-assetic-cssrewrite:

Fixing CSS Paths with the ``cssrewrite`` Filter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since Assetic generates new URLs for your assets, any relative paths inside
your CSS files will break. To fix this, make sure to use the ``cssrewrite``
filter with your ``stylesheets`` tag. This parses your CSS files and corrects
the paths internally to reflect the new location.

You can see an example in the previous section.

.. caution::

When using the ``cssrewrite`` filter, don't refer to your CSS files using
the ``@AcmeFooBundle``. See the note in the above section for details.

Combining Assets
~~~~~~~~~~~~~~~~

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

.. configuration-block::

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

.. tip::

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

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

Filters
-------

Expand Down
2 changes: 1 addition & 1 deletion reference/constraints/Email.rst
Expand Up @@ -80,7 +80,7 @@ Basic Usage
{
$metadata->addPropertyConstraint('email', new Assert\Email(array(
'message' => 'The email "{{ value }}" is not a valid email.',
'check' => true,
'checkMX' => true,
)));
}
}
Expand Down
3 changes: 3 additions & 0 deletions reference/forms/types/collection.rst
Expand Up @@ -23,6 +23,7 @@ forms, which is useful when creating forms that expose one-to-many relationships
| Inherited | - `label`_ |
| options | - `error_bubbling`_ |
| | - `by_reference`_ |
| | - `empty_data`_ |
+-------------+-----------------------------------------------------------------------------+
| Parent type | :doc:`form</reference/forms/types/form>` |
+-------------+-----------------------------------------------------------------------------+
Expand Down Expand Up @@ -344,3 +345,5 @@ error_bubbling
.. _reference-form-types-by-reference:

.. include:: /reference/forms/types/options/by_reference.rst.inc

.. include:: /reference/forms/types/options/empty_data.rst.inc

0 comments on commit f239d0e

Please sign in to comment.