tornado.template — Flexible output generation — Tornado 3.2.dev1 documentation (2024)

A simple template system that compiles templates to Python code.

Basic usage looks like:

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

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

loader = template.Loader("/home/btaylor")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:

### base.html<html> <head> <title>{% block title %}Default title{% end %}</title> </head> <body> <ul> {% for student in students %} {% block student %} <li>{{ escape(student.name) }}</li> {% end %} {% end %} </ul> </body></html>### bold.html{% extends "base.html" %}{% block title %}A bolder title{% end %}{% block student %} <li><span style="bold">{{ escape(student.name) }}</span></li>{% end %}

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 {% %}. These tags may be escaped as {{!and {%! if you need to include a literal {{ or {% in the output.

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

{% apply *function* %}...{% end %}

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

{% 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.:

{% 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.:

<!-- 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:

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

{% raw *expr* %}

Outputs the result of the given expression without autoescaping.

{% set *x* = *y* %}

Sets a local variable.

{% try %}...{% except %}...{% finally %}...{% else %}...{% 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.

Class reference¶

class tornado.template.Template(template_string, name="<string>", loader=None, compress_whitespace=None, autoescape="xhtml_escape")[source]¶

A compiled template.

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

generate(**kwargs)[source]¶: Generate this template with the given arguments.

class tornado.template.BaseLoader(autoescape='xhtml_escape', namespace=None)[source]¶

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.

autoescape must be either None or a string naming a functionin the template namespace, such as “xhtml_escape”.

load(name, parent_path=None)[source]¶: Loads a template.

reset()[source]¶: Resets the cache of compiled templates.

resolve_path(name, parent_path=None)[source]¶: Converts a possibly-relative path to absolute (used internally).

class tornado.template.Loader(root_directory, **kwargs)[source]¶: A template loader that loads from a single root directory.

class tornado.template.DictLoader(dict, **kwargs)[source]¶: A template loader that loads from a dictionary.

exception tornado.template.ParseError[source]¶: Raised for template syntax errors.