Introduction

The web.py template language, called Templetor is designed to bring the power of Python to templates.
Instead of inventing new syntax for templates, it re-uses python syntax.
If you know the Python programming language, you will be at home.

Templetor intentionally limits variable access within a template. A user has access to the variables passed into the template and some builtin python functions. This allows untrusted users to write templates, and not worry about them causing harm to the running system. You can, of course, increase the global variables available, but more on this later.

Here is a simple template:

$def with (name)
Hello $name!

The first line says that the template is defined with one argument called name.
$name in the second line will be replaced with the value of name when the template is rendered.

Using the template system

The most common way of rendering templates is this:

render = web.template.render('templates')
print render.hello('world')

The render function takes the template root as argument. render.hello(..) calls the template hello.html with the given arguments.
In fact, it looks for the files matching hello.* in the template root and picks the first matching file.

Assignments

Sometimes you may want to define new variables and re-assign some variables.

$ bug = get_bug(id)
<h1>$bug.title</h1>
<div>
$bug.description
<div>

Notice the space after $ in the assignment. It is required to differentiate assignment from expression substitution.

Filtering

By default, Templetor uses web.websafe filter to do HTML-encoding.

>>> render.hello("1 < 2")
"Hello 1 &lt; 2"

To turnoff filter use : after $. For example:

The following will not be html escaped.
$:form.render()

Newline suppression

Newline can be suppressed by adding \ character at the end of line.

If you put a backslash \
at the end of a line \
(like these) \
then there will be no newline.

Escaping $

Use $$ to get $ in the output.

Can you lend me $$50?

Comments

$# is used as comment indicator. Anything starting with $# till end of the line is ignored.

$# this is a comment
Hello $name.title()! $# display the name in title case

Control Structures

The template system supports for, while, if, elif and else.
Just like in python, body of the statement is indented.

$for i in range(10):
I like $i
$for i in range(10): I like $i
$while a:
hello $a.pop()
$if times > max:
Stop! In the name of love.
$else:
Keep on, you can do it.

The for loop sets a number of variables available within the loop:

loop.index: the iteration of the loop (1-indexed)
loop.index0: the iteration of the loop (0-indexed)
loop.first: True if first iteration
loop.last: True if last iteration
loop.odd: True if an odd iteration
loop.even: True if an even iteration
loop.parity: "odd" or "even" depending on which is true
loop.parent: the loop above this in nested loops

code

Arbitrary python code can be written using the code block.

$code:
x = "you can write any python code here"
y = x.title()
z = len(x + y)
def limit(s, width=10):
"""limits a string to the given width"""
if len(s) >= width:
return s[:width] + "..."
else:
return s
And we are back to template.
The variables defined in the code block can be used here.
For example, $limit(x)

var

The var block can be used to define additional properties in the template result.

builtins and globals

Just like any Python function, template can also access builtins along with its arguments and local variables.
Some common builtin functions like range, min, max etc. and boolean values True and False are made available to all the templates.
Apart from the builtins, application specific globals can be specified to make them accessible in all the templates.