Added a note about configuring several paths under the same namespace

Author: javiereguiluz

Diff for: cookbook/templating/namespaced_paths.rst

@@ -81,3 +81,56 @@ called ``sidebar.twig`` in that directory, you can use it easily:
 .. code-block:: jinja
 
     {% include '@foo_bar/sidebar.twig' %}
+
+Multiple paths per namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also assign several paths to the same template namespace. The order in
+which paths are configured is very important, because Twig will always load
+the first template that exists, starting from the first configured path. This
+feature can be used as a fallback mechanism to load generic templates when the
+specific template doesn't exist.
+
+    .. code-block:: yaml
+
+        # app/config/config.yml
+        twig:
+            # ...
+            paths:
+                "%kernel.root_dir%/../vendor/acme/themes/theme1": theme
+                "%kernel.root_dir%/../vendor/acme/themes/theme2": theme
+                "%kernel.root_dir%/../vendor/acme/themes/common": theme
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xmlns:twig="http://symfony.com/schema/dic/twig"
+        >
+
+            <twig:config debug="%kernel.debug%" strict-variables="%kernel.debug%">
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/theme1</twig:path>
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/theme2</twig:path>
+                <twig:path namespace="theme">%kernel.root_dir%/../vendor/acme/themes/common</twig:path>
+            </twig:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config.php
+        $container->loadFromExtension('twig', array(
+            'paths' => array(
+                '%kernel.root_dir%/../vendor/acme/themes/theme1' => 'theme',
+                '%kernel.root_dir%/../vendor/acme/themes/theme2' => 'theme',
+                '%kernel.root_dir%/../vendor/acme/themes/common' => 'theme',
+            );
+        ));
+
+Now you can use the same ``@theme`` namespace to refer to any template located
+in the previous three directories:
+
+.. code-block:: jinja
+
+    {% include '@theme/header.twig' %}