|
| 1 | +..index:: |
| 2 | + single: Assetic; UglifyJs |
| 3 | + |
| 4 | +How to Minify JavaScripts with UglifyJs |
| 5 | +============================================================= |
| 6 | + |
| 7 | +`UglifyJs`_ is a javascript parser/compressor/beautifier toolkit. It can be used |
| 8 | +to combine and minify javascript assets so they need less HTTP requests and makes |
| 9 | +the website load faster. |
| 10 | + |
| 11 | +Install UglifyJs |
| 12 | +------------------------------- |
| 13 | + |
| 14 | +UglifyJs is build as an node.js npm module and can be installed using npm. First, you |
| 15 | +need to `install node.js`_. Afterwards you can install UglifyJs using npm: |
| 16 | + |
| 17 | +..code-block::bash |
| 18 | +
|
| 19 | + $ npm install -g uglifyjs |
| 20 | +
|
| 21 | +..note:: |
| 22 | + |
| 23 | + It's also possible to install UglifyJs for your symfony project only. To do this, |
| 24 | + install it without the ``-g`` option and specify the path where to put the module: |
| 25 | + |
| 26 | + ..code-block::bash |
| 27 | +
|
| 28 | + $ npm install uglifyjs /path/to/symfony/app |
| 29 | +
|
| 30 | + It is recommended that you install uglifyjs in your app folder and add the ``node_modules`` |
| 31 | + folder to version control. |
| 32 | + |
| 33 | +Configure the UglifyJs Filter |
| 34 | +------------------------- |
| 35 | + |
| 36 | +Now we need to configure symfony2 to use the UglifyJs Filter when processing your |
| 37 | +stylesheets: |
| 38 | + |
| 39 | +..configuration-block:: |
| 40 | + |
| 41 | + ..code-block::yaml |
| 42 | +
|
| 43 | +# app/config/config.yml |
| 44 | +assetic: |
| 45 | +filters: |
| 46 | +uglifyjs: |
| 47 | +bin:/usr/local/bin/uglifyjs |
| 48 | +
|
| 49 | + ..code-block::xml |
| 50 | +
|
| 51 | +<!-- app/config/config.xml--> |
| 52 | + <assetic:config> |
| 53 | + <assetic:filter |
| 54 | +name="uglifyjs" |
| 55 | +bin="/usr/local/bin/uglifyjs" /> |
| 56 | + </assetic:config> |
| 57 | +
|
| 58 | + ..code-block::php |
| 59 | +
|
| 60 | + // app/config/config.php |
| 61 | + $container->loadFromExtension('assetic', array( |
| 62 | + 'filters' => array( |
| 63 | + 'uglifyjs' => array( |
| 64 | + 'bin' => '/usr/local/bin/uglifyjs', |
| 65 | + ), |
| 66 | + ), |
| 67 | + )); |
| 68 | +
|
| 69 | +..note:: |
| 70 | + |
| 71 | + The path where uglifyjs is installed may vary depending on your system. |
| 72 | + To find out where npm stores the bin folder, you can use the following |
| 73 | + command: |
| 74 | + |
| 75 | + ..code-block::bash |
| 76 | +
|
| 77 | + $ npm bin -g |
| 78 | +
|
| 79 | + It should output a folder on your system, inside which you should find |
| 80 | + the uglifyjs executable. |
| 81 | + |
| 82 | + If you installed uglifyjs locally, you can find the bin folder inside |
| 83 | + the ``node_modules`` folder. It's called ``.bin`` in this case. |
| 84 | + |
| 85 | +You now have access to the ``uglifyjs`` Filter in your application. |
| 86 | + |
| 87 | +Minify your Assets |
| 88 | +------------------ |
| 89 | + |
| 90 | +In order to use UglifyJs on your assets, you need to apply it to them. Since |
| 91 | +your assets are a part of the view layer, this work is done in your templates: |
| 92 | + |
| 93 | +..configuration-block:: |
| 94 | + |
| 95 | + ..code-block::html+jinja |
| 96 | + |
| 97 | + {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='uglifyjs' %} |
| 98 | + <script src="{{ asset_url }}"></script> |
| 99 | + {% endjavascripts %} |
| 100 | +
|
| 101 | + ..code-block::html+php |
| 102 | + |
| 103 | + <?php foreach ($view['assetic']->javascripts( |
| 104 | + array('@AcmeFooBundle/Resources/public/js/*'), |
| 105 | + array('uglifyjs') |
| 106 | + ) as $url): ?> |
| 107 | + <script src="<?php echo $view->escape($url) ?>"></script> |
| 108 | + <?php endforeach; ?> |
| 109 | +
|
| 110 | +..note:: |
| 111 | + |
| 112 | + The above example assumes that you have a bundle called ``AcmeFooBundle`` |
| 113 | + and your JavaScript files are in the ``Resources/public/js`` directory under |
| 114 | + your bundle. This isn't important however - you can include your Javascript |
| 115 | + files no matter where they are. |
| 116 | + |
| 117 | +With the addition of the ``uglifyjs`` filter to the asset tags above, you should |
| 118 | +now see minified JavaScripts coming over the wire much faster. |
| 119 | + |
| 120 | +Disable Minification in Debug Mode |
| 121 | +---------------------------------- |
| 122 | + |
| 123 | +Minified JavaScripts are very difficult to read, let alone |
| 124 | +debug. Because of this, Assetic lets you disable a certain filter when your |
| 125 | +application is in debug mode. You can do this by prefixing the filter name |
| 126 | +in your template with a question mark: ``?``. This tells Assetic to only |
| 127 | +apply this filter when debug mode is off. |
| 128 | + |
| 129 | +..configuration-block:: |
| 130 | + |
| 131 | + ..code-block::html+jinja |
| 132 | + |
| 133 | + {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='?uglifyjs' %} |
| 134 | + <script src="{{ asset_url }}"></script> |
| 135 | + {% endjavascripts %} |
| 136 | +
|
| 137 | + ..code-block::html+php |
| 138 | + |
| 139 | + <?php foreach ($view['assetic']->javascripts( |
| 140 | + array('@AcmeFooBundle/Resources/public/js/*'), |
| 141 | + array('?uglifyjs') |
| 142 | + ) as $url): ?> |
| 143 | + <script src="<?php echo $view->escape($url) ?>"></script> |
| 144 | + <?php endforeach; ?> |
| 145 | +
|
| 146 | + |
| 147 | +..tip:: |
| 148 | + |
| 149 | + Instead of adding the filter to the asset tags, you can also globally |
| 150 | + enable it by adding the apply-to attribute to the filter configuration, for |
| 151 | + example in the ``uglifyjs`` filter ``apply_to: "\.js$"``. To only have the filter |
| 152 | + applied in production, add this to the config_prod file rather than the |
| 153 | + common config file. For details on applying filters by file extension, |
| 154 | + see:ref:`cookbook-assetic-apply-to`. |
| 155 | + |
| 156 | + |
| 157 | +.. _`UglifyJs`:https://github.com/mishoo/UglifyJS |
| 158 | +.. _`install node.js`:http://nodejs.org/ |