Merge branch '2.8' into 3.4

* 2.8:
  Better explain render() and render_esi() functions
  Updated the embed controllers article
  Use <button> instead of <a> for JavaScript interactive buttons

Author: javiereguiluz

form/form_collections.rst

@@ -353,8 +353,8 @@ will be show next):
     var $collectionHolder;
 
     // setup an "add a tag" link
-    var $addTagLink = $('<a href="#" class="add_tag_link">Add a tag</a>');
-    var $newLinkLi = $('<li></li>').append($addTagLink);
+    var $addTagButton = $('<button type="button" class="add_tag_link">Add a tag</a>');
+    var $newLinkLi = $('<li></li>').append($addTagButton);
 
     jQuery(document).ready(function() {
         // Get the ul that holds the collection of tags
@@ -367,10 +367,7 @@ will be show next):
         // index when inserting a new item (e.g. 2)
         $collectionHolder.data('index', $collectionHolder.find(':input').length);
 
-        $addTagLink.on('click', function(e) {
-            // prevent the link from creating a "#" on the URL
-            e.preventDefault();
-
+        $addTagButton.on('click', function(e) {
             // add a new tag form (see next code block)
             addTagForm($collectionHolder, $newLinkLi);
         });
@@ -619,7 +616,7 @@ Template Modifications
 
 The ``allow_delete`` option means that if an item of a collection
 isn't sent on submission, the related data is removed from the collection
-on the server. In order for this to work in an HTML form, you must remove 
+on the server. In order for this to work in an HTML form, you must remove
 the DOM element for the collection item to be removed, before submitting
 the form.
 
@@ -651,13 +648,10 @@ The ``addTagFormDeleteLink()`` function will look something like this:
 .. code-block:: javascript
 
     function addTagFormDeleteLink($tagFormLi) {
-        var $removeFormA = $('<a href="#">delete this tag</a>');
-        $tagFormLi.append($removeFormA);
-
-        $removeFormA.on('click', function(e) {
-            // prevent the link from creating a "#" on the URL
-            e.preventDefault();
+        var $removeFormButton = $('<button type="button">Delete this tag</a>');
+        $tagFormLi.append($removeFormButton);
 
+        $removeFormButton.on('click', function(e) {
             // remove the li for the tag form
             $tagFormLi.remove();
         });

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

reference/forms/types/collection.rst

@@ -167,7 +167,6 @@ you need is this JavaScript code:
     // add-collection-widget.js
     jQuery(document).ready(function () {
         jQuery('.add-another-collection-widget').click(function (e) {
-            e.preventDefault();
             var list = jQuery(jQuery(this).attr('data-list'));
             // Try to find the counter of the list
             var counter = list.data('widget-counter') | list.children().length;
@@ -210,7 +209,7 @@ And update the template as follows:
         {% endfor %}
         </ul>
 
-        <a href="#"
+        <button type="button"
             class="add-another-collection-widget"
             data-list="#email-fields-list">Add another email</a>
 

reference/twig_reference.rst

@@ -53,14 +53,21 @@ render
 ``options`` *(optional)*
     **type**: ``array`` **default**: ``[]``
 
-Renders the fragment for the given controller (using the `controller`_ function)
-or URI. For more information, see :doc:`/templating/embedding_controllers`.
+Makes a request to the given internal URI or controller and returns the result.
+It's commonly used to :doc:`embed controllers in templates </templating/embedding_controllers>`.
 
-The render strategy can be specified in the ``strategy`` key of the options.
+.. code-block:: twig
 
-.. tip::
+    {# if the controller is associated with a route, use the path() or
+       url() functions to generate the URI used by render() #}
+    {{ render(path('latest_articles', {num: 5})) }}
+    {{ render(url('latest_articles', {num: 5})) }}
+
+    {# if you don't want to expose the controller with a public URL, use
+       the controller() function to define the controller to be executed #}
+    {{ render(controller('AppBundle:Default:latestArticles', {num: 5})) }}
 
-    The URI can be generated by other functions, like `path`_ and `url`_.
+The render strategy can be specified in the ``strategy`` key of the options.
 
 .. _reference-twig-function-render-esi:
 
@@ -76,13 +83,9 @@ render_esi
 ``options`` *(optional)*
     **type**: ``array`` **default**: ``[]``
 
-Generates an ESI tag when possible or falls back to the behavior of
-`render`_ function instead. For more information, see
-:doc:`/templating/embedding_controllers`.
-
-.. tip::
-
-    The URI can be generated by other functions, like `path`_ and `url`_.
+It's similar to the `render`_ function and defines the same arguments. However,
+it generates an ESI tag when :doc:`ESI support </http_cache/esi>` is enabled or
+falls back to the behavior of `render`_ otherwise.
 
 .. tip::
 

templating/embedding_controllers.rst

@@ -4,20 +4,27 @@
 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.
-
 .. note::
 
     Rendering embedded controllers is "heavier" than including a template or calling
     a custom Twig function. Unless you're planning on :doc:`caching the fragment </http_cache/esi>`,
     avoid embedding many controllers.
 
-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::
+:ref:`Including template fragments <including-other-templates>` 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.
+
+First, create a controller that renders a certain number of recent articles::
 
     // src/AppBundle/Controller/ArticleController.php
     namespace AppBundle\Controller;
@@ -39,15 +46,16 @@ 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::
 
     .. code-block:: html+twig
 
         {# app/Resources/views/article/recent_list.html.twig #}
         {% for article in articles %}
-            <a href="/article/{{ article.slug }}">
+            <a href="{{ path('article_show', {slug: article.slug}) }}">
                 {{ article.title }}
             </a>
         {% endfor %}
@@ -56,19 +64,15 @@ The ``recent_list`` template is perfectly straightforward:
 
         <!-- app/Resources/views/article/recent_list.html.php -->
         <?php foreach ($articles as $article): ?>
-            <a href="/article/<?php echo $article->getSlug() ?>">
+            <a href="<?php echo $view['router']->path('article_show', array(
+            'slug' => $article->getSlug(),
+            )) ?>">
                 <?php echo $article->getTitle() ?>
             </a>
         <?php endforeach ?>
 
-.. 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::
 
@@ -97,5 +101,3 @@ string syntax for controllers (i.e. **bundle**:**controller**:**action**):
                 )
             ) ?>
         </div>
-
-The result of an embedded controller can also be :doc:`cached </http_cache/esi>`