From e03cc0624f656a4ad454ad18e397fc90c8059373 Mon Sep 17 00:00:00 2001 From: Olivier Date: Thu, 29 Nov 2012 09:33:51 +0100 Subject: [PATCH 1/3] Added information about the cssrewrite filter not working with the @AcmeFooBundle syntax. [kriswallsmith/assetic#53] https://github.com/kriswallsmith/assetic/issues/53#issuecomment-2976018 --- cookbook/assetic/asset_management.rst | 34 ++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 80fbc91354b..1bc25354155 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -88,10 +88,42 @@ The actual rendered tag might simply look like: .. 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 + served from a different location. This *will* 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. + + Unfortunately, the ``cssrewrite`` filter does not work when using the + ``@AcmeFooBundle`` syntax to reference the assets. This is a known + limitation. A workaround is to use the ``output`` option to change the + location the files are served from to a path from which the relative paths + work, e.g.: + + .. configuration-block:: + + .. code-block:: html+jinja + + {% stylesheets + output='bundles/acmefoo/css/compiled.css' + '@AcmeFooBundle/Resources/public/css/*' + %} + + {% endstylesheets %} + + .. code-block:: html+php + + stylesheets( + array('@AcmeFooBundle/Resources/public/css/*'), + array(), + array('output' => 'bundles/acmefoo/css/compiled.css') + ) as $url): ?> + + + + Of course, this assumes that all the CSS files you serve in this block use + relative paths that start from the same location, which is not always + convenient. This is the reason this is called a *workaround* and not a + *solution*. Combining Assets ~~~~~~~~~~~~~~~~ From e01e42731224ddd8fdc4948b46aebcbe4623f670 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Sat, 23 Feb 2013 12:15:45 -0800 Subject: [PATCH 2/3] [Assetic] Proofreading the Assetic section, rewriting parts, adding more details, evolving it --- cookbook/assetic/asset_management.rst | 165 +++++++++++++++----------- 1 file changed, 94 insertions(+), 71 deletions(-) diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 1bc25354155..774b1a6feac 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -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` and +:ref:`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: @@ -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` +and :ref:`JavaScript files`. 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:: @@ -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/*' %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('bundles/acme_foo/css/*') - ) as $url): ?> - - + 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. @@ -85,55 +84,76 @@ The actual rendered tag might simply look like: +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' %} + + {% endstylesheets %} + + .. code-block:: html+php + + stylesheets( + array('bundles/acme_foo/css/*'), + array('cssrewrite') + ) as $url): ?> + + + +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` filter. + .. note:: - 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. However, this can be fixed - by using the ``cssrewrite`` filter, which updates paths in CSS files - to reflect their new location. - - Unfortunately, the ``cssrewrite`` filter does not work when using the - ``@AcmeFooBundle`` syntax to reference the assets. This is a known - limitation. A workaround is to use the ``output`` option to change the - location the files are served from to a path from which the relative paths - work, e.g.: - - .. configuration-block:: - - .. code-block:: html+jinja - - {% stylesheets - output='bundles/acmefoo/css/compiled.css' - '@AcmeFooBundle/Resources/public/css/*' - %} - - {% endstylesheets %} - - .. code-block:: html+php - - stylesheets( - array('@AcmeFooBundle/Resources/public/css/*'), - array(), - array('output' => 'bundles/acmefoo/css/compiled.css') - ) as $url): ?> - - - - Of course, this assumes that all the CSS files you serve in this block use - relative paths that start from the same location, which is not always - convenient. This is the reason this is called a *workaround* and not a - *solution*. + 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:: @@ -158,16 +178,17 @@ them as a single file: -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, +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: @@ -193,6 +214,8 @@ combine third party assets, such as jQuery, with your own into a single file: +.. _cookbook-assetic-filters: + Filters ------- From 0ed1a842ec1c49bb4445c981de61c3cda91e0116 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Tue, 26 Feb 2013 21:46:05 -0600 Subject: [PATCH 3/3] [#2263] Clarifying when assets are combined thanks to @stof --- cookbook/assetic/asset_management.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 774b1a6feac..d74d28b20c4 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -179,9 +179,10 @@ but still serve them as a single file: 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, which contains the contents -of all of the JavaScript files. +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::