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``