[#2121] Tweaking a few things related to new render changes

Author: weaverryan

book/http_cache.rst

@@ -906,12 +906,13 @@ writing the ESI tag yourself. That's because using a helper makes your
 application work even if there is no gateway cache installed.
 
 When using the default ``render`` function (or setting the strategy to
-``default``), Symfony2 merges the included page content within the main one
-before sending the response to the client. But when using ``esi`` strategy,
-*and* if Symfony2 detects that it's talking to a gateway cache that supports
-ESI, it generates an ESI include tag. But if there is no gateway cache or if
-it does not support ESI, Symfony2 will just merge the included page content
-within the main one as it would have done if you had used ``render``.
+``default``), Symfony2 merges the included page content into the main one
+before sending the response to the client. But if you use the ``esi`` strategy
+(i.e. call ``render_esi``), *and* if Symfony2 detects that it's talking to
+a gateway cache that supports ESI, it generates an ESI include tag. But if
+there is no gateway cache or if it does not support ESI, Symfony2 will just
+merge the included page content within the main one as it would have done
+if you had used ``render``.
 
 .. note::
 
@@ -938,8 +939,8 @@ When using a controller reference, the ESI tag should reference the embedded
 action as an accessible URL so the gateway cache can fetch it independently of
 the rest of the page. Of course, an action can't be accessed via a URL unless
 it has a route that points to it. Symfony2 takes care of this via a generic
-route and controller. For the ESI include tag to work properly, you must
-define the ``_proxy`` route:
+route. For the ESI include tag to work properly, you must define the ``_proxy``
+route:
 
 .. configuration-block::
 
@@ -976,6 +977,12 @@ One great advantage of this caching strategy is that you can make your
 application as dynamic as needed and at the same time, hit the application as
 little as possible.
 
+.. tip::
+
+    The proxy route doesn't point to a real controller. Instead, it's handled
+    by an internal :class:`Symfony\\Component\\HttpKernel\\EventListener\\RouterProxyListener`
+    class. This listener only responds to local IP addresses or trusted proxies.
+
 .. note::
 
     Once you start using ESI, remember to always use the ``s-maxage``

book/templating.rst

@@ -560,6 +560,10 @@ template using the ``with`` command.
     maps (i.e. an array with named keys). If you needed to pass in multiple
     elements, it would look like this: ``{'foo': foo, 'bar': bar}``.
 
+.. versionadded:: 2.2
+    The ``include()`` function is a new Twig feature that's available in
+    Symfony 2.2. Prior, the ``{% include %}`` tag was used.
+
 .. index::
    single: Templating; Embedding action
 
@@ -715,10 +719,10 @@ in your application configuration:
         ));
 
 .. versionadded:: 2.2
-    Default templates per render tag was added in Symfony 2.2
+    Default templates per render function was added in Symfony 2.2
 
-You can define default templates per ``render`` tag (which will override
-any global default templates that is defined):
+You can define default templates per ``render`` function (which will override
+any global default template that is defined):
 
 .. configuration-block::
 

quick_tour/the_view.rst

@@ -182,7 +182,7 @@ some variable not available in the main template.
 
 Suppose you've created a ``fancyAction`` controller method, and you want to
 "render" it inside the ``index`` template, which means including the result
-(e.g. ``HTML``) of the controller, use the ``render`` function:
+(e.g. ``HTML``) of the controller. To do this, use the ``render`` function:
 
 .. code-block:: jinja
 

reference/twig_reference.rst

@@ -20,21 +20,28 @@ Functions
 .. versionadded:: 2.1
     The ``csrf_token``, ``logout_path`` and ``logout_url`` functions were added in Symfony2.1
 
+.. versionadded:: 2.3
+    The ``render`` and ``controller`` functions are new in Symfony 2.2. Prior,
+    the ``{% render %}`` tag was used and had a different signature.
+
 +----------------------------------------------------+--------------------------------------------------------------------------------------------+
 | Function Syntax                                    | Usage                                                                                      |
 +====================================================+============================================================================================+
-| ``render(controller('B:C:a', {params}))``          | This will render the Response Content for the given controller or                          |
-| ``render(path('route', {params}))``                | URL. For more information, see :ref:`templating-embedding-controller`.                     |
+| ``render(uri, options = {})``                      | This will render the Response Content for the given controller or                          |
+| ``render(controller('B:C:a', {params}))``          | URL. For more information, see :ref:`templating-embedding-controller`.                     |
+| ``render(path('route', {params}))``                |                                                                                            |
 | ``render(url('route', {params}))``                 |                                                                                            |
 +----------------------------------------------------+--------------------------------------------------------------------------------------------+
 | ``render_esi(controller('B:C:a', {params}))``      | This will generates an ESI tag when possible or fallback to the ``render``                 |
 | ``render_esi(url('route', {params}))``             | behavior otherwise. For more information, see :ref:`templating-embedding-controller`.      |
 | ``render_esi(path('route', {params}))``            |                                                                                            |
 +----------------------------------------------------+--------------------------------------------------------------------------------------------+
-| ``render_hinclude(controller('B:C:a', {params}))`` | This will generates an Hinclude tag for the given controller or URL.                       |
+| ``render_hinclude(controller(...))``               | This will generates an Hinclude tag for the given controller or URL.                       |
 | ``render_hinclude(url('route', {params}))``        | For more information, see :ref:`templating-embedding-controller`.                          |
 | ``render_hinclude(path('route', {params}))``       |                                                                                            |
 +----------------------------------------------------+--------------------------------------------------------------------------------------------+
+| ``controller(attributes = {}, query = {})``        | Used along with the ``render`` tag to refer to the controller that you want to render      |
++----------------------------------------------------+--------------------------------------------------------------------------------------------+
 | ``asset(path, packageName = null)``                | Get the public path of the asset, more information in                                      |
 |                                                    | ":ref:`book-templating-assets`".                                                           |
 +----------------------------------------------------+--------------------------------------------------------------------------------------------+