From 3e6e2b1497c1984acb5b11d34f406dec92fc209f Mon Sep 17 00:00:00 2001
From: Richard Miller <richard.miller@limethinking.co.uk>
Date: Mon, 27 Jun 2011 16:08:17 +0100
Subject: [PATCH 1/2] Adding general assetic cookbook article

---
 cookbook/assetic/asset_management.rst | 227 ++++++++++++++++++++++++++
 1 file changed, 227 insertions(+)
 create mode 100644 cookbook/assetic/asset_management.rst

diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst
new file mode 100644
index 00000000000..75e716f0c68
--- /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
+
+        <script src="{{ asset('js/script.js') }}" type="text/javascript" />
+
+    .. code-block:: php
+
+        <script src="<?php echo $view['assets']->getUrl('js/script.js') ?>"
+                type="text/javascript" />
+
+Assets
+------
+
+Using Assetic provides many advantages over directly serving the files.
+The files do not need to be stored where they are served from and can be
+drawn from various sources such as within a bundle:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% javascripts '@AcmeFooBundle/Resources/public/js/*'
+        %}
+        <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array('@AcmeFooBundle/Resources/public/js/*')) as $url): ?>
+        <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
+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'
+        %}
+        <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array('@AcmeFooBundle/Resources/public/js/*',
+                  '@AcmeBarBundle/Resources/public/js/form.js',
+                  '@AcmeBarBundle/Resources/public/js/calendar.js')) as $url): ?>
+        <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
+
+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/*'
+        %}
+        <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array('@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
+                  '@AcmeFooBundle/Resources/public/js/*')) as $url): ?>
+        <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
+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
+
+        <!-- app/config/config.xml -->
+        <assetic:config>
+            <assetic:filter
+                name="yui_js"
+                jar="%kernel.root_dir%/Resources/java/yuicompressor.jar" />
+        </assetic:config>
+
+    .. 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' %}
+        <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array('@AcmeFooBundle/Resources/public/js/*'),
+            array('yui_js')) as $url): ?>
+        <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
+
+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'
+        %}
+        <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array('@AcmeFooBundle/Resources/public/js/*'),
+            array(),
+            array('output' => 'js/combined.js')
+        ) as $url): ?>
+        <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
+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 this 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.

From ca1bf53fec9c8e2e663f5e0548d2d1fa427073aa Mon Sep 17 00:00:00 2001
From: Richard Miller <richard.miller@limethinking.co.uk>
Date: Mon, 27 Jun 2011 16:29:32 +0100
Subject: [PATCH 2/2] Removed unneeded ``this``

---
 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 75e716f0c68..5f8d3b539fd 100644
--- a/cookbook/assetic/asset_management.rst
+++ b/cookbook/assetic/asset_management.rst
@@ -221,7 +221,7 @@ is:
 
 .. note::
 
-    Once you have dumped the output this you will need to run the console
+    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.