From 433dd041b7f84cd3f66d8a835e810c70298f112e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Dec 2015 16:05:24 +0100 Subject: [PATCH] Added caution notes about the removal of AsseticBundle in 2.8/3.0 --- best_practices/web-assets.rst | 6 ++ book/templating.rst | 6 +- cookbook/assetic/apply_to_option.rst | 6 ++ cookbook/assetic/asset_management.rst | 85 +++++++++++++++++++++++++++ cookbook/assetic/index.rst | 6 ++ cookbook/assetic/jpeg_optimize.rst | 6 ++ cookbook/assetic/php.rst | 6 ++ cookbook/assetic/uglifyjs.rst | 6 ++ cookbook/assetic/yuicompressor.rst | 6 ++ reference/configuration/assetic.rst | 6 ++ reference/twig_reference.rst | 5 +- 11 files changed, 137 insertions(+), 7 deletions(-) diff --git a/best_practices/web-assets.rst b/best_practices/web-assets.rst index a4160d62e2e..61a992b8181 100644 --- a/best_practices/web-assets.rst +++ b/best_practices/web-assets.rst @@ -35,6 +35,12 @@ much more concise: Using Assetic ------------- +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + These days, you probably can't simply create static CSS and JavaScript files and include them in your template. Instead, you'll probably want to combine and minify these to improve client-side performance. You may also want to diff --git a/book/templating.rst b/book/templating.rst index f50085219c1..5b76fe410d4 100644 --- a/book/templating.rst +++ b/book/templating.rst @@ -1130,9 +1130,9 @@ advantage of Symfony's template inheritance. .. tip:: This section will teach you the philosophy behind including stylesheet - and JavaScript assets in Symfony. Symfony also packages another library, - called Assetic, which follows this philosophy but allows you to do much - more interesting things with those assets. For more information on + and JavaScript assets in Symfony. Symfony is also compatible with another + library, called Assetic, which follows this philosophy but allows you to do + much more interesting things with those assets. For more information on using Assetic see :doc:`/cookbook/assetic/asset_management`. Start by adding two blocks to your base template that will hold your assets: diff --git a/cookbook/assetic/apply_to_option.rst b/cookbook/assetic/apply_to_option.rst index 22c7506075f..6f132ec4641 100644 --- a/cookbook/assetic/apply_to_option.rst +++ b/cookbook/assetic/apply_to_option.rst @@ -4,6 +4,12 @@ How to Apply an Assetic Filter to a specific File Extension =========================================================== +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + Assetic filters can be applied to individual files, groups of files or even, as you'll see here, files that have a specific extension. To show you how to handle each option, suppose that you want to use Assetic's CoffeeScript diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index af0055f5795..6fa15d80e5d 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -4,6 +4,91 @@ How to Use Assetic for Asset Management ======================================= +Installing and Enabling Assetic +------------------------------- + +Starting from Symfony 2.8, Assetic is no longer included by default in the +Symfony Standard Edition. Before using any of its features, install the +AsseticBundle executing this console command in your project: + + .. code-block:: bash + + $ composer require symfony/assetic-bundle + +Then, enable the bundle in the ``AppKernel`` file of your Symfony application:: + + // app/AppKernel.php + + // ... + class AppKernel extends Kernel + { + // ... + + public function registerBundles() + { + $bundles = array( + // ... + new Symfony\Bundle\AsseticBundle\AsseticBundle(), + ); + + // ... + } + } + +Finally, add the following minimal configuration to enable Assetic support in +your application: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + debug: "%kernel.debug%" + use_controller: false + filters: + cssrewrite: ~ + + # ... + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + + $container->loadFromExtension('assetic', array( + 'debug' => '%kernel.debug%', + 'use_controller' => '%kernel.debug%', + 'filters' => array( + 'cssrewrite' => null, + ), + // ... + )); + + // ... + +Introducing Assetic +------------------- + 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 diff --git a/cookbook/assetic/index.rst b/cookbook/assetic/index.rst index c37efdc16ee..8d2ac650587 100644 --- a/cookbook/assetic/index.rst +++ b/cookbook/assetic/index.rst @@ -1,6 +1,12 @@ Assetic ======= +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + .. toctree:: :maxdepth: 2 diff --git a/cookbook/assetic/jpeg_optimize.rst b/cookbook/assetic/jpeg_optimize.rst index c55a32dc800..d479fdd8893 100644 --- a/cookbook/assetic/jpeg_optimize.rst +++ b/cookbook/assetic/jpeg_optimize.rst @@ -4,6 +4,12 @@ How to Use Assetic for Image Optimization with Twig Functions ============================================================= +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + Among its many filters, Assetic has four filters which can be used for on-the-fly image optimization. This allows you to get the benefits of smaller file sizes without having to use an image editor to process each image. The results diff --git a/cookbook/assetic/php.rst b/cookbook/assetic/php.rst index c7e8c2e6b26..3bde1e7aef2 100644 --- a/cookbook/assetic/php.rst +++ b/cookbook/assetic/php.rst @@ -4,6 +4,12 @@ Combining, Compiling and Minimizing Web Assets with PHP Libraries ================================================================= +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + The official Symfony Best Practices recommend to use Assetic to :doc:`manage web assets `, unless you are comfortable with JavaScript-based front-end tools. diff --git a/cookbook/assetic/uglifyjs.rst b/cookbook/assetic/uglifyjs.rst index a08569647a3..47eb82ba4f6 100644 --- a/cookbook/assetic/uglifyjs.rst +++ b/cookbook/assetic/uglifyjs.rst @@ -4,6 +4,12 @@ How to Minify CSS/JS Files (Using UglifyJS and UglifyCSS) ========================================================= +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + `UglifyJS`_ is a JavaScript parser/compressor/beautifier toolkit. It can be used to combine and minify JavaScript assets so that they require less HTTP requests and make your site load faster. `UglifyCSS`_ is a CSS compressor/beautifier diff --git a/cookbook/assetic/yuicompressor.rst b/cookbook/assetic/yuicompressor.rst index 6ae078a8eac..4c2cc87a913 100644 --- a/cookbook/assetic/yuicompressor.rst +++ b/cookbook/assetic/yuicompressor.rst @@ -10,6 +10,12 @@ How to Minify JavaScripts and Stylesheets with YUI Compressor **strongly advised to avoid using YUI utilities** unless strictly necessary. Read :doc:`/cookbook/assetic/uglifyjs` for a modern and up-to-date alternative. +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + Yahoo! provides an excellent utility for minifying JavaScripts and stylesheets so they travel over the wire faster, the `YUI Compressor`_. Thanks to Assetic, you can take advantage of this tool very easily. diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst index c775fc4a407..925f1cf7ac7 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -4,6 +4,12 @@ AsseticBundle Configuration ("assetic") ======================================= +.. caution:: + + Starting from Symfony 2.8, Assetic is no longer included by default in the + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. + Full Default Configuration -------------------------- diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst index 8fd0c083ec9..e19857b8843 100644 --- a/reference/twig_reference.rst +++ b/reference/twig_reference.rst @@ -739,10 +739,7 @@ Those bundles can have other Twig extensions: * **Twig Extensions** includes some interesting extensions that do not belong to the Twig core. You can read more in `the official Twig Extensions - documentation`_; -* **Assetic** adds the ``{% stylesheets %}``, ``{% javascripts %}`` and - ``{% image %}`` tags. You can read more about them in - :doc:`the Assetic Documentation `. + documentation`_. .. _`Twig Reference`: http://twig.sensiolabs.org/documentation#reference .. _`the official Twig Extensions documentation`: http://twig.sensiolabs.org/doc/extensions/index.html