Use the Twig namespaced syntax for all templates

Author: javiereguiluz

best_practices/templates.rst

@@ -30,22 +30,20 @@ Template Locations
     Store all your application's templates in ``app/Resources/views/`` directory.
 
 Traditionally, Symfony developers stored the application templates in the
-``Resources/views/`` directory of each bundle. Then they used the logical name
-to refer to them (e.g. ``AcmeDemoBundle:Default:index.html.twig``).
+``Resources/views/`` directory of each bundle. Then they used the Twig namespaced
+path to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``).
 
 But for the templates used in your application, it's much more convenient
 to store them in the ``app/Resources/views/`` directory. For starters, this
 drastically simplifies their logical names:
 
-=================================================  ==================================
-Templates Stored inside Bundles                    Templates Stored in ``app/``
-=================================================  ==================================
-``AcmeDemoBundle:Default:index.html.twig``         ``default/index.html.twig``
-``::layout.html.twig``                             ``layout.html.twig``
-``AcmeDemoBundle::index.html.twig``                ``index.html.twig``
-``AcmeDemoBundle:Default:subdir/index.html.twig``  ``default/subdir/index.html.twig``
-``AcmeDemoBundle:Default/subdir:index.html.twig``  ``default/subdir/index.html.twig``
-=================================================  ==================================
+============================================  ==================================
+Templates Stored inside Bundles               Templates Stored in ``app/``
+============================================  ==================================
+``@AcmeDemo/index.html.twig``                 ``index.html.twig``
+``@AcmeDemo/Default/index.html.twig``         ``default/index.html.twig``
+``@AcmeDemo/Default/subdir/index.html.twig``  ``default/subdir/index.html.twig``
+============================================  ==================================
 
 Another advantage is that centralizing your templates simplifies the work
 of your designers. They don't need to look for templates in lots of directories

components/form.rst

@@ -408,7 +408,7 @@ is created from the form factory.
                     ->add('dueDate', 'date')
                     ->getForm();
 
-                return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
+                return $this->render('@AcmeTask/Default/new.html.twig', array(
                     'form' => $form->createView(),
                 ));
             }

controller/service.rst

@@ -177,7 +177,7 @@ Symfony's base controller::
         public function indexAction($name)
         {
             return $this->render(
-                'AppBundle:Hello:index.html.twig',
+                '@App/Hello/index.html.twig',
                 array('name' => $name)
             );
         }
@@ -213,7 +213,7 @@ service and use it directly::
         public function indexAction($name)
         {
             return $this->templating->renderResponse(
-                'AppBundle:Hello:index.html.twig',
+                '@App/Hello/index.html.twig',
                 array('name' => $name)
             );
         }

form/direct_submit.rst

@@ -28,7 +28,7 @@ submissions::
             return $this->redirectToRoute('task_success');
         }
 
-        return $this->render('AppBundle:Default:new.html.twig', array(
+        return $this->render('@App/Default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }
@@ -67,7 +67,7 @@ method, pass the submitted data directly to
             }
         }
 
-        return $this->render('AppBundle:Default:new.html.twig', array(
+        return $this->render('@App/Default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }
@@ -126,7 +126,7 @@ a convenient shortcut to the previous example::
             }
         }
 
-        return $this->render('AppBundle:Default:new.html.twig', array(
+        return $this->render('@App/Default/new.html.twig', array(
             'form' => $form->createView(),
         ));
     }

form/dynamic_form_modification.rst

@@ -616,7 +616,7 @@ your application. Assume that you have a sport meetup creation controller::
             }
 
             return $this->render(
-                'AppBundle:Meetup:create.html.twig',
+                '@App/Meetup/create.html.twig',
                 array('form' => $form->createView())
             );
         }

form/form_collections.rst

@@ -184,7 +184,7 @@ In your controller, you'll now initialize a new instance of ``TaskType``::
                 // ... maybe do some form processing, like saving the Task and Tag objects
             }
 
-            return $this->render('AppBundle:Task:new.html.twig', array(
+            return $this->render('@App/Task/new.html.twig', array(
                 'form' => $form->createView(),
             ));
         }

form/form_customization.rst

@@ -327,8 +327,8 @@ name of all the templates as an array using the ``with`` keyword:
 
     {# ... #}
 
-The templates can also be located in different bundles, use the functional name
-to reference these templates, e.g. ``AcmeFormExtraBundle:form:fields.html.twig``.
+The templates can also be located in different bundles, use the Twig namespaced
+path to reference these templates, e.g. ``@AcmeFormExtra/form/fields.html.twig``.
 
 Child Forms
 ...........

reference/configuration/twig.rst

@@ -22,7 +22,7 @@ TwigBundle Configuration ("twig")
                 - bootstrap_3_horizontal_layout.html.twig
 
                 # Example:
-                - MyBundle::form.html.twig
+                - @App/form.html.twig
 
             globals:
 
@@ -75,7 +75,7 @@ TwigBundle Configuration ("twig")
                 optimizations="true"
             >
                 <twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
-                <twig:form-theme>MyBundle::form.html.twig</twig:form-theme>
+                <twig:form-theme>@App/form.html.twig</twig:form-theme>
 
                 <twig:global key="foo" id="bar" type="service" />
                 <twig:global key="pi">3.14</twig:global>
@@ -91,7 +91,7 @@ TwigBundle Configuration ("twig")
         $container->loadFromExtension('twig', array(
             'form_themes' => array(
                 'form_div_layout.html.twig', // Default
-                'MyBundle::form.html.twig',
+                '@App/form.html.twig',
              ),
              'globals' => array(
                  'foo' => '@bar',

templating.rst

@@ -270,11 +270,9 @@ A child template might look like this:
 
 .. note::
 
-   The parent template is identified by a special string syntax
-   (``base.html.twig``). This path is relative to the ``app/Resources/views``
-   directory of the project. You could also use the logical name equivalent:
-   ``::base.html.twig``. This naming convention is explained fully in
-   :ref:`template-naming-locations`.
+   The parent template is stored in ``app/Resources/views/``, so its path is
+   simply ``base.html.twig``. The template naming conventions are explained
+   fully in :ref:`template-naming-locations`.
 
 The key to template inheritance is the ``{% extends %}`` tag. This tells
 the templating engine to first evaluate the base template, which sets up
@@ -382,43 +380,36 @@ to render/extend ``app/Resources/views/base.html.twig``, you'll use the
 Referencing Templates in a Bundle
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*If* you need to refer to a template that lives in a bundle, Symfony uses a **bundle**:**directory**:**filename**
-string syntax. This allows for several types of templates, each which lives in a
-specific location:
+*If* you need to refer to a template that lives in a bundle, Symfony uses the
+Twig namespaced syntax (``@BundleName/directory/filename.html.twig``). This allows
+for several types of templates, each which lives in a specific location:
 
-* ``AcmeBlogBundle:Blog:index.html.twig``: This syntax is used to specify a
+* ``@AcmeBlog/Blog/index.html.twig``: This syntax is used to specify a
   template for a specific page. The three parts of the string, each separated
-  by a colon (``:``), mean the following:
+  by a slash (``/``), mean the following:
 
-  * ``AcmeBlogBundle``: (*bundle*) the template lives inside the AcmeBlogBundle
-    (e.g. ``src/Acme/BlogBundle``);
+  * ``@AcmeBlog``: is the bundle name without the ``Bundle`` suffix. This template
+    lives in the AcmeBlogBundle (e.g. ``src/Acme/BlogBundle``);
 
   * ``Blog``: (*directory*) indicates that the template lives inside the
-    ``Blog`` subdirectory of ``Resources/views``;
+    ``Blog`` subdirectory of ``Resources/views/``;
 
   * ``index.html.twig``: (*filename*) the actual name of the file is
     ``index.html.twig``.
 
   Assuming that the AcmeBlogBundle lives at ``src/Acme/BlogBundle``, the
   final path to the layout would be ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``.
 
-* ``AcmeBlogBundle::layout.html.twig``: This syntax refers to a base template
+* ``@AcmeBlog/layout.html.twig``: This syntax refers to a base template
   that's specific to the AcmeBlogBundle. Since the middle, "directory", portion
   is missing (e.g. ``Blog``), the template lives at
-  ``Resources/views/layout.html.twig`` inside AcmeBlogBundle. Yes, there are 2
-  colons in the middle of the string when the "controller" subdirectory part is
-  missing.
+  ``Resources/views/layout.html.twig`` inside AcmeBlogBundle.
 
 In the :doc:`/templating/overriding` section, you'll find out how each
 template living inside the AcmeBlogBundle, for example, can be overridden
 by placing a template of the same name in the ``app/Resources/AcmeBlogBundle/views/``
 directory. This gives the power to override templates from any vendor bundle.
 
-.. tip::
-
-    Hopefully the template naming syntax looks familiar - it's similar to
-    the naming convention used to refer to :ref:`controller-string-syntax`.
-
 Template Suffix
 ~~~~~~~~~~~~~~~
 

templating/namespaced_paths.rst

@@ -4,31 +4,26 @@
 How to Use and Register Namespaced Twig Paths
 =============================================
 
-Usually, when you refer to a template, you'll use the ``MyBundle:Subdir:filename.html.twig``
-format (see :ref:`template-naming-locations`).
-
-Twig also natively offers a feature called "namespaced paths", and support
-is built-in automatically for all of your bundles.
-
-Take the following paths as an example:
-
-.. code-block:: twig
-
-    {% extends "AppBundle::layout.html.twig" %}
-    {{ include('AppBundle:Foo:bar.html.twig') }}
-
-With namespaced paths, the following works as well:
+Usually, when you refer to a template, you'll use the Twig namespaced paths, which
+are automatically registered for your bundles:
 
 .. code-block:: twig
 
     {% extends "@App/layout.html.twig" %}
     {{ include('@App/Foo/bar.html.twig') }}
 
-Both paths are valid and functional by default in Symfony.
+.. note::
+
+    In the past, Symfony used a different syntax to refer to templates. This
+    format, which uses colons (``:``) to separate each template path section, is
+    less consistent and has worse performance than the Twig syntax. For reference
+    purposes, this is the equivalent notation of the previous example:
 
-.. tip::
+    .. code-block:: twig
 
-    As an added bonus, the namespaced syntax is faster.
+        {# the following template syntax is no longer recommended #}
+        {% extends "AppBundle::layout.html.twig" %}
+        {{ include('AppBundle:Foo:bar.html.twig') }}
 
 Registering your own Namespaces
 -------------------------------