Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit c4c2179

Browse filesBrowse files
xabbuhxabbuh
committed
minor #8120 Use the Twig namespaced syntax for all templates (javiereguiluz)
This PR was merged into the 2.7 branch. Discussion ---------- Use the Twig namespaced syntax for all templates This fixes #7003. Commits ------- 858dd81 Use the Twig namespaced syntax for all templates
2 parents 08001c7 + 858dd81 commit c4c2179
Copy full SHA for c4c2179

File tree

Expand file treeCollapse file tree

11 files changed

+51
-67
lines changed
Filter options
Expand file treeCollapse file tree

11 files changed

+51
-67
lines changed

‎best_practices/templates.rst

Copy file name to clipboardExpand all lines: best_practices/templates.rst
+9-11Lines changed: 9 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,22 +30,20 @@ Template Locations
3030
Store all your application's templates in ``app/Resources/views/`` directory.
3131

3232
Traditionally, Symfony developers stored the application templates in the
33-
``Resources/views/`` directory of each bundle. Then they used the logical name
34-
to refer to them (e.g. ``AcmeDemoBundle:Default:index.html.twig``).
33+
``Resources/views/`` directory of each bundle. Then they used the Twig namespaced
34+
path to refer to them (e.g. ``@AcmeDemo/Default/index.html.twig``).
3535

3636
But for the templates used in your application, it's much more convenient
3737
to store them in the ``app/Resources/views/`` directory. For starters, this
3838
drastically simplifies their logical names:
3939

40-
================================================= ==================================
41-
Templates Stored inside Bundles Templates Stored in ``app/``
42-
================================================= ==================================
43-
``AcmeDemoBundle:Default:index.html.twig`` ``default/index.html.twig``
44-
``::layout.html.twig`` ``layout.html.twig``
45-
``AcmeDemoBundle::index.html.twig`` ``index.html.twig``
46-
``AcmeDemoBundle:Default:subdir/index.html.twig`` ``default/subdir/index.html.twig``
47-
``AcmeDemoBundle:Default/subdir:index.html.twig`` ``default/subdir/index.html.twig``
48-
================================================= ==================================
40+
============================================ ==================================
41+
Templates Stored inside Bundles Templates Stored in ``app/``
42+
============================================ ==================================
43+
``@AcmeDemo/index.html.twig`` ``index.html.twig``
44+
``@AcmeDemo/Default/index.html.twig`` ``default/index.html.twig``
45+
``@AcmeDemo/Default/subdir/index.html.twig`` ``default/subdir/index.html.twig``
46+
============================================ ==================================
4947

5048
Another advantage is that centralizing your templates simplifies the work
5149
of your designers. They don't need to look for templates in lots of directories

‎components/form.rst

Copy file name to clipboardExpand all lines: components/form.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -408,7 +408,7 @@ is created from the form factory.
408408
->add('dueDate', 'date')
409409
->getForm();
410410
411-
return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
411+
return $this->render('@AcmeTask/Default/new.html.twig', array(
412412
'form' => $form->createView(),
413413
));
414414
}

‎controller/service.rst

Copy file name to clipboardExpand all lines: controller/service.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -177,7 +177,7 @@ Symfony's base controller::
177177
public function indexAction($name)
178178
{
179179
return $this->render(
180-
'AppBundle:Hello:index.html.twig',
180+
'@App/Hello/index.html.twig',
181181
array('name' => $name)
182182
);
183183
}
@@ -213,7 +213,7 @@ service and use it directly::
213213
public function indexAction($name)
214214
{
215215
return $this->templating->renderResponse(
216-
'AppBundle:Hello:index.html.twig',
216+
'@App/Hello/index.html.twig',
217217
array('name' => $name)
218218
);
219219
}

‎form/direct_submit.rst

Copy file name to clipboardExpand all lines: form/direct_submit.rst
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ submissions::
2828
return $this->redirectToRoute('task_success');
2929
}
3030

31-
return $this->render('AppBundle:Default:new.html.twig', array(
31+
return $this->render('@App/Default/new.html.twig', array(
3232
'form' => $form->createView(),
3333
));
3434
}
@@ -67,7 +67,7 @@ method, pass the submitted data directly to
6767
}
6868
}
6969

70-
return $this->render('AppBundle:Default:new.html.twig', array(
70+
return $this->render('@App/Default/new.html.twig', array(
7171
'form' => $form->createView(),
7272
));
7373
}
@@ -126,7 +126,7 @@ a convenient shortcut to the previous example::
126126
}
127127
}
128128

129-
return $this->render('AppBundle:Default:new.html.twig', array(
129+
return $this->render('@App/Default/new.html.twig', array(
130130
'form' => $form->createView(),
131131
));
132132
}

‎form/dynamic_form_modification.rst

Copy file name to clipboardExpand all lines: form/dynamic_form_modification.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,7 @@ your application. Assume that you have a sport meetup creation controller::
616616
}
617617

618618
return $this->render(
619-
'AppBundle:Meetup:create.html.twig',
619+
'@App/Meetup/create.html.twig',
620620
array('form' => $form->createView())
621621
);
622622
}

‎form/form_collections.rst

Copy file name to clipboardExpand all lines: form/form_collections.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,7 +184,7 @@ In your controller, you'll now initialize a new instance of ``TaskType``::
184184
// ... maybe do some form processing, like saving the Task and Tag objects
185185
}
186186

187-
return $this->render('AppBundle:Task:new.html.twig', array(
187+
return $this->render('@App/Task/new.html.twig', array(
188188
'form' => $form->createView(),
189189
));
190190
}

‎form/form_customization.rst

Copy file name to clipboardExpand all lines: form/form_customization.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -327,8 +327,8 @@ name of all the templates as an array using the ``with`` keyword:
327327

328328
{# ... #}
329329

330-
The templates can also be located in different bundles, use the functional name
331-
to reference these templates, e.g. ``AcmeFormExtraBundle:form:fields.html.twig``.
330+
The templates can also be located in different bundles, use the Twig namespaced
331+
path to reference these templates, e.g. ``@AcmeFormExtra/form/fields.html.twig``.
332332

333333
Child Forms
334334
...........

‎reference/configuration/twig.rst

Copy file name to clipboardExpand all lines: reference/configuration/twig.rst
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ TwigBundle Configuration ("twig")
2222
- bootstrap_3_horizontal_layout.html.twig
2323
2424
# Example:
25-
- MyBundle::form.html.twig
25+
- @App/form.html.twig
2626
2727
globals:
2828
@@ -75,7 +75,7 @@ TwigBundle Configuration ("twig")
7575
optimizations="true"
7676
>
7777
<twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
78-
<twig:form-theme>MyBundle::form.html.twig</twig:form-theme>
78+
<twig:form-theme>@App/form.html.twig</twig:form-theme>
7979
8080
<twig:global key="foo" id="bar" type="service" />
8181
<twig:global key="pi">3.14</twig:global>
@@ -91,7 +91,7 @@ TwigBundle Configuration ("twig")
9191
$container->loadFromExtension('twig', array(
9292
'form_themes' => array(
9393
'form_div_layout.html.twig', // Default
94-
'MyBundle::form.html.twig',
94+
'@App/form.html.twig',
9595
),
9696
'globals' => array(
9797
'foo' => '@bar',

‎templating.rst

Copy file name to clipboardExpand all lines: templating.rst
+13-22Lines changed: 13 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -270,11 +270,9 @@ A child template might look like this:
270270

271271
.. note::
272272

273-
The parent template is identified by a special string syntax
274-
(``base.html.twig``). This path is relative to the ``app/Resources/views``
275-
directory of the project. You could also use the logical name equivalent:
276-
``::base.html.twig``. This naming convention is explained fully in
277-
:ref:`template-naming-locations`.
273+
The parent template is stored in ``app/Resources/views/``, so its path is
274+
simply ``base.html.twig``. The template naming conventions are explained
275+
fully in :ref:`template-naming-locations`.
278276

279277
The key to template inheritance is the ``{% extends %}`` tag. This tells
280278
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
382380
Referencing Templates in a Bundle
383381
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
384382

385-
*If* you need to refer to a template that lives in a bundle, Symfony uses a **bundle**:**directory**:**filename**
386-
string syntax. This allows for several types of templates, each which lives in a
387-
specific location:
383+
*If* you need to refer to a template that lives in a bundle, Symfony uses the
384+
Twig namespaced syntax (``@BundleName/directory/filename.html.twig``). This allows
385+
for several types of templates, each which lives in a specific location:
388386

389-
* ``AcmeBlogBundle:Blog:index.html.twig``: This syntax is used to specify a
387+
* ``@AcmeBlog/Blog/index.html.twig``: This syntax is used to specify a
390388
template for a specific page. The three parts of the string, each separated
391-
by a colon (``:``), mean the following:
389+
by a slash (``/``), mean the following:
392390

393-
* ``AcmeBlogBundle``: (*bundle*) the template lives inside the AcmeBlogBundle
394-
(e.g. ``src/Acme/BlogBundle``);
391+
* ``@AcmeBlog``: is the bundle name without the ``Bundle`` suffix. This template
392+
lives in the AcmeBlogBundle (e.g. ``src/Acme/BlogBundle``);
395393

396394
* ``Blog``: (*directory*) indicates that the template lives inside the
397-
``Blog`` subdirectory of ``Resources/views``;
395+
``Blog`` subdirectory of ``Resources/views/``;
398396

399397
* ``index.html.twig``: (*filename*) the actual name of the file is
400398
``index.html.twig``.
401399

402400
Assuming that the AcmeBlogBundle lives at ``src/Acme/BlogBundle``, the
403401
final path to the layout would be ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``.
404402

405-
* ``AcmeBlogBundle::layout.html.twig``: This syntax refers to a base template
403+
* ``@AcmeBlog/layout.html.twig``: This syntax refers to a base template
406404
that's specific to the AcmeBlogBundle. Since the middle, "directory", portion
407405
is missing (e.g. ``Blog``), the template lives at
408-
``Resources/views/layout.html.twig`` inside AcmeBlogBundle. Yes, there are 2
409-
colons in the middle of the string when the "controller" subdirectory part is
410-
missing.
406+
``Resources/views/layout.html.twig`` inside AcmeBlogBundle.
411407

412408
In the :doc:`/templating/overriding` section, you'll find out how each
413409
template living inside the AcmeBlogBundle, for example, can be overridden
414410
by placing a template of the same name in the ``app/Resources/AcmeBlogBundle/views/``
415411
directory. This gives the power to override templates from any vendor bundle.
416412

417-
.. tip::
418-
419-
Hopefully the template naming syntax looks familiar - it's similar to
420-
the naming convention used to refer to :ref:`controller-string-syntax`.
421-
422413
Template Suffix
423414
~~~~~~~~~~~~~~~
424415

‎templating/namespaced_paths.rst

Copy file name to clipboardExpand all lines: templating/namespaced_paths.rst
+12-17Lines changed: 12 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,31 +4,26 @@
44
How to Use and Register Namespaced Twig Paths
55
=============================================
66

7-
Usually, when you refer to a template, you'll use the ``MyBundle:Subdir:filename.html.twig``
8-
format (see :ref:`template-naming-locations`).
9-
10-
Twig also natively offers a feature called "namespaced paths", and support
11-
is built-in automatically for all of your bundles.
12-
13-
Take the following paths as an example:
14-
15-
.. code-block:: twig
16-
17-
{% extends "AppBundle::layout.html.twig" %}
18-
{{ include('AppBundle:Foo:bar.html.twig') }}
19-
20-
With namespaced paths, the following works as well:
7+
Usually, when you refer to a template, you'll use the Twig namespaced paths, which
8+
are automatically registered for your bundles:
219

2210
.. code-block:: twig
2311
2412
{% extends "@App/layout.html.twig" %}
2513
{{ include('@App/Foo/bar.html.twig') }}
2614
27-
Both paths are valid and functional by default in Symfony.
15+
.. note::
16+
17+
In the past, Symfony used a different syntax to refer to templates. This
18+
format, which uses colons (``:``) to separate each template path section, is
19+
less consistent and has worse performance than the Twig syntax. For reference
20+
purposes, this is the equivalent notation of the previous example:
2821

29-
.. tip::
22+
.. code-block:: twig
3023
31-
As an added bonus, the namespaced syntax is faster.
24+
{# the following template syntax is no longer recommended #}
25+
{% extends "AppBundle::layout.html.twig" %}
26+
{{ include('AppBundle:Foo:bar.html.twig') }}
3227
3328
Registering your own Namespaces
3429
-------------------------------

‎templating/overriding.rst

Copy file name to clipboardExpand all lines: templating/overriding.rst
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ following::
2121
$blogs = ...;
2222

2323
$this->render(
24-
'AcmeBlogBundle:Blog:index.html.twig',
24+
'@AcmeBlog/Blog/index.html.twig',
2525
array('blogs' => $blogs)
2626
);
2727
}
2828

29-
When the ``AcmeBlogBundle:Blog:index.html.twig`` is rendered, Symfony actually
30-
looks in two different locations for the template:
29+
When ``@AcmeBlog/Blog/index.html.twig`` is rendered, Symfony actually looks in
30+
two different locations for the template:
3131

3232
#. ``app/Resources/AcmeBlogBundle/views/Blog/index.html.twig``
3333
#. ``src/Acme/BlogBundle/Resources/views/Blog/index.html.twig``
@@ -44,7 +44,7 @@ to create it). You're now free to customize the template.
4444

4545
This logic also applies to base bundle templates. Suppose also that each
4646
template in AcmeBlogBundle inherits from a base template called
47-
``AcmeBlogBundle::layout.html.twig``. Just as before, Symfony will look in
47+
``@AcmeBlog/layout.html.twig``. Just as before, Symfony will look in
4848
the following two places for the template:
4949

5050
#. ``app/Resources/AcmeBlogBundle/views/layout.html.twig``

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.