From f418e201d59753ae51f7c19b9c1ff7f1abc46610 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Mar 2015 11:25:17 +0100 Subject: [PATCH 1/2] Reviewed the Assetic cookbook articles --- cookbook/assetic/apply_to_option.rst | 21 ++++---- cookbook/assetic/asset_management.rst | 34 ++++++------ cookbook/assetic/jpeg_optimize.rst | 31 +++++------ cookbook/assetic/uglifyjs.rst | 75 +++++++++++++++------------ cookbook/assetic/yuicompressor.rst | 17 +++--- 5 files changed, 88 insertions(+), 90 deletions(-) diff --git a/cookbook/assetic/apply_to_option.rst b/cookbook/assetic/apply_to_option.rst index eedc6e8e7af..29615b09214 100644 --- a/cookbook/assetic/apply_to_option.rst +++ b/cookbook/assetic/apply_to_option.rst @@ -9,7 +9,7 @@ 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 filter, which compiles CoffeeScript files into JavaScript. -The main configuration is just the paths to coffee, node and node_modules. +The main configuration is just the paths to ``coffee``, ``node`` and ``node_modules``. An example configuration might look like this: .. configuration-block:: @@ -102,8 +102,7 @@ You can also combine multiple CoffeeScript files into a single output file: -Both the files will now be served up as a single file compiled into regular -JavaScript. +Both files will now be served up as a single file compiled into regular JavaScript. .. _cookbook-assetic-apply-to: @@ -117,10 +116,10 @@ since they will ultimately all be served as JavaScript. Unfortunately just adding the JavaScript files to the files to be combined as above will not work as the regular JavaScript files will not survive the CoffeeScript compilation. -This problem can be avoided by using the ``apply_to`` option in the config, -which allows you to specify which filter should always be applied to particular -file extensions. In this case you can specify that the ``coffee`` filter is -applied to all ``.coffee`` files: +This problem can be avoided by using the ``apply_to`` option, which allows you +to specify which filter should always be applied to particular file extensions. +In this case you can specify that the ``coffee`` filter is applied to all +``.coffee`` files: .. configuration-block:: @@ -161,10 +160,10 @@ applied to all ``.coffee`` files: ), )); -With this, you no longer need to specify the ``coffee`` filter in the template. -You can also list regular JavaScript files, all of which will be combined -and rendered as a single JavaScript file (with only the ``.coffee`` files -being run through the CoffeeScript filter): +With this option, you no longer need to specify the ``coffee`` filter in the +template. You can also list regular JavaScript files, all of which will be +combined and rendered as a single JavaScript file (with only the ``.coffee`` +files being run through the CoffeeScript filter): .. configuration-block:: diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst index 8a84bbd0e43..503036bb3fe 100644 --- a/cookbook/assetic/asset_management.rst +++ b/cookbook/assetic/asset_management.rst @@ -73,9 +73,9 @@ To include JavaScript files, use the ``javascripts`` tag in any template: .. note:: - If you're using the default block names from the Symfony Standard Edition, - the ``javascripts`` tag will most commonly live in the ``javascripts`` - block: + If your application templates use the default block names from the Symfony + Standard Edition, the ``javascripts`` tag will most commonly live in the + ``javascripts`` block: .. code-block:: html+jinja @@ -108,8 +108,8 @@ that reference images by their relative path. See :ref:`cookbook-assetic-cssrewr Including CSS Stylesheets ~~~~~~~~~~~~~~~~~~~~~~~~~ -To bring in CSS stylesheets, you can use the same methodologies seen -above, except with the ``stylesheets`` tag: +To bring in CSS stylesheets, you can use the same technique explained above, +except with the ``stylesheets`` tag: .. configuration-block:: @@ -130,9 +130,9 @@ above, except with the ``stylesheets`` tag: .. note:: - If you're using the default block names from the Symfony Standard Edition, - the ``stylesheets`` tag will most commonly live in the ``stylesheets`` - block: + If your application templates use the default block names from the Symfony + Standard Edition, the ``stylesheets`` tag will most commonly live in the + ``stylesheets`` block: .. code-block:: html+jinja @@ -204,7 +204,7 @@ Combining Assets ~~~~~~~~~~~~~~~~ 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. +to reduce the number of HTTP requests, which is great for frontend 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, @@ -350,7 +350,7 @@ Filters Once they're managed by Assetic, you can apply filters to your assets before they are served. This includes filters that compress the output of your assets -for smaller file sizes (and better front-end optimization). Other filters +for smaller file sizes (and better frontend optimization). Other filters can compile JavaScript file from CoffeeScript files and process SASS into CSS. In fact, Assetic has a long list of available filters. @@ -366,8 +366,8 @@ To use a filter, you first need to specify it in the Assetic configuration. Adding a filter here doesn't mean it's being used - it just means that it's available to use (you'll use the filter below). -For example to use the UglifyJS JavaScript minifier the following config should -be added: +For example to use the UglifyJS JavaScript minifier the following configuration +should be defined: .. configuration-block:: @@ -489,8 +489,8 @@ environment is just too slow. .. _cookbook-assetic-dump-prod: -Instead, each time you use your app in the ``prod`` environment (and therefore, -each time you deploy), you should run the following task: +Instead, each time you use your application in the ``prod`` environment (and therefore, +each time you deploy), you should run the following command: .. code-block:: bash @@ -532,7 +532,7 @@ the following change in your ``config_dev.yml`` file: )); Next, since Symfony is no longer generating these assets for you, you'll -need to dump them manually. To do so, run the following: +need to dump them manually. To do so, run the following command: .. code-block:: bash @@ -547,8 +547,8 @@ assets will be regenerated automatically *as they change*: $ php app/console assetic:watch -The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior -versions, you had to use the ``--watch`` option of the ``assetic:dump`` +The ``assetic:watch`` command was introduced in AsseticBundle 2.4. In prior +versions, you had to use the ``--watch`` option of the ``assetic:dump`` command for the same behavior. Since running this command in the ``dev`` environment may generate a bunch diff --git a/cookbook/assetic/jpeg_optimize.rst b/cookbook/assetic/jpeg_optimize.rst index 7955771ca02..d3aebeb9e94 100644 --- a/cookbook/assetic/jpeg_optimize.rst +++ b/cookbook/assetic/jpeg_optimize.rst @@ -13,8 +13,9 @@ for your end users. Using Jpegoptim --------------- -`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic, -add the following to the Assetic config: +`Jpegoptim`_ is a utility for optimizing JPEG files. To use it with Assetic, make +sure to have it already installed on your system and then, configure its location +using the ``bin`` option of the ``jpegoptim`` filter: .. configuration-block:: @@ -46,11 +47,6 @@ add the following to the Assetic config: ), )); -.. note:: - - Notice that to use jpegoptim, you must have it already installed on your - system. The ``bin`` option points to the location of the compiled binary. - It can now be used from a template: .. configuration-block:: @@ -74,9 +70,9 @@ It can now be used from a template: Removing all EXIF Data ~~~~~~~~~~~~~~~~~~~~~~ -By default, running this filter only removes some of the meta information -stored in the file. Any EXIF data and comments are not removed, but you can -remove these by using the ``strip_all`` option: +By default, the ``jpegoptim`` filter removes some of the meta information stored +in the image. To remove all EXIF data and comments, set the ``strip_all`` option +to ``true``: .. configuration-block:: @@ -111,13 +107,13 @@ remove these by using the ``strip_all`` option: ), )); -Lowering maximum Quality +Lowering Maximum Quality ~~~~~~~~~~~~~~~~~~~~~~~~ -The quality level of the JPEG is not affected by default. You can gain -further file size reductions by setting the max quality setting lower than -the current level of the images. This will of course be at the expense of -image quality: +By default, the ``jpegoptim`` filter doesn't alter the quality level of the JPEG +image. Use the ``max`` option to configure the maximum quality setting (in a +scale of ``0`` to ``100``). The reduction in the image file size will of course +be at the expense of its quality: .. configuration-block:: @@ -157,7 +153,7 @@ Shorter Syntax: Twig Function If you're using Twig, it's possible to achieve all of this with a shorter syntax by enabling and using a special Twig function. Start by adding the -following config: +following configuration: .. configuration-block:: @@ -206,7 +202,8 @@ The Twig template can now be changed to the following: Example -You can specify the output directory in the config in the following way: +You can also specify the output directory for images in the Assetic configuration +file: .. configuration-block:: diff --git a/cookbook/assetic/uglifyjs.rst b/cookbook/assetic/uglifyjs.rst index 8b0ddd66028..1ca7cf69d1f 100644 --- a/cookbook/assetic/uglifyjs.rst +++ b/cookbook/assetic/uglifyjs.rst @@ -16,41 +16,47 @@ talked about briefly. Install UglifyJS ---------------- -UglifyJS is available as an `Node.js`_ npm module and can be installed using -npm. First, you need to `install Node.js`_. Afterwards you can install UglifyJS -using npm: +UglifyJS is available as a `Node.js`_ module. First, you need to `install Node.js`_ +and then, decide the installation method: global or local. + +Global Installation +~~~~~~~~~~~~~~~~~~~ + +The global installation method makes all your projects use the very same UglifyJS +version, which simplifies its maintenance. Open your command console and execute +the following command (you may need to run it as a root user): .. code-block:: bash $ npm install -g uglify-js -This command will install UglifyJS globally and you may need to run it as -a root user. +Now you can execute the global ``uglifyjs`` command anywhere on your system: -.. note:: +.. code-block:: bash - It's also possible to install UglifyJS inside your project only. To do - this, install it without the ``-g`` option and specify the path where - to put the module: + $ uglifyjs --help - .. code-block:: bash +Local Installation +~~~~~~~~~~~~~~~~~~ - $ cd /path/to/symfony - $ mkdir app/Resources/node_modules - $ npm install uglify-js --prefix app/Resources +It's also possible to install UglifyJS inside your project only, which is useful +when your project requires an specific UglifyJS version. To do this, install it +without the ``-g`` option and specify the path where to put the module: - It is recommended that you install UglifyJS in your ``app/Resources`` folder - and add the ``node_modules`` folder to version control. Alternatively, - you can create an npm `package.json`_ file and specify your dependencies - there. +.. code-block:: bash -Depending on your installation method, you should either be able to execute -the ``uglifyjs`` executable globally, or execute the physical file that lives -in the ``node_modules`` directory: + $ cd /path/to/your/symfony/project + $ mkdir app/Resources/node_modules + $ npm install uglify-js --prefix app/Resources -.. code-block:: bash +It is recommended that you install UglifyJS in your ``app/Resources`` folder and +add the ``node_modules`` folder to version control. Alternatively, you can create +an npm `package.json`_ file and specify your dependencies there. - $ uglifyjs --help +Now you can execute the ``uglifyjs`` command that lives in the ``node_modules`` +directory: + +.. code-block:: bash $ ./app/Resources/node_modules/.bin/uglifyjs --help @@ -96,8 +102,7 @@ your JavaScripts: .. note:: The path where UglifyJS is installed may vary depending on your system. - To find out where npm stores the ``bin`` folder, you can use the following - command: + To find out where npm stores the ``bin`` folder, execute the following command: .. code-block:: bash @@ -154,8 +159,8 @@ can configure its location using the ``node`` key: Minify your Assets ------------------ -In order to use UglifyJS on your assets, you need to apply it to them. Since -your assets are a part of the view layer, this work is done in your templates: +In order to apply UglifyJS on your assets, add the ``filter`` option in the +asset tags of your templates to tell Assetic to use the ``uglifyjs2`` filter: .. configuration-block:: @@ -178,8 +183,7 @@ your assets are a part of the view layer, this work is done in your templates: The above example assumes that you have a bundle called AppBundle and your JavaScript files are in the ``Resources/public/js`` directory under your - bundle. This isn't important however - you can include your JavaScript - files no matter where they are. + bundle. However you can include your JavaScript files no matter where they are. With the addition of the ``uglifyjs2`` filter to the asset tags above, you should now see minified JavaScripts coming over the wire much faster. @@ -216,12 +220,9 @@ and :ref:`dump your assetic assets `. .. tip:: - Instead of adding the filter to the asset tags, you can also globally - enable it by adding the ``apply_to`` attribute to the filter configuration, for - example in the ``uglifyjs2`` filter ``apply_to: "\.js$"``. To only have - the filter applied in production, add this to the ``config_prod`` file - rather than the common config file. For details on applying filters by - file extension, see :ref:`cookbook-assetic-apply-to`. + Instead of adding the filters to the asset tags, you can also configure which + filters to apply for each file in your application configuration file. + See :ref:`cookbook-assetic-apply-to` for more details. Install, Configure and Use UglifyCSS ------------------------------------ @@ -231,8 +232,14 @@ the node package is installed: .. code-block:: bash + # global installation $ npm install -g uglifycss + # local installation + $ cd /path/to/your/symfony/project + $ mkdir app/Resources/node_modules + $ npm install uglifycss --prefix app/Resources + Next, add the configuration for this filter: .. configuration-block:: diff --git a/cookbook/assetic/yuicompressor.rst b/cookbook/assetic/yuicompressor.rst index 356b67b6071..dccb8351a56 100644 --- a/cookbook/assetic/yuicompressor.rst +++ b/cookbook/assetic/yuicompressor.rst @@ -4,19 +4,15 @@ How to Minify JavaScripts and Stylesheets with YUI Compressor ============================================================= -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. - .. caution:: - The YUI Compressor is `no longer maintained by Yahoo`_ but by an independent - volunteer. Moreover, Yahoo has decided to `stop all new development on YUI`_ - and to move to other modern alternatives such as Node.js. + The YUI Compressor is `no longer maintained by Yahoo`_. That's why you are + **strongly advised to avoid using YUI utilities** unless strictly necessary. + Read :doc:`/cookbook/assetic/uglifyjs` for a modern and up-to-date alternative. - That's why you are **strongly advised** to avoid using YUI utilities unless - strictly necessary. Read :doc:`/cookbook/assetic/uglifyjs` for a modern and - up-to-date alternative. +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. Download the YUI Compressor JAR ------------------------------- @@ -170,4 +166,3 @@ apply this filter when debug mode is off. .. _`YUI Compressor`: http://developer.yahoo.com/yui/compressor/ .. _`Download the JAR`: https://github.com/yui/yuicompressor/releases .. _`no longer maintained by Yahoo`: http://www.yuiblog.com/blog/2013/01/24/yui-compressor-has-a-new-owner/ -.. _`stop all new development on YUI`: http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui From 22ccd76cb771e1bc2beac7156f2b89cdb1a0de58 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 19 Mar 2015 11:55:02 +0100 Subject: [PATCH 2/2] Fixed a path for Windows --- cookbook/assetic/uglifyjs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/assetic/uglifyjs.rst b/cookbook/assetic/uglifyjs.rst index 1ca7cf69d1f..54a06bfbc7e 100644 --- a/cookbook/assetic/uglifyjs.rst +++ b/cookbook/assetic/uglifyjs.rst @@ -58,7 +58,7 @@ directory: .. code-block:: bash - $ ./app/Resources/node_modules/.bin/uglifyjs --help + $ "./app/Resources/node_modules/.bin/uglifyjs" --help Configure the ``uglifyjs2`` Filter ----------------------------------