From 4c8402e2e4e17c31f72e19a2ab1327fd3cb2cb01 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Wed, 6 Jun 2018 12:41:15 +0200 Subject: [PATCH 1/3] Updated the embed controllers article --- templating/embedding_controllers.rst | 32 ++++++++++++---------------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/templating/embedding_controllers.rst b/templating/embedding_controllers.rst index 45f223180b3..c884ec40a56 100644 --- a/templating/embedding_controllers.rst +++ b/templating/embedding_controllers.rst @@ -4,14 +4,13 @@ How to Embed Controllers in a Template ====================================== -In some cases, you need to do more than include a simple template. Suppose -you have a sidebar in your layout that contains the three most recent articles. -Retrieving the three articles may include querying the database or performing -other heavy logic that can't be done from within a template. +Including template fragments is a simple way to reuse common contents among +templates. However, the contents of the included templates are static, so you +can't use them to implement features like displaying in a sidebar the most +recent articles (which require making a database query). -The solution is to simply embed the result of an entire controller from your -template. First, create a controller that renders a certain number of recent -articles:: +The solution is to call a controller from the template and output its result. +First, create a controller that renders a certain number of recent articles:: // src/AppBundle/Controller/ArticleController.php namespace AppBundle\Controller; @@ -33,7 +32,8 @@ articles:: } } -The ``recent_list`` template is perfectly straightforward: +Then, create a ``recent_list`` template fragment to list the articles given by +the controller: .. configuration-block:: @@ -41,7 +41,7 @@ The ``recent_list`` template is perfectly straightforward: {# app/Resources/views/article/recent_list.html.twig #} {% for article in articles %} - + {{ article.title }} {% endfor %} @@ -50,19 +50,15 @@ The ``recent_list`` template is perfectly straightforward: - + getTitle() ?> -.. note:: - - Notice that the article URL is hardcoded in this example - (e.g. ``/article/*slug*``). This is a bad practice. In the next section, - you'll learn how to do this correctly. - -To include the controller, you'll need to refer to it using the standard -string syntax for controllers (i.e. **bundle**:**controller**:**action**): +Finally, call the controller from any template using the ``render()`` function +and the common syntax for controllers (i.e. **bundle**:**controller**:**action**): .. configuration-block:: From 67ad44e02d97763dae12ca8ae385320a715971b2 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 7 Jun 2018 09:58:58 +0200 Subject: [PATCH 2/3] Reword --- quick_tour/the_view.rst | 2 ++ templating/embedding_controllers.rst | 23 +++++++++++++++-------- 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst index 6254099475f..d7f8337fc0f 100644 --- a/quick_tour/the_view.rst +++ b/quick_tour/the_view.rst @@ -159,6 +159,8 @@ extensively to modify the information before displaying it to the user: Don't forget to check out the official `Twig documentation`_ to learn everything about filters, functions and tags. +.. including-other-templates: + Including other Templates ------------------------- diff --git a/templating/embedding_controllers.rst b/templating/embedding_controllers.rst index c884ec40a56..61ff3fd1a65 100644 --- a/templating/embedding_controllers.rst +++ b/templating/embedding_controllers.rst @@ -4,12 +4,20 @@ How to Embed Controllers in a Template ====================================== -Including template fragments is a simple way to reuse common contents among -templates. However, the contents of the included templates are static, so you -can't use them to implement features like displaying in a sidebar the most -recent articles (which require making a database query). +:ref:`Including template fragments ` is useful to +reuse the same content on several pages. However, this technique is not the best +solution in some cases. + +Consider a website that displays on its sidebar the most recently published +articles. This list of articles is dynamic and it's probably the result of a +database query. In other words, the controller of any page that displays that +sidebar must make the same database query and pass the list of articles to the +included template fragment. + +The alternative solution proposed by Symfony is to create a controller that only +displays the list of recent articles and then call to that controller from any +template that needs to display that content. -The solution is to call a controller from the template and output its result. First, create a controller that renders a certain number of recent articles:: // src/AppBundle/Controller/ArticleController.php @@ -90,6 +98,5 @@ and the common syntax for controllers (i.e. **bundle**:**controller**:**action** Whenever you find that you need a variable or a piece of information that you don't have access to in a template, consider rendering a controller. -Controllers are fast to execute and promote good code organization and reuse. -Of course, like all controllers, they should ideally be "skinny", meaning -that as much code as possible lives in reusable :doc:`services `. +Make sure that embedded controllers are fast to execute to not hurt performance +and that they follow Symfony's :doc:`best practices for controllers `. From 6693eefa6a07edeaea9fdcef376b1873b94565b0 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 7 Jun 2018 10:12:20 +0200 Subject: [PATCH 3/3] Fix RST syntax --- quick_tour/the_view.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quick_tour/the_view.rst b/quick_tour/the_view.rst index d7f8337fc0f..bf0aea76d6b 100644 --- a/quick_tour/the_view.rst +++ b/quick_tour/the_view.rst @@ -159,7 +159,7 @@ extensively to modify the information before displaying it to the user: Don't forget to check out the official `Twig documentation`_ to learn everything about filters, functions and tags. -.. including-other-templates: +.. _including-other-templates: Including other Templates -------------------------