10000 Merge pull request #2121 from fabpot/content-renderer · symfony/symfony-docs@823cef3 · GitHub
[go: up one dir, main page]
Skip to content

Commit 823cef3

Browse files
weaverryanweaverryan
committed
Merge pull request #2121 from fabpot/content-renderer
Updated the docs for the new way to render partials/ESI/HInclude
2 parents 5065822 + 1550871 commit 823cef3

File tree

7 files changed

+128
-190
lines changed

7 files changed

+128
-190
lines changed

‎book/_security-2012-6431.rst.inc

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎book/http_cache.rst

Lines changed: 64 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -881,58 +881,37 @@ matter), Symfony2 uses the standard ``render`` helper to configure ESI tags:
881881

882882
.. code-block:: jinja
883883
884-
{% render url('latest_news', { 'max': 5 }), {'standalone': true} %}
884+
{# you can use a controller reference #}
885+
{{ render_esi(controller('...:news', { 'max': 5 })) }}
886+
887+
{# ... or a URL #}
888+
{{ render_esi(url('latest_news', { 'max': 5 })) }}
885889
886890
.. code-block:: php
887891
892+
<?php echo $view['actions']->render(
893+
new ControllerReference('...:news', array('max' => 5)),
894+
array('strategy' => 'esi'))
895+
?>
896+
888897
<?php echo $view['actions']->render(
889898
$view['router']->generate('latest_news', array('max' => 5), true),
890-
array('standalone' => true)
899+
array('strategy' => 'esi')
891900
) ?>
892901
893-
.. include:: /book/_security-2012-6431.rst.inc
894-
895-
The ``render`` tag takes the absolute url to the embedded action. This means
896-
that you need to define a new route to the controller that you're embedding:
897-
898-
.. code-block:: yaml
899-
900-
# app/config/routing.yml
901-
latest_news:
902-
pattern: /esi/latest-news/{max}
903-
defaults: { _controller: AcmeNewsBundle:News:news }
904-
requirements: { max: \d+ }
905-
906-
.. caution::
907-
908-
Unless you want this URL to be accessible to the outside world, you
909-
should use Symfony's firewall to secure it (by allowing access to your
910-
reverse proxy's IP range). See the :ref:`Securing by IP<book-security-securing-ip>`
911-
section of the :doc:`Security Chapter </book/security>` for more information
912-
on how to do this.
913-
914-
.. tip::
902+
By using the ``esi`` rendering strategy (via the ``render_esi`` Twig
903+
function), you tell Symfony2 that the action should be rendered as an ESI tag.
904+
You might be wondering why you would want to use a helper instead of just
905+
writing the ESI tag yourself. That's because using a helper makes your
906+
application work even if there is no gateway cache installed.
915907

916-
The best practice is to mount all your ESI urls on a single prefix (e.g.
917-
``/esi``) of your choice. This has two main advantages. First, it eases
918-
the management of ESI urls as you can easily identify the routes used for ESI.
919-
Second, it eases security management since securing all urls starting
920-
with the same prefix is easier than securing each individual url. See
921-
the above note for more details on securing ESI URLs.
922-
923-
By setting ``standalone`` to ``true`` in the ``render`` Twig tag, you tell
924-
Symfony2 that the ac 9E88 tion should be rendered as an ESI tag. You might be
925-
wondering why you would want to use a helper instead of just writing the ESI tag
926-
yourself. That's because using a helper makes your application work even if
927-
there is no gateway cache installed.
928-
929-
When standalone is ``false`` (the default), Symfony2 merges the included page
930-
content within the main one before sending the response to the client. But
931-
when standalone is ``true``, *and* if Symfony2 detects that it's talking
932-
to a gateway cache that supports ESI, it generates an ESI include tag. But
933-
if there is no gateway cache or if it does not support ESI, Symfony2 will
934-
just merge the included page content within the main one as it would have
935-
done were standalone set to ``false``.
908+
When using the default ``render`` function (or setting the strategy to
909+
``default``), Symfony2 merges the included page content within the main one
910+
before sending the response to the client. But when using ``esi`` strategy,
911+
*and* if Symfony2 detects that it's talking to a gateway cache that supports
912+
ESI, it generates an ESI include tag. But if there is no gateway cache or if
913+
it does not support ESI, Symfony2 will just merge the included page content
914+
within the main one as it would have done if you had used ``render``.
936915

937916
.. note::
938917

@@ -947,14 +926,52 @@ of the master page.
947926
948927
public function newsAction($max)
949928
{
950-
// ...
929+
// ...
951930
952-
$response->setSharedMaxAge(60);
931+
$response->setSharedMaxAge(60);
953932
}
954933
955934
With ESI, the full page cache will be valid for 600 seconds, but the news
956935
component cache will only last for 60 seconds.
957936

937+
When using a controller reference, the ESI tag should reference the embedded
938+
action as an accessible URL so the gateway cache can fetch it independently of
939+
the rest of the page. Of course, an action can't be accessed via a URL unless
940+
it has a route that points to it. Symfony2 takes care of this via a generic
941+
route and controller. For the ESI include tag to work properly, you must
942+
define the ``_proxy`` route:
943+
944+
.. configuration-block::
945+
946+
.. code-block:: yaml
947+
948+
# app/config/routing.yml
949+
_proxy:
950+
resource: "@FrameworkBundle/Resources/config/routing/proxy.xml"
951+
prefix: /proxy
952+
953+
.. code-block:: xml
954+
955+
<!-- app/config/routing.xml -->
956+
<?xml version="1.0" encoding="UTF-8" ?>
957+
958+
<routes xmlns="http://symfony.com/schema/routing"
959+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
960+
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
961+
962+
<import resource="@FrameworkBundle/Resources/config/routing/proxy.xml" prefix="/proxy" />
963+
</routes>
964+
965+
.. code-block:: php
966+
967+
// app/config/routing.php
968+
use Symfony\Component\Routing\RouteCollection;
969+
use Symfony\Component\Routing\Route;
970+
971+
$collection->addCollection($loader->import('@FrameworkBundle/Resources/config/routing/proxy.xml', '/proxy'));
972+
973+
return $collection;
974+
958975
One great advantage of this caching strategy is that you can make your
959976
application as dynamic as needed and at the same time, hit the application as
960977
little as possible.
@@ -967,7 +984,7 @@ little as possible.
967984
obey the ``max-age`` directive and cache the entire page. And you don't
968985
want that.
969986

970-
The ``render`` helper supports two other useful options:
987+
The ``render_esi`` helper supports two other useful options:
971988

972989
* ``alt``: used as the ``alt`` attribute on the ESI tag, which allows you
973990
to specify an alternative URL to be used if the ``src`` cannot be found;

‎book/templating.rst

Lines changed: 21 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -532,9 +532,7 @@ Including this template from any other template is simple:
532532
<h1>Recent Articles<h1>
533533

534534
{% for article in articles %}
535-
{% include 'AcmeArticleBundle:Article:articleDetails.html.twig'
536-
with {'article': article}
537-
%}
535+
{{ include('AcmeArticleBundle:Article:articleDetails.html.twig', {'article': article}) }}
538536
{% endfor %}
539537
{% endblock %}
540538

@@ -551,7 +549,7 @@ Including this template from any other template is simple:
551549
<?php endforeach; ?>
552550
<?php $view['slots']->stop() ?>
553551

554-
The template is included using the ``{% include %}`` tag. Notice that the
552+
The template is included using the ``{{ include() }}`` function. Notice that the
555553
template name follows the same typical convention. The ``articleDetails.html.twig``
556554
template uses an ``article`` variable. This is passed in by the ``list.html.twig``
557555
template using the ``with`` command.
@@ -623,43 +621,8 @@ The ``recentList`` template is perfectly straightforward:
623621
(e.g. ``/article/*slug*``). This is a bad practice. In the next section,
624622
you'll learn how to do this correctly.
625623

626-
Even though this controller will only be used internally, you'll need to
627-
create a route that points to the controller:
628-
629-
.. configuration-block::
630-
631-
.. code-block:: yaml
632-
633-
latest_articles:
634-
pattern: /articles/latest/{max}
635-
defaults: { _controller: AcmeArticleBundle:Article:recentArticles }
636-
637-
.. code-block:: xml
638-
639-
<?xml version="1.0" encoding="UTF-8" ?>
640-
641-
<routes xmlns="http://symfony.com/schema/routing"
642-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
643-
xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
644-
645-
<route id="latest_articles" pattern="/articles/latest/{max}">
646-
<default key="_controller">AcmeArticleBundle:Article:recentArticles</default>
647-
</route>
648-
</routes>
649-
650-
.. code-block:: php
651-
652-
use Symfony\Component\Routing\RouteCollection;
653-
use Symfony\Component\Routing\Route;
654-
655-
$collection = new RouteCollection();
656-
$collection->add('latest_articles', new Route('/articles/latest/{max}', array(
657-
'_controller' => 'AcmeArticleBundle:Article:recentArticles',
658-
)));
659-
660-
return $collection;
661-
662-
To include the controller, you'll need to refer to it using an absolute url:
624+
To include the controller, you'll need to refer to it using the standard
625+
string syntax for controllers (i.e. **bundle**:**controller**:**action**):
663626

664627
.. configuration-block::
665628

@@ -669,7 +632,7 @@ To include the controller, you'll need to refer to it using an absolute url:
669632

670633
{# ... #}
671634
<div id="sidebar">
672-
{% render url('latest_articles', { 'max': 3 }) %}
635+
{{ render(controller('AcmeArticleBundle:Article:recentArticles', { 'max': 3 })) }}
673636
</div>
674637

675638
.. code-block:: html+php
@@ -679,12 +642,10 @@ To include the controller, you'll need to refer to it using an absolute url:
679642
<!-- ... -->
680643
<div id="sidebar">
681644
<?php echo $view['actions']->render(
682-
$view['router']->generate('latest_articles', array('max' => 3), true)
645+
new ControllerReference('AcmeArticleBundle:Article:recentArticles', array('max' => 3))
< 10000 div aria-hidden="true" style="left:-2px" class="position-absolute top-0 d-flex user-select-none DiffLineTableCellParts-module__in-progress-comment-indicator--hx3m3">
683646
) ?>
684647
</div>
685648

686-
.. include:: /book/_security-2012-6431.rst.inc
687-
688649
Whenever you find that you need a variable or a piece of information that
689650
you don't have access to in a template, consider rendering a controller.
690651
Controllers are fast to execute and promote good code organization and reuse.
@@ -703,13 +664,20 @@ Symfony2 uses the standard ``render`` helper to configure ``hinclude`` tags:
703664

704665
.. code-block:: jinja
705666
706-
{% render url('...'), {'standalone': 'js'} %}
667+
{{ render_hinclude(controller('...')) }}
668+
669+
{{ render_hinclude(url('...')) }}
707670
708671
.. code-block:: php
709672
673+
<?php echo $view['actions']->render(
674+
new ControllerReference('...'),
675+
array('strategy' => 'hinclude')
676+
) ?>
677+
710678
<?php echo $view['actions']->render(
711679
$view['router']->generate('...'),
712-
array('standalone' => 'js')
680+
array('strategy' => 'hinclude')
713681
) ?>
714682
715683
.. note::
@@ -756,18 +724,14 @@ any global default templates that is defined):
756724

757725
.. code-block:: jinja
758726
759-
{% render '...:news' with
760-
{},
761-
{'standalone': 'js', 'default': 'AcmeDemoBundle:Default:content.html.twig'}
762-
%}
727+
{{ render_hinclude(controller('...'), {'default': 'AcmeDemoBundle:Default:content.html.twig'}) }}
763728
764729
.. code-block:: php
765730
766731
<?php echo $view['actions']->render(
767-
'...:news',
768-
array(),
732+
new ControllerReference('...'),
769733
array(
770-
'standalone' => 'js',
734+
'strategy' => 'hinclude',
771735
'default' => 'AcmeDemoBundle:Default:content.html.twig',
772736
)
773737
) ?>
@@ -778,18 +742,14 @@ Or you can also specify a string to display as the default content:
778742

779743
.. code-block:: jinja
780744
781-
{% render '...:news' with
782-
{},
783-
{'standalone': 'js', 'default': 'Loading...'}
784-
%}
745+
{{ render_hinclude(controller('...'), {'default': 'Loading...'}) }}
785746
786747
.. code-block:: php
787748
788749
<?php echo $view['actions']->render(
789-
'...:news',
790-
array(),
750+
new ControllerReference('...'),
791751
array(
792-
'standalone' => 'js',
752+
'strategy' => 'hinclude',
793753
'default' => 'Loading...',
794754
)
795755
) ?>

0 commit comments

Comments
 (0)
0