How to Upgrade to Jinja 1.1?

Since Version 1.1 Jinja uses a completely different concept internally. If you have complex Jinja template setups and don't want upgrade it's a good idea to ship the Jinja 0.9 version as requirement. There is a branch for Jinja < 1.0 that receives security updates etc. You can find it in the Jinja SVN.

I want to upgrade. What's new?

Basically Jinja 1.0 is a complete rewrite and has a different idea. It's a lot more flexible now and supports expressions. So you can put slightly more logic into the templates. This can be useful if you have to perform small calculations in the templats such as calling methods with paramters etc.

Upgrading is pretty straightforward. Here what has changed on the template site.

Template Changes

• it's {# comment #} instead of {* comment *} in the default settings.
• it's {% block name %} instead of {% block "name" %}
• Method calls require a call operator foo() and you can now pass parameters to it
• instead of {{ foo|bar baz|blah }} it's now {{ foo|bar(baz)|blah }}
• you can use filters everywhere. So also do things like {% for item in seq|reverse %}
• loops don't have a reverse modifier, just apply the reverse function

There are some other changes too such as missing custom tag support but there are function calls and macros as alternatives which are documented in the new docs.

Changes in the API

The new API is a lot simpler. You now have one central class called an environment which provides all required things.

If this was the old code:

from jinja import Template, Context, FileSystemLoader

t = Template('templatename', FileSystemLoader('path/to/the/templates'))
c = Context({
    'users': [
        {'name': 'someone', 'id': 1, 'visible': True},
        {'name': 'notme', 'id': 2, 'visible': True},
        {'name': 'peter', 'id': 3, 'visible': False}
    ]
})
print t.render(c)

Then this is the new version:

from jinja import Environment, FileSystemLoader
env = Environment(loader=FileSystemLoader('path/to/the/templates'))
t = env.get_template('templatename.html')
print t.render(users=[
    {'name': 'someone', 'id': 1, 'visible': True},
    {'name': 'notme', 'id': 2, 'visible': True},
    {'name': 'peter', 'id': 3, 'visible': False}
])

Help! I'm Lost

Visit #pocoo on irc.freenode.net then and ask your question or consult the the new documentation.