From: David Lord <davidism@gmail.com>
Date: Tue, 9 Nov 2021 18:32:06 +0000 (-0800)
Subject: rewrite docs about extending template objects
X-Git-Tag: 3.0.3~3^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a6162daeca116e81ca8a390ed36b3c67aea33671;p=thirdparty%2Fjinja.git

rewrite docs about extending template objects
---

diff --git a/docs/templates.rst b/docs/templates.rst
index a90f8bd0..237a46b5 100644
--- a/docs/templates.rst
+++ b/docs/templates.rst
@@ -587,17 +587,26 @@ When combined with ``scoped``, the ``required`` modifier must be placed
 Template Objects
 ~~~~~~~~~~~~~~~~
 
-.. versionchanged:: 2.4
+``extends``, ``include``, and ``import`` can take a template object
+instead of the name of a template to load. This could be useful in some
+advanced situations, since you can use Python code to load a template
+first and pass it in to ``render``.
+
+.. code-block:: python
+
+    if debug_mode:
+        layout = env.get_template("debug_layout.html")
+    else:
+        layout = env.get_template("layout.html")
 
-If a template object was passed in the template context, you can
-extend from that object as well.  Assuming the calling code passes
-a layout template as `layout_template` to the environment, this
-code works::
+    user_detail = env.get_template("user/detail.html", layout=layout)
+
+.. code-block:: jinja
 
-    {% extends layout_template %}
+    {% extends layout %}
 
-Previously, the `layout_template` variable had to be a string with
-the layout template's filename for this to work.
+Note how ``extends`` is passed the variable with the template object
+that was passed to ``render``, instead of a string.
 
 
 HTML Escaping