Developer Quickstart



This part of the documentation shows you how to embed Jinja into your application.

Starting Up

Here the quickest way to create a template from a string and render it:

from jinja import Environment
env = Environment()
tmpl = env.from_string('Hello {{ name }}!')
print tmpl.render(name='John Doe')

This example should output the following string after execution:

Hello John Doe!

If you receive an error, check if you have a typo in your code. If not, have a look at the installation page for troubleshooting.

The Environment

The core component of Jinja is the Environment. It contains important shared variables like configuration, filters, tests, globals and other stuff.

Here the possible initialization parameters:

block_start_string * the string marking the begin of a block. this defaults to '{%'.
block_end_string * the string marking the end of a block. defaults to '%}'.
variable_start_string * the string marking the begin of a print statement. defaults to '{{'.
comment_start_string * the string marking the begin of a comment. defaults to '{#'.
comment_end_string * the string marking the end of a comment. defaults to '#}'.
trim_blocks * If this is set to True the first newline after a block is removed (block, not variable tag!). Defaults to False.
auto_escape If this is set to True Jinja will automatically escape all variables using xml escaping methods. If you don't want to escape a string you have to wrap it in a Markup object from the jinja.datastructure module.
template_charset The charset of the templates. Defaults to 'utf-8'.
charset Charset of all string input data. Defaults to 'utf-8'.
namespace Global namespace for all templates.
loader Specify a template loader.
filters dict of filters or the default filters if not defined.
tests dict of tests of the default tests if not defined.

All of these variables except those marked with a star (*) are modifiable after environment initialization.

The environment provides the following useful functions and properties in addition to the initialization values:

parse(source, filename) Parse the sourcecode and return the abstract syntax tree. This tree of nodes is used by the translators to convert the template into executable source- or bytecode.
from_string(source) Load and parse a template source and translate it into eval-able Python code. This code is wrapped within a Template class that allows you to render it.
get_template(name) Load a template from a loader. If the template does not exist, you will get a TemplateNotFound exception.

There are also some internal functions on the environment used by the template evaluation code to keep it sandboxed.

Loading Templates From Files

Loading templates from a string is always a bad idea. It doesn't allow template inheritance and is also slow since it parses and compiles the template again and again whereas loaders can cache the template code.

All you have to do is to define a loader and use the get_template function.

from jinja import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader('templates'))
tmpl = env.get_template('index.html')
print tmpl.render(name='John Doe')

This tells jinja to look for templates in the templates folder. It's a better idea to use an absolute path here though. For a list of supported loaders or how to write your own, head over to the loader documentation.

Adding Filters

If you want to add additional filters to the environment, the best way is to modify the filters attribute and not to pass a dict to the environment. If you pass it a dict it will not include the default filters!

from mylib import my_cool_filter
env.filters['mycoolfilter'] = my_cool_filter

Writing filter functions is explained in the filter development section.

Adding Tests

Adding additional tests works analogous to filters:

from mylib import my_cool_test
env.tests['mycooltest'] = my_cool_test

Writing tests is explained in the test development section.