tornado.template — Flexible output generation¶

A simple template system that compiles templates to Python code.

Basic usage looks like:

  1. t = template.Template("<html>{{ myvalue }}</html>")
  2. print t.generate(myvalue="XXX")

Loader is a class that loads templates from a root directory and cachesthe compiled templates:

  1. loader = template.Loader("/home/btaylor")
  2. print loader.load("test.html").generate(myvalue="XXX")

We compile all templates to raw Python. Error-reporting is currently… uh,interesting. Syntax for the templates:

  1. ### base.html
  2. <html>
  3.   <head>
  4.     <title>{% block title %}Default title{% end %}</title>
  5.   </head>
  6.   <body>
  7.     <ul>
  8.       {% for student in students %}
  9.         {% block student %}
  10.           <li>{{ escape(student.name) }}</li>
  11.         {% end %}
  12.       {% end %}
  13.     </ul>
  14.   </body>
  15. </html>
  16.  
  17. ### bold.html
  18. {% extends "base.html" %}
  19.  
  20. {% block title %}A bolder title{% end %}
  21.  
  22. {% block student %}
  23.   <li><span style="bold">{{ escape(student.name) }}</span></li>
  24. {% end %}

Unlike most other template systems, we do not put any restrictions on theexpressions you can include in your statements. if and for blocks gettranslated exactly into Python, so you can do complex expressions like:

  1. {% for student in [p for p in people if p.student and p.age > 23] %}
  2.   <li>{{ escape(student.name) }}</li>
  3. {% end %}

Translating directly to Python means you can apply functions to expressionseasily, like the escape() function in the examples above. You can passfunctions in to your template just like any other variable(In a RequestHandler, override RequestHandler.get_template_namespace):

  1. ### Python code
  2. def add(x, y):
  3.    return x + y
  4. template.execute(add=add)
  5.  
  6. ### The template
  7. {{ add(1, 2) }}

We provide the functions escape(), url_escape(),json_encode(), and squeeze() to all templates by default.

Typical applications do not create Template or Loader instances byhand, but instead use the render andrender_string methods oftornado.web.RequestHandler, which load templates automatically basedon the template_path Application setting.

Variable names beginning with tt are reserved by the templatesystem and should not be used by application code.

Syntax Reference¶

Template expressions are surrounded by double curly braces: {{ … }}.The contents may be any python expression, which will be escaped accordingto the current autoescape setting and inserted into the output. Othertemplate directives use {% %}.

To comment out a section so that it is omitted from the output, surround itwith {# … #}.

These tags may be escaped as {{!, {%!, and {#!if you need to include a literal {{, {%, or {# in the output.

{% apply function %}…{% end %}

Applies a function to the output of all template code between applyand end:



  1. {% apply linkify %}{{name}} said: {{message}}{% end %}




Note that as an implementation detail apply blocks are implementedas nested functions and thus may interact strangely with variablesset via {% set %}, or the use of {% break %} or {% continue %}within loops.
{% autoescape function %}

Sets the autoescape mode for the current file. This does not affectother files, even those referenced by {% include %}. Note thatautoescaping can also be configured globally, at the Applicationor Loader.:



  1. {% autoescape xhtml_escape %}
    {% autoescape None %}



{% block name %}…{% end %}

Indicates a named, replaceable block for use with {% extends %}.Blocks in the parent template will be replaced with the contents ofthe same-named block in a child template.:



  1. <!— base.html —>
    <title>{% block title %}Default title{% end %}</title>

    <!— mypage.html —>
    {% extends "base.html" %}
    {% block title %}My page title{% end %}



{% comment … %}
A comment which will be removed from the template output. Note thatthere is no {% end %} tag; the comment goes from the word commentto the closing %} tag.
{% extends filename %}
Inherit from another template. Templates that use extends shouldcontain one or more block tags to replace content from the parenttemplate. Anything in the child template not contained in a blocktag will be ignored. For an example, see the {% block %} tag.
{% for var in expr %}…{% end %}
Same as the python for statement. {% break %} and{% continue %} may be used inside the loop.
{% from x import y %}
Same as the python import statement.
{% if condition %}…{% elif condition %}…{% else %}…{% end %}
Conditional statement - outputs the first section whose condition istrue. (The elif and else sections are optional)
{% import module %}
Same as the python import statement.
{% include filename %}
Includes another template file. The included file can see all the localvariables as if it were copied directly to the point of the includedirective (the {% autoescape %} directive is an exception).Alternately, {% module Template(filename, *kwargs) %} may be usedto include another template with an isolated namespace.
{% module expr %}

Renders a UIModule. The output of the UIModule isnot escaped:



  1. {% module Template("foo.html", arg=42) %}




UIModules are a feature of the tornado.web.RequestHandlerclass (and specifically its render method) and will not workwhen the template system is used on its own in other contexts.
{% raw expr %}
Outputs the result of the given expression without autoescaping.
{% set x = y %}
Sets a local variable.
{% try %}…{% except %}…{% else %}…{% finally %}…{% end %}
Same as the python try statement.
{% while condition %}… {% end %}
Same as the python while statement. {% break %} and{% continue %} may be used inside the loop.
{% whitespace mode* %}
Sets the whitespace mode for the remainder of the current file(or until the next {% whitespace %} directive). Seefilter_whitespace for available options. New in Tornado 4.3.

Class reference¶

class tornado.template.Template(template_string, name="<string>", loader=None, compress_whitespace=None, autoescape="xhtml_escape", whitespace=None)[源代码]

A compiled template.

We compile into Python from the given templatestring. You can generatethe template from variables with generate().

Construct a Template.

|参数:
|——-
|
- template_string ([_str](https://docs.python.org/3.4/library/stdtypes.html#str)) – the contents of the template file.
- name (str) – the filename from which the template was loaded(used for error message).
- loader (tornado.template.BaseLoader) – the BaseLoader responsible for this template,used to resolve {% include %} and {% extend %}directives.
- compress_whitespace (bool) – Deprecated since Tornado 4.3.Equivalent to whitespace="single" if true andwhitespace="all" if false.
- autoescape (str) – The name of a function in the templatenamespace, or None to disable escaping by default.
- whitespace (str) – A string specifying treatment of whitespace;see filter_whitespace for options.



在 4.3 版更改: Added whitespace parameter; deprecated compresswhitespace.

generate(kwargs)[源代码]

Generate this template with the given arguments.
_class tornado.template.BaseLoader(autoescape='xhtml_escape', namespace=None, whitespace=None)[源代码]

Base class for template loaders.

You must use a template loader to use template constructs like{% extends %} and {% include %}. The loader caches alltemplates after they are loaded the first time.

Construct a template loader.

|参数:
|——-
|
- autoescape (str) – The name of a function in the templatenamespace, such as “xhtml_escape”, or None to disableautoescaping by default.
- namespace (dict) – A dictionary to be added to the default templatenamespace, or None.
- whitespace (str) – A string specifying default behavior forwhitespace in templates; see filter_whitespace for options.Default is “single” for files ending in ”.html” and ”.js” and“all” for other files.



在 4.3 版更改: Added whitespace parameter.

load(name, parent_path=None)[源代码]

Loads a template.
reset()[源代码]

Resets the cache of compiled templates.
resolvepath(_name, parent_path=None)[源代码]

Converts a possibly-relative path to absolute (used internally).
class tornado.template.Loader(root_directory, _kwargs)[源代码]

A template loader that loads from a single root directory.
_class tornado.template.DictLoader(dict, **kwargs)[源代码]

A template loader that loads from a dictionary.
exception tornado.template.ParseError(message, filename=None, lineno=0)[源代码]

Raised for template syntax errors.

ParseError instances have filename and lineno attributesindicating the position of the error.


在 4.3 版更改: Added filename and lineno attributes.

tornado.template.filterwhitespace(_mode, text)[源代码]

Transform whitespace in text according to mode.

Available modes are:

- all: Return all whitespace unmodified.
- single: Collapse consecutive whitespace with a single whitespacecharacter, preserving newlines.
- oneline: Collapse all runs of whitespace into a single spacecharacter, removing all newlines in the process.

4.3 新版功能.

原文:

https://tornado-zh-cn.readthedocs.io/zh_CN/latest/template.html