Merge branch '3.4' into 4.4

javiereguiluz · javiereguiluz · commit 6c6e0c4601ec · 2020-03-12T16:46:52.000+01:00
* 3.4:
  [Twig] tweaked first block examples
diff --git a/templates.rst b/templates.rst
@@ -476,9 +476,9 @@ provided by Symfony:
                 # special options defined by Symfony to set the page cache
                 maxAge:    86400
                 sharedAge: 86400
-                
+
                 # whether or not caching should apply for client caches only
-                private: true 
+                private: true
 
     .. code-block:: xml
 
@@ -518,7 +518,7 @@ provided by Symfony:
                     // special options defined by Symfony to set the page cache
                     'maxAge'    => 86400,
                     'sharedAge' => 86400,
-                    
+
                     // whether or not caching should apply for client caches only
                     'private' => true,
                 ])
@@ -844,25 +844,30 @@ In practice, the ``base.html.twig`` template would look like this:
         <head>
             <meta charset="UTF-8">
             <title>{% block title %}My Application{% endblock %}</title>
+            {% block stylesheets %}
+                <link rel="stylesheet" type="text/css" href="/css/base.css"/>
+            {% endblock
         </head>
         <body>
-            <div id="sidebar">
-                {% block sidebar %}
-                    <ul>
-                        <li><a href="{{ path('homepage') }}">Home</a></li>
-                        <li><a href="{{ path('blog_index') }}">Blog</a></li>
-                    </ul>
-                {% endblock %}
-            </div>
-
-            <div id="content">
-                {% block body %}{% endblock %}
-            </div>
+            {% block body %}
+                <div id="sidebar">
+                    {% block sidebar %}
+                        <ul>
+                            <li><a href="{{ path('homepage') }}">Home</a></li>
+                            <li><a href="{{ path('blog_index') }}">Blog</a></li>
+                        </ul>
+                    {% endblock %}
+                </div>
+
+                <div id="content">
+                    {% block content %}{% endblock %}
+                </div>
+            {% endblock %}
         </body>
     </html>
 
 The `Twig block tag`_ defines the page sections that can be overridden in the
-child templates. They can be empty, like the ``body`` block or define a default
+child templates. They can be empty, like the ``content`` block or define a default
 content, like the ``title`` block, which is displayed when child templates don't
 override them.
 
@@ -873,14 +878,14 @@ The ``blog/layout.html.twig`` template could be like this:
     {# templates/blog/layout.html.twig #}
     {% extends 'base.html.twig' %}
 
-    {% block body %}
+    {% block content %}
         <h1>Blog</h1>
 
-        {% block content %}{% endblock %}
+        {% block page_contents %}{% endblock %}
     {% endblock %}
 
 The template extends from ``base.html.twig`` and only defines the contents of
-the ``body`` block. The rest of the parent template blocks will display their
+the ``content`` block. The rest of the parent template blocks will display their
 default contents. However, they can be overridden by the third-level inheritance
 template, such as ``blog/index.html.twig``, which displays the blog index:
 
@@ -891,22 +896,38 @@ template, such as ``blog/index.html.twig``, which displays the blog index:
 
     {% block title %}Blog Index{% endblock %}
 
-    {% block content %}
+    {% block page_contents %}
         {% for article in articles %}
             <h2>{{ article.title }}</h2>
             <p>{{ article.body }}</p>
         {% endfor %}
     {% endblock %}
 
 This template extends from the second-level template (``blog/layout.html.twig``)
-but overrides blocks of different parent templates: ``content`` from
+but overrides blocks of different parent templates: ``page_contents`` from
 ``blog/layout.html.twig`` and ``title`` from ``base.html.twig``.
 
 When you render the ``blog/index.html.twig`` template, Symfony uses three
 different templates to create the final contents. This inheritance mechanism
 boosts your productivity because each template includes only its unique contents
 and leaves the repeated contents and HTML structure to some parent templates.
 
+.. caution::
+
+    When using ``extends``, a child template is forbidden to define template
+    parts outside of a block. The following code throws a ``SyntaxError``:
+
+    .. code-block:: html+twig
+
+        {# app/Resources/views/blog/index.html.twig #}
+        {% extends 'base.html.twig' %}
+
+        {# the line below is not captured by a "block" tag #}
+        <div class="alert">Some Alert</div>
+
+        {# the following is valid #}
+        {% block content %}My cool blog posts{% endblock %}
+
 Read the `Twig template inheritance`_ docs to learn more about how to reuse
 parent block contents when overriding templates and other advanced features.
 
