diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst new file mode 100644 index 00000000000..5f8d3b539fd --- /dev/null +++ b/cookbook/assetic/asset_management.rst @@ -0,0 +1,227 @@ +How to Use Assetic for Asset Management +======================================= + +Assetic is an asset management library which is packaged with the standard +Symfony2 distribution, it has a bundle to allow it to be easily used +in Symfony2 directly from Twig or PHP templates. It works with assets and +filters. The assets are files such as CSS, JavaScript and images files. +There are various filters 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 using Assetic or another asset manager you are just directly serving +up the files that are stored in the application: + +.. configuration-block:: + + .. code-block:: html+jinja + + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AcmeFooBundle/Resources/public/js/*')) as $url): ?> + + + +You can also combine several files into one. This helps to reduce the number +of HTTP requests which is good for front end performance, as most browsers +will only process a limited number at a time slowing down page load times. +It also allows you to maintain the files more easily by splitting them into +manageable parts. This can also 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:: + + .. code-block:: html+jinja + + {% javascripts '@AcmeFooBundle/Resources/public/js/*' + '@AcmeBarBundle/Resources/public/js/form.js' + '@AcmeBarBundle/Resources/public/js/calendar.js' + %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AcmeFooBundle/Resources/public/js/*', + '@AcmeBarBundle/Resources/public/js/form.js', + '@AcmeBarBundle/Resources/public/js/calendar.js')) as $url): ?> + + + + +This does not only apply to your own files you can also use Assetic to +combine third party assets, such as jQuery with your own into a single file: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% javascripts '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js' + '@AcmeFooBundle/Resources/public/js/*' + %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js', + '@AcmeFooBundle/Resources/public/js/*')) as $url): ?> + + + +Filters +------- + +Additionally to this Assetic can apply filters to the assets before they +are served. This includes tasks such as compressing the output for smaller +file sizes which is another valuable front end optimisation. Other filters +include compiling JavaScript file from CoffeeScript files and SASS to CSS. + +Many of the filters do not do the work directly but use other libraries +to do it, this so you will often have to install that software as well. +The great advantage of using Assetic to invoke these libraries is that +instead of having to run them manually when you have worked on the files, +Assetic will take care of this for you and remove this step altogether +from your development and deployment processes. + +To use a filter you must specify it in the Assetic configuration +as they are not enabled by default. For example to use the JavaScript YUI +Compressor the following config needs to be added: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + assetic: + filters: + yui_js: + jar: "%kernel.root_dir%/Resources/java/yuicompressor.jar" + + .. code-block:: xml + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('assetic', array( + 'filters' => array( + 'yui_js' => array( + 'jar' => '%kernel.root_dir%/Resources/java/yuicompressor.jar', + ), + ), + )); + + +You can then specify using the filter in the template: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% javascripts '@AcmeFooBundle/Resources/public/js/*' filter='yui_js' %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AcmeFooBundle/Resources/public/js/*'), + array('yui_js')) as $url): ?> + + + + +A more detail guide to configuring and using Assetic filters as well as +details of Assetic's debug mode can be found in :doc:`/cookbook/assetic/yuicompressor`. + +Controlling the URL used +------------------------ + +If you wish to you can control the URLs which Assetic produces. This is +done from the template and is relative to the public document root: + +.. configuration-block:: + + .. code-block:: html+jinja + + {% javascripts '@AcmeFooBundle/Resources/public/js/*' + output='js/combined.js' + %} + + {% endjavascripts %} + + .. code-block:: html+php + + javascripts( + array('@AcmeFooBundle/Resources/public/js/*'), + array(), + array('output' => 'js/combined.js') + ) as $url): ?> + + + +Caching the output +------------------ + +The process of creating the files served up can be quite slow especially +when using some of the filters which invoke third party software to the +actual work. Even when working in the development environment the slow +down in the page loads if this was to be done each time would quickly get +frustrating. Fortunately in the dev environment Assetic caches the output +so this will not happen, rather than having to clear the cache manually +though, it monitors for changes to the assets and regenerates the files +as needed. This means you can work on the asset files and see the results +on page load but without having to suffer continual slow page loads. + +For production, where you will not be making changes to the asset files, +performance can be increased by avoiding the step of checking for changes. +Assetic allows you to go further than this and avoid touching Symfony2 +and even PHP at all when serving the files. This is done by dumping all +of the output files using a console command. These can then be served directly +by the web server as static files, increasing performance and allowing the +web server to deal with caching headers. The console command to dump the files +is: + +.. code-block:: bash + + php app/console assetic:dump + +.. note:: + + Once you have dumped the output you will need to run the console + command again to see any new changes. If you run it on your development + server you will need to remove the files in order to start letting Assetic + process the assets on the fly again.