diff --git a/best_practices/templates.rst b/best_practices/templates.rst
index da09b535d43..86bfd38576d 100644
--- a/best_practices/templates.rst
+++ b/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
diff --git a/components/form.rst b/components/form.rst
index 1ab45b155bd..dbbd05c6ecb 100644
--- a/components/form.rst
+++ b/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(),
));
}
diff --git a/controller/service.rst b/controller/service.rst
index 8c9c0179a70..6cff4b477da 100644
--- a/controller/service.rst
+++ b/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)
);
}
diff --git a/form/direct_submit.rst b/form/direct_submit.rst
index 8c700ccd33d..42af84ec465 100644
--- a/form/direct_submit.rst
+++ b/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(),
));
}
diff --git a/form/dynamic_form_modification.rst b/form/dynamic_form_modification.rst
index 6c8dc979405..cadb876eea8 100644
--- a/form/dynamic_form_modification.rst
+++ b/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())
);
}
diff --git a/form/form_collections.rst b/form/form_collections.rst
index 26fc88ea9fa..148bd167c04 100644
--- a/form/form_collections.rst
+++ b/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(),
));
}
diff --git a/form/form_customization.rst b/form/form_customization.rst
index fe17a0e7a2f..4d4805b2d2f 100644
--- a/form/form_customization.rst
+++ b/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
...........
diff --git a/reference/configuration/twig.rst b/reference/configuration/twig.rst
index 79fcd4161af..6a34da1db07 100644
--- a/reference/configuration/twig.rst
+++ b/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"
>
form_div_layout.html.twig
- MyBundle::form.html.twig
+ @App/form.html.twig
3.14
@@ -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',
diff --git a/templating.rst b/templating.rst
index 9c350a6d5de..cb416362201 100644
--- a/templating.rst
+++ b/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,19 +380,19 @@ 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``.
@@ -402,23 +400,16 @@ specific location:
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
~~~~~~~~~~~~~~~
diff --git a/templating/namespaced_paths.rst b/templating/namespaced_paths.rst
index 03834cc06ba..c9f0b9d4167 100644
--- a/templating/namespaced_paths.rst
+++ b/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
-------------------------------
diff --git a/templating/overriding.rst b/templating/overriding.rst
index 2e90f801d91..f6fb12c9034 100644
--- a/templating/overriding.rst
+++ b/templating/overriding.rst
@@ -21,13 +21,13 @@ following::
$blogs = ...;
$this->render(
- 'AcmeBlogBundle:Blog:index.html.twig',
+ '@AcmeBlog/Blog/index.html.twig',
array('blogs' => $blogs)
);
}
-When the ``AcmeBlogBundle:Blog:index.html.twig`` is rendered, Symfony actually
-looks in two different locations for the template:
+When ``@AcmeBlog/Blog/index.html.twig`` is rendered, Symfony actually looks in
+two different locations for the template:
#. ``app/Resources/AcmeBlogBundle/views/Blog/index.html.twig``
#. ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``
@@ -44,7 +44,7 @@ to create it). You're now free to customize the template.
This logic also applies to base bundle templates. Suppose also that each
template in AcmeBlogBundle inherits from a base template called
-``AcmeBlogBundle::layout.html.twig``. Just as before, Symfony will look in
+``@AcmeBlog/layout.html.twig``. Just as before, Symfony will look in
the following two places for the template:
#. ``app/Resources/AcmeBlogBundle/views/layout.html.twig``