feature symfony#3496 Added a section about using named assets (vmattila)

weaverryan · weaverryan · commit 527c8b6d9042 · 2014-02-03T20:53:23.000-06:00
This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes symfony#3496). Discussion ---------- Added a section about using named assets This PR will add a section about named assets to the asset management page. | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | all | Fixed tickets | Commits ------- 9c9743e Added a section about using named assets
diff --git a/cookbook/assetic/asset_management.rst b/cookbook/assetic/asset_management.rst
@@ -270,6 +270,79 @@ combine third party assets, such as jQuery, with your own into a single file:
             <script src="<?php echo $view->escape($url) ?>"></script>
         <?php endforeach; ?>
 
+Using Named Assets
+~~~~~~~~~~~~~~~~~~
+
+AsseticBundle configuration directives allow you to define named asset sets.
+You can do so by defining the input files, filters and output files in your
+configuration under the ``assetic`` section. Read more in the
+:doc:`assetic config reference </reference/configuration/assetic>`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        assetic:
+            assets:
+                jquery_and_ui:
+                    inputs:
+                        - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js'
+                        - '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js'
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:assetic="http://symfony.com/schema/dic/assetic">
+
+            <assetic:config>
+                <assetic:asset name="jquery_and_ui">
+                    <assetic:input>@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js</assetic:input>
+                    <assetic:input>@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js</assetic:input>
+                </assetic:asset>
+            </assetic:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('assetic', array(
+            'assets' => array(
+                'jquery_and_ui' => array(
+                    'inputs' => array(
+                        '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.js',
+                        '@AcmeFooBundle/Resources/public/js/thirdparty/jquery.ui.js',
+                    ),
+                ),
+            ),
+        );
+
+After you have defined the named assets, you can reference them in your templates
+with the ``@named_asset`` notation:
+
+.. configuration-block::
+
+    .. code-block:: html+jinja
+
+        {% javascripts
+            '@jquery_and_ui'
+            '@AcmeFooBundle/Resources/public/js/*' %}
+            <script src="{{ asset_url }}"></script>
+        {% endjavascripts %}
+
+    .. code-block:: html+php
+
+        <?php foreach ($view['assetic']->javascripts(
+            array(
+                '@jquery_and_ui',
+                '@AcmeFooBundle/Resources/public/js/*',
+            )
+        ) as $url): ?>
+            <script src="<?php echo $view->escape($url) ?>"></script>
+        <?php endforeach; ?>
+
 .. _cookbook-assetic-filters:
 
 Filters
