Developer Quickstart — Jinja Documentation

# Jinja

## 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.

Basically the important method on a template is the render method. It takes either a dict or keyword arguments. All keyword arguments appear in the template as variables.

So these two snippets do the same:

    tmpl.render(
        knights='we say nih',
        spam='and eggs'
    )

    tmpl.render({
        'knights':  'we say nih',
        'spam':     'and eggs'
    })

## The Environment

The Jinja environment.

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

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. If auto_escape is `True` there will be also a `Markup` object in the template namespace to define partial html fragments. Note that we do not recommend this feature.
default_filters | list of tuples in the form (`filter_name`, `arguments`) where `filter_name` is the name of a registered filter and `arguments` a tuple with the filter arguments. The filters specified here will always be applied when printing data to the template. new in Jinja 1.1
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.
context_class | the context class this template should use. See the Context documentation for more details.
undefined_singleton | The singleton value that is used for missing variables. new in Jinja 1.1
disable_regexps | Disable support for regular expresssions.
friendly_traceback | Set this to False to disable the developer friendly traceback rewriting. Whenever an runtime or syntax error occours jinja will try to make a developer friendly traceback that shows the error in the template line. This however can be annoying when debugging broken functions that are called from the template. new in Jinja 1.1
translator_factory | A callback function that is called with the context as first argument to get the translator for the current instance. new in Jinja 1.2

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.
`lex(source, filename)` | Tokenize the given sourcecode and return a generator of tuples in the form `(lineno, token, value)`. The filename is just used in the exceptions raised. New in Jinja 1.1
`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.

## Undefined Values

If a template designer tries to access a not defined value the return value will be the undefined_singleton specified in the environment. The default one is the SilentUndefined which fails in no case. Additionally there is a special undefined type called the ComplainingUndefined which is located in the jinja.datastructure module. It will raise exceptions when compared with other types, or when rendered.

Theoretically you can provide your own singleton by subclassing AbstractUndefindedType and creating an instance of it using make_undefined (both located in jinja.datastructure) but those two types should cover the basic use cases. The Undefined object in that module exists for backwards compatibility and is an alias for SilentUndefined.

To create your own undefined singleton do something like this:

    from jinja.datastructure import AbstractUndefinedType, make_undefined

    class MyUndefinedType(AbstractUndefindedType):
        __slots__ = ()

        def __iter__(self):
            return iter(int, 0)

        def __reduce__(self):
            return 'MyUndefined'

    MyUndefined = make_undefined(MyUndefinedType)

The only thing you have to do is to override __reduce__ so that it returns the name of the singleton instance and create the instance using make_undefined. Everything else is up to you. Note that currently attributes on undefined objects are available in the Jinja layer too which however will change in one of the next Jinja versions. So if you put a foo attribute on your undefined singleton you will be able to do `{{ undefined.foo }}` by now but certainly not in the future.

This limitation currently exists because undefined is treated as normal object and thus affected by normal getattr calls.

## Automatic Escaping

Jinja provides a way for automatic escaping, but we do not recommend using it. Because Jinja was designed as multi purpose template engine there are some issues with automatic escaping. For example filters don't deal with markup data. Also you can easily bypass the automatic escaping so it's not something you can expect to "just work". Also there is a huge overhead when escaping everything.

The best idea is to think about which data already contains html, which will probably contain (eg: every user input, etc) etc. And live with self escaping.

That's usually a much better idea.

## 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.