tornado.template — Flexible output generation

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 caches the 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 %}

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

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

Translating directly to Python means you can apply functions to expressions easily, like the escape() function in the examples above. You can pass functions in to your template just like any other variable:

### Python code
def add(x, y):
   return x + y
template.execute(add=add)

### The template
{{ 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 by hand, but instead use the render and render_string methods of tornado.web.RequestHandler, which load templates automatically based on the template_path Application setting.

class tornado.template.Template(template_string, name='<string>', loader=None, compress_whitespace=None, autoescape=<object object at 0x2512d50>)[source]

A compiled template.

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

generate(**kwargs)[source]

Generate this template with the given arguments.

class tornado.template.BaseLoader(root_directory, autoescape='xhtml_escape')[source]

Base class for template loaders.

Creates a template loader.

root_directory may be the empty string if this loader does not use the filesystem.

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

reset()[source]

Resets the cache of compiled templates.

resolve_path(name, parent_path=None)[source]

Converts a possibly-relative path to absolute (used internally).

load(name, parent_path=None)[source]

Loads a template.

class tornado.template.Loader(root_directory, **kwargs)[source]

A template loader that loads from a single root directory.

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

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.

x.__init__(...) initializes x; see help(type(x)) for signature

Previous topic

tornado.httpserver — Non-blocking HTTP server

Next topic

tornado.escape — Escaping and string manipulation

This Page