From 534ac4829764f317cf2fbc4a18354fcc998c1425 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Thu, 9 Feb 2023 16:48:46 +0100 Subject: Refs #34140 -- Applied rst code-block to non-Python examples. Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for reviews. --- docs/ref/templates/api.txt | 38 ++- docs/ref/templates/builtins.txt | 626 ++++++++++++++++++++++++++++++---------- docs/ref/templates/language.txt | 126 +++++--- 3 files changed, 589 insertions(+), 201 deletions(-) (limited to 'docs/ref/templates') diff --git a/docs/ref/templates/api.txt b/docs/ref/templates/api.txt index 8110d5bed9..e080388ff4 100644 --- a/docs/ref/templates/api.txt +++ b/docs/ref/templates/api.txt @@ -211,7 +211,9 @@ different contexts. .. method:: Template.render(context) Call the :class:`Template` object's ``render()`` method with a - :class:`Context` to "fill" the template:: + :class:`Context` to "fill" the template: + + .. code-block:: pycon >>> from django.template import Context, Template >>> template = Template("My name is {{ my_name }}.") @@ -243,7 +245,9 @@ interpreted as a literal string and not using the value of the variable "bar", if one exists in the template context. The template system uses the first lookup type that works. It's short-circuit -logic. Here are a few examples:: +logic. Here are a few examples: + +.. code-block:: pycon >>> from django.template import Context, Template >>> t = Template("My name is {{ person.first_name }}.") @@ -264,7 +268,9 @@ logic. Here are a few examples:: "The first stooge in the list is Larry." If any part of the variable is callable, the template system will try calling -it. Example:: +it. Example: + +.. code-block:: pycon >>> class PersonClass2: ... def name(self): @@ -282,7 +288,9 @@ straight lookups. Here are some things to keep in mind: *does* have a ``silent_variable_failure`` attribute whose value is ``True``, the variable will render as the value of the engine's ``string_if_invalid`` configuration option (an empty string, by default). - Example:: + Example: + + .. code-block:: pycon >>> t = Template("My name is {{ person.first_name }}.") >>> class PersonClass3: @@ -320,9 +328,11 @@ straight lookups. Here are some things to keep in mind: A good example is the :meth:`~django.db.models.Model.delete` method on each Django model object. The template system shouldn't be allowed to do - something like this:: + something like this: + + .. code-block:: html+django - I will now delete this valuable data. {{ data.delete }} + I will now delete this valuable data. {{ data.delete }} To prevent this, set an ``alters_data`` attribute on the callable variable. The template system won't call a variable if it has @@ -395,14 +405,18 @@ A similar issue exists if you want to include these sequences in template filter or tag arguments. For example, when parsing a block tag, Django's template parser looks for the first occurrence of ``%}`` after a ``{%``. This prevents the use of ``"%}"`` as a string literal. For example, a ``TemplateSyntaxError`` -will be raised for the following expressions:: +will be raised for the following expressions: + +.. code-block:: html+django {% include "template.html" tvar="Some string literal with %} in it." %} {% with tvar="Some string literal with %} in it." %}{% endwith %} The same issue can be triggered by using a reserved sequence in filter -arguments:: +arguments: + +.. code-block:: html+django {{ some.variable|default:"}}" }} @@ -417,7 +431,9 @@ Playing with ``Context`` objects Most of the time, you'll instantiate :class:`Context` objects by passing in a fully-populated dictionary to ``Context()``. But you can add and delete items from a ``Context`` object once it's been instantiated, too, using standard -dictionary syntax:: +dictionary syntax: + +.. code-block:: pycon >>> from django.template import Context >>> c = Context({"foo": "bar"}) @@ -448,7 +464,9 @@ dictionary syntax:: A ``Context`` object is a stack. That is, you can ``push()`` and ``pop()`` it. If you ``pop()`` too much, it'll raise -``django.template.ContextPopException``:: +``django.template.ContextPopException``: + +.. code-block:: pycon >>> c = Context() >>> c['foo'] = 'first level' diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index f866e865b5..d69bd3266a 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -12,8 +12,6 @@ documentation for any custom tags or filters installed. Built-in tag reference ====================== -.. highlight:: html+django - .. templatetag:: autoescape ``autoescape`` @@ -32,7 +30,9 @@ The only exceptions are variables that are already marked as "safe" from escaping, either by the code that populated the variable, or because it has had the :tfilter:`safe` or :tfilter:`escape` filters applied. -Sample usage:: +Sample usage: + +.. code-block:: html+django {% autoescape on %} {{ body }} @@ -55,7 +55,9 @@ Ignores everything between ``{% comment %}`` and ``{% endcomment %}``. An optional note may be inserted in the first tag. For example, this is useful when commenting out code for documenting why the code was disabled. -Sample usage:: +Sample usage: + +.. code-block:: html+django

Rendered text with {{ pub_date|date:"c" }}

{% comment "Optional note" %} @@ -82,7 +84,9 @@ argument is produced on the first encounter, the second argument on the second encounter, and so forth. Once all arguments are exhausted, the tag cycles to the first argument and produces it again. -This tag is particularly useful in a loop:: +This tag is particularly useful in a loop: + +.. code-block:: html+django {% for o in some_list %} @@ -96,7 +100,9 @@ loop. You can use variables, too. For example, if you have two template variables, ``rowvalue1`` and ``rowvalue2``, you can alternate between their values like -this:: +this: + +.. code-block:: html+django {% for o in some_list %} @@ -105,7 +111,9 @@ this:: {% endfor %} Variables included in the cycle will be escaped. You can disable auto-escaping -with:: +with: + +.. code-block:: html+django {% for o in some_list %} @@ -113,7 +121,9 @@ with:: {% endfor %} -You can mix variables and strings:: +You can mix variables and strings: + +.. code-block:: html+django {% for o in some_list %} @@ -123,7 +133,9 @@ You can mix variables and strings:: In some cases you might want to refer to the current value of a cycle without advancing to the next value. To do this, -give the ``{% cycle %}`` tag a name, using "as", like this:: +give the ``{% cycle %}`` tag a name, using "as", like this: + +.. code-block:: html+django {% cycle 'row1' 'row2' as rowcolors %} @@ -131,7 +143,9 @@ From then on, you can insert the current value of the cycle wherever you'd like in your template by referencing the cycle name as a context variable. If you want to move the cycle to the next value independently of the original ``cycle`` tag, you can use another ``cycle`` tag and specify the name of the -variable. So, the following template:: +variable. So, the following template: + +.. code-block:: html+django ... @@ -142,7 +156,9 @@ variable. So, the following template:: ... -would output:: +would output: + +.. code-block:: html+django ... @@ -163,7 +179,9 @@ usage of ``{% cycle %}`` that initiates the cycle will itself produce the first value in the cycle. This could be a problem if you want to use the value in a nested loop or an included template. If you only want to declare the cycle but not produce the first value, you can add a -``silent`` keyword as the last keyword in the tag. For example:: +``silent`` keyword as the last keyword in the tag. For example: + +.. code-block:: html+django {% for obj in some_list %} {% cycle 'row1' 'row2' as rowcolors silent %} @@ -180,7 +198,9 @@ omitted, ``row1`` and ``row2`` would be emitted as normal text, outside the When the silent keyword is used on a cycle definition, the silence automatically applies to all subsequent uses of that specific cycle tag. The following template would output *nothing*, even though the second -call to ``{% cycle %}`` doesn't specify ``silent``:: +call to ``{% cycle %}`` doesn't specify ``silent``: + +.. code-block:: html+django {% cycle 'row1' 'row2' as rowcolors silent %} {% cycle rowcolors %} @@ -223,7 +243,9 @@ See :ref:`template-inheritance` for more information. Normally the template name is relative to the template loader's root directory. A string argument may also be a relative path starting with ``./`` or ``../``. -For example, assume the following directory structure:: +For example, assume the following directory structure: + +.. code-block:: text dir1/ template.html @@ -232,7 +254,9 @@ For example, assume the following directory structure:: base3.html base1.html -In ``template.html``, the following paths would be valid:: +In ``template.html``, the following paths would be valid: + +.. code-block:: html+django {% extends "./base2.html" %} {% extends "../base1.html" %} @@ -250,7 +274,9 @@ in variable syntax. Note that the block includes *all* the text between the ``filter`` and ``endfilter`` tags. -Sample usage:: +Sample usage: + +.. code-block:: html+django {% filter force_escape|lower %} This text will be HTML-escaped, and will appear in all lowercase. @@ -271,11 +297,15 @@ Outputs the first argument variable that is not "false" (i.e. exists, is not empty, is not a false boolean value, and is not a zero numeric value). Outputs nothing if all the passed variables are "false". -Sample usage:: +Sample usage: + +.. code-block:: html+django {% firstof var1 var2 var3 %} -This is equivalent to:: +This is equivalent to: + +.. code-block:: html+django {% if var1 %} {{ var1 }} @@ -286,17 +316,23 @@ This is equivalent to:: {% endif %} You can also use a literal string as a fallback value in case all -passed variables are False:: +passed variables are False: + +.. code-block:: html+django {% firstof var1 var2 var3 "fallback value" %} -This tag auto-escapes variable values. You can disable auto-escaping with:: +This tag auto-escapes variable values. You can disable auto-escaping with: + +.. code-block:: html+django {% autoescape off %} {% firstof var1 var2 var3 "fallback value" %} {% endautoescape %} -Or if only some variables should be escaped, you can use:: +Or if only some variables should be escaped, you can use: + +.. code-block:: html+django {% firstof var1 var2|safe var3 "fallback value"|safe %} @@ -310,7 +346,9 @@ output inside a variable. Loops over each item in an array, making the item available in a context variable. For example, to display a list of athletes provided in -``athlete_list``:: +``athlete_list``: + +.. code-block:: html+django