1 Switching from other Template Engines
2 =====================================
4 .. highlight:: html+jinja
6 If you have used a different template engine in the past and want to swtich
7 to Jinja2 here is a small guide that shows the basic syntatic and semantic
8 changes between some common, similar text template engines for Python.
13 Jinja2 is mostly compatible with Jinja1 in terms of API usage and template
14 syntax. The differences between Jinja1 and 2 are explained in the following
21 Jinja2 uses a different loader API. Because the internal representation
22 of templates changed there is no longer support for external caching
23 systems such as memcached. The memory consumed by templates is comparable
24 with regular Python modules now and external caching doesn't give any
25 advantage. If you have used a custom loader in the past have a look at
26 the new :ref:`loader API <loaders>`.
28 Loading templates from strings
29 In the past it was possible to generate templates from a string with the
30 default environment configuration by using `jinja.from_string`. Jinja2
31 provides a :class:`Template` class that can be used to do the same, but
32 with optional additional configuration.
34 Automatic unicode conversion
35 Jinja1 performed automatic conversion of bytestrings in a given encoding
36 into unicode objects. This conversion is no longer implemented as it
37 was inconsistent as most libraries are using the regular Python ASCII
38 bytestring to Unicode conversion. An application powered by Jinja2
39 *has to* use unicode internally everywhere or make sure that Jinja2 only
40 gets unicode strings passed.
43 Jinja1 used custom translators for internationalization. i18n is now
44 available as Jinja2 extension and uses a simpler, more gettext friendly
45 interface and has support for babel. For more details see
46 :ref:`i18n-extension`.
49 Jinja1 exposed a few internal methods on the environment object such
50 as `call_function`, `get_attribute` and others. While they were marked
51 as being an internal method it was possible to override them. Jinja2
52 doesn't have equivalent methods.
55 Jinja1 was running sandbox mode by default. Few applications actually
56 used that feature so it became optional in Jinja2. For more details
57 about the sandboxed execution see :class:`SandboxedEnvironment`.
60 Jinja1 had a stacked context as storage for variables passed to the
61 environment. In Jinja2 a similar object exists but it doesn't allow
62 modifications nor is it a singleton. As inheritance is dynamic now
63 multiple context objects may exist during template evaluation.
66 Filters and tests are regular functions now. It's no longer necessary
67 and allowed to use factory functions.
73 Jinja2 has mostly the same syntax as Jinja1. What's different is that
74 macros require parentheses around the argument list now.
76 Additionally Jinja2 allows dynamic inheritance now and dynamic includes.
77 The old helper function `rendertemplate` is gone now, `include` can be used
78 instead. Includes no longer import macros and variable assignments, for
79 that the new `import` tag is used. This concept is explained in the
80 :ref:`import` documentation.
82 Another small change happened in the `for`-tag. The special loop variable
83 doesn't have a `parent` attribute, instead you have to alias the loop
84 yourself. See :ref:`accessing-the-parent-loop` for more details.
90 If you have previously worked with Django templates, you should find
91 Jinja2 very familiar. In fact, most of the syntax elements look and
94 However, Jinja2 provides some more syntax elements covered in the
95 documentation and some work a bit different.
97 This section covers the template changes. As the API is fundamentally
98 different we won't cover it here.
103 In Django method calls work implicitly. With Jinja2 you have to specify that
104 you want to call an object. Thus this Django code::
106 {% for page in user.get_created_pages %}
110 will look like this in Jinja::
112 {% for page in user.get_created_pages() %}
116 This allows you to pass variables to the function which is also used for macros
117 which is not possible in Django.
122 In Django you can use the following constructs to check for equality::
124 {% ifequal foo "bar" %}
130 In Jinja2 you can use the normal if statement in combination with operators::
132 {% if foo == 'bar' %}
138 You can also have multiple elif branches in your template::
142 {% elif otherthing %}
153 Jinja2 provides more than one argument for filters. Also the syntax for
154 argument passing is different. A template that looks like this in Django::
156 {{ items|join:", " }}
158 looks like this in Jinja2::
160 {{ items|join(', ') }}
162 In fact it's a bit more verbose but it allows different types of arguments -
163 including variables - and more than one of them.
168 In addition to filters there also are tests you can perform using the is
169 operator. Here are some examples::
171 {% if user.user_id is odd %}
172 {{ user.username|e }} is odd
174 hmm. {{ user.username|e }} looks pretty normal
180 For loops work very similar to Django, the only incompatibility is that in
181 Jinja2 the special variable for the loop context is called `loop` and not
182 `forloop` like in Django.
187 The ``{% cycle %}`` tag does not exist in Jinja because of it's implicit
188 nature. However you can achieve mostly the same by using the `cycle`
189 method on a loop object.
191 The following Django template::
193 {% for user in users %}
194 <li class="{% cycle 'odd' 'even' %}">{{ user }}</li>
197 Would look like this in Jinja::
199 {% for user in users %}
200 <li class="{{ loop.cycle('odd', 'even') }}">{{ user }}</li>
203 There is no equivalent of ``{% cycle ... as variable %}``.
209 .. highlight:: html+mako
211 If you have used Mako so far and want to switch to Jinja2 you can configure
212 Jinja2 to look more like Mako:
214 .. sourcecode:: python
216 env = Environment('<%', '%>', '${', '}', '%')
218 Once the environment is configure like that Jinja2 should be able to interpret
219 a small subset of Mako templates. Jinja2 does not support embedded Python code
220 so you would have to move that out of the template. The syntax for defs (in
221 Jinja2 defs are called macros) and template inheritance is different too. The
222 following Mako template::
224 <%inherit file="layout.html" />
225 <%def name="title()">Page Title</%def>
232 Looks like this in Jinja2 with the above configuration::
234 <% extends "layout.html" %>
235 <% block title %>Page Title<% endblock %>