From 0764dffc47176271d830d2dd88ba5ffcac33d639 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Dec 2015 16:05:24 +0100 Subject: [PATCH 1/4] Addee caution notes about the removal of AsseticBundle in 2.8/3.0 --- best_practices/web-assets.rst | 10 ++++++++++ book/templating.rst | 6 +++--- cookbook/assetic/apply_to_option.rst | 10 ++++++++++ cookbook/assetic/asset_management.rst | 10 ++++++++++ cookbook/assetic/index.rst | 10 ++++++++++ cookbook/assetic/jpeg_optimize.rst | 10 ++++++++++ cookbook/assetic/php.rst | 10 ++++++++++ cookbook/assetic/uglifyjs.rst | 10 ++++++++++ cookbook/assetic/yuicompressor.rst | 10 ++++++++++ reference/configuration/assetic.rst | 10 ++++++++++ reference/twig_reference.rst | 5 +---- 11 files changed, 94 insertions(+), 7 deletions(-) diff --git a/best_practices/web-assets.rst b/best_practices/web-assets.rst index a4160d62e2e..de75e080088 100644 --- a/best_practices/web-assets.rst +++ b/best_practices/web-assets.rst @@ -35,6 +35,16 @@ much more concise: Using Assetic ------------- +.. caution:: + + 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 command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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..4b904211e82 100644 --- a/cookbook/assetic/apply_to_option.rst +++ b/cookbook/assetic/apply_to_option.rst @@ -4,6 +4,16 @@ 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. Before using any of its features, install the + AsseticBundle executing this command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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..d688731dc4a 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -4,6 +4,16 @@ How to Use Assetic for Asset Management ======================================= +.. caution:: + + 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 command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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..1ef4d7a3760 100644 --- a/cookbook/assetic/index.rst +++ b/cookbook/assetic/index.rst @@ -1,6 +1,16 @@ Assetic ======= +.. caution:: + + 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 command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + .. toctree:: :maxdepth: 2 diff --git a/cookbook/assetic/jpeg_optimize.rst b/cookbook/assetic/jpeg_optimize.rst index c55a32dc800..690faab4e34 100644 --- a/cookbook/assetic/jpeg_optimize.rst +++ b/cookbook/assetic/jpeg_optimize.rst @@ -4,6 +4,16 @@ 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. Before using any of its features, install the + AsseticBundle executing this command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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..7b3e0b4e186 100644 --- a/cookbook/assetic/php.rst +++ b/cookbook/assetic/php.rst @@ -4,6 +4,16 @@ 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. Before using any of its features, install the + AsseticBundle executing this command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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..fe3a5540394 100644 --- a/cookbook/assetic/uglifyjs.rst +++ b/cookbook/assetic/uglifyjs.rst @@ -4,6 +4,16 @@ 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. Before using any of its features, install the + AsseticBundle executing this command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + `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 66cb5364ec7..8eeaff3ac2a 100644 --- a/cookbook/assetic/yuicompressor.rst +++ b/cookbook/assetic/yuicompressor.rst @@ -10,6 +10,16 @@ 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. Before using any of its features, install the + AsseticBundle executing this command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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 5a355b92932..a91ff2a7cb7 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -4,6 +4,16 @@ AsseticBundle Configuration ("assetic") ======================================= +.. caution:: + + 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 command command in your project: + + .. code-block:: cli + + $ composer install symfony/assetic-bundle + 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 From d2e51dad4b125ac9db2ada88af5a8100e7b573b2 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Dec 2015 17:32:14 +0100 Subject: [PATCH 2/4] Reworded the caution notes about AsseticBundle --- best_practices/web-assets.rst | 8 +--- cookbook/assetic/apply_to_option.rst | 8 +--- cookbook/assetic/asset_management.rst | 55 ++++++++++++++++++++++++++- cookbook/assetic/index.rst | 8 +--- cookbook/assetic/jpeg_optimize.rst | 8 +--- cookbook/assetic/php.rst | 8 +--- cookbook/assetic/uglifyjs.rst | 8 +--- cookbook/assetic/yuicompressor.rst | 8 +--- reference/configuration/assetic.rst | 8 +--- 9 files changed, 69 insertions(+), 50 deletions(-) diff --git a/best_practices/web-assets.rst b/best_practices/web-assets.rst index de75e080088..61a992b8181 100644 --- a/best_practices/web-assets.rst +++ b/best_practices/web-assets.rst @@ -38,12 +38,8 @@ Using Assetic .. caution:: 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 command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 diff --git a/cookbook/assetic/apply_to_option.rst b/cookbook/assetic/apply_to_option.rst index 4b904211e82..6f132ec4641 100644 --- a/cookbook/assetic/apply_to_option.rst +++ b/cookbook/assetic/apply_to_option.rst @@ -7,12 +7,8 @@ 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. Before using any of its features, install the - AsseticBundle executing this command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index d688731dc4a..7c93c105c57 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -10,9 +10,60 @@ How to Use Assetic for Asset Management Symfony Standard Edition. Before using any of its features, install the AsseticBundle executing this command command in your project: - .. code-block:: cli + .. code-block:: bash - $ composer install symfony/assetic-bundle + $ composer require symfony/assetic-bundle + + Then, enable the bundle by adding the following configuration under the + ``asetic`` key: + + .. 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, + ), + // ... + )); + + // ... Assetic combines two major ideas: :ref:`assets ` and :ref:`filters `. The assets are files such as CSS, diff --git a/cookbook/assetic/index.rst b/cookbook/assetic/index.rst index 1ef4d7a3760..8d2ac650587 100644 --- a/cookbook/assetic/index.rst +++ b/cookbook/assetic/index.rst @@ -4,12 +4,8 @@ Assetic .. caution:: 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 command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 690faab4e34..d479fdd8893 100644 --- a/cookbook/assetic/jpeg_optimize.rst +++ b/cookbook/assetic/jpeg_optimize.rst @@ -7,12 +7,8 @@ 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. Before using any of its features, install the - AsseticBundle executing this command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 diff --git a/cookbook/assetic/php.rst b/cookbook/assetic/php.rst index 7b3e0b4e186..3bde1e7aef2 100644 --- a/cookbook/assetic/php.rst +++ b/cookbook/assetic/php.rst @@ -7,12 +7,8 @@ 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. Before using any of its features, install the - AsseticBundle executing this command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 diff --git a/cookbook/assetic/uglifyjs.rst b/cookbook/assetic/uglifyjs.rst index fe3a5540394..47eb82ba4f6 100644 --- a/cookbook/assetic/uglifyjs.rst +++ b/cookbook/assetic/uglifyjs.rst @@ -7,12 +7,8 @@ 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. Before using any of its features, install the - AsseticBundle executing this command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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 diff --git a/cookbook/assetic/yuicompressor.rst b/cookbook/assetic/yuicompressor.rst index 8eeaff3ac2a..698b9ab8ab9 100644 --- a/cookbook/assetic/yuicompressor.rst +++ b/cookbook/assetic/yuicompressor.rst @@ -13,12 +13,8 @@ How to Minify JavaScripts and Stylesheets with YUI Compressor .. caution:: 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 command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + 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, diff --git a/reference/configuration/assetic.rst b/reference/configuration/assetic.rst index a91ff2a7cb7..16636e3271f 100644 --- a/reference/configuration/assetic.rst +++ b/reference/configuration/assetic.rst @@ -7,12 +7,8 @@ AsseticBundle Configuration ("assetic") .. caution:: 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 command command in your project: - - .. code-block:: cli - - $ composer install symfony/assetic-bundle + Symfony Standard Edition. Refer to :doc:`this article ` + to learn how to install and enable Assetic in your Symfony application. Full Default Configuration -------------------------- From ee942d9eccd1ce4a2a5ccf7b465b8a14709a749c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 7 Dec 2015 17:38:12 +0100 Subject: [PATCH 3/4] Fixed a typo --- cookbook/assetic/asset_management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 7c93c105c57..5f53de39a46 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -8,7 +8,7 @@ How to Use Assetic for Asset Management 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 command command in your project: + AsseticBundle executing this console command in your project: .. code-block:: bash From 8e896e68a907582462b6c524dcc496e917a4f3a5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 9 Dec 2015 18:00:42 +0100 Subject: [PATCH 4/4] Reworded everything --- cookbook/assetic/asset_management.rst | 106 ++++++++++++++++---------- 1 file changed, 65 insertions(+), 41 deletions(-) diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 5f53de39a46..6fa15d80e5d 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -4,66 +4,90 @@ How to Use Assetic for Asset Management ======================================= -.. caution:: +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: +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 by adding the following configuration under the - ``asetic`` key: +Then, enable the bundle in the ``AppKernel`` file of your Symfony application:: - .. configuration-block:: + // app/AppKernel.php - .. code-block:: yaml + // ... + class AppKernel extends Kernel + { + // ... - # app/config/config.yml - assetic: - debug: "%kernel.debug%" - use_controller: false - filters: - cssrewrite: ~ + public function registerBundles() + { + $bundles = array( + // ... + new Symfony\Bundle\AsseticBundle\AsseticBundle(), + ); - # ... + // ... + } + } - .. code-block:: xml +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:: php + # ... - // app/config/config.php + .. code-block:: xml - $container->loadFromExtension('assetic', array( - 'debug' => '%kernel.debug%', - 'use_controller' => '%kernel.debug%', - 'filters' => array( - 'cssrewrite' => null, - ), - // ... - )); + + + + + + + + + + + + .. 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,