docs/switching.rst

   1 Switching from other Template Engines
   2 =====================================
   3
   4 .. highlight:: html+jinja
   5
   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.
   9
  10 Jinja1
  11 ------
  12
  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
  15 list.
  16
  17 API
  18 ~~~
  19
  20 Loaders
  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>`.
  27
  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.
  33
  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.
  41
  42 i18n
  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`.
  47
  48 Internal methods
  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.
  53
  54 Sandbox
  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`.
  58
  59 Context
  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.
  64
  65 Filters and Tests
  66     Filters and tests are regular functions now.  It's no longer necessary
  67     and allowed to use factory functions.
  68
  69
  70 Templates
  71 ~~~~~~~~~
  72
  73 Jinja2 has mostly the same syntax as Jinja1.  What's different is that
  74 macros require parentheses around the argument list now.
  75
  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.
  81
  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.
  85
  86
  87 Django
  88 ------
  89
  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
  92 work the same.
  93
  94 However, Jinja2 provides some more syntax elements covered in the
  95 documentation and some work a bit different.
  96
  97 This section covers the template changes.  As the API is fundamentally
  98 different we won't cover it here.
  99
 100 Method Calls
 101 ~~~~~~~~~~~~
 102
 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::
 105
 106     {% for page in user.get_created_pages %}
 107         ...
 108     {% endfor %}
 109
 110 will look like this in Jinja::
 111
 112     {% for page in user.get_created_pages() %}
 113         ...
 114     {% endfor %}
 115
 116 This allows you to pass variables to the function which is also used for macros
 117 which is not possible in Django.
 118
 119 Conditions
 120 ~~~~~~~~~~
 121
 122 In Django you can use the following constructs to check for equality::
 123
 124     {% ifequal foo "bar" %}
 125         ...
 126     {% else %}
 127         ...
 128     {% endifequal %}
 129
 130 In Jinja2 you can use the normal if statement in combination with operators::
 131
 132     {% if foo == 'bar' %}
 133         ...
 134     {% else %}
 135         ...
 136     {% endif %}
 137
 138 You can also have multiple elif branches in your template::
 139
 140     {% if something %}
 141         ...
 142     {% elif otherthing %}
 143         ...
 144     {% elif foothing %}
 145         ...
 146     {% else %}
 147         ...
 148     {% endif %}
 149
 150 Filter Arguments
 151 ~~~~~~~~~~~~~~~~
 152
 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::
 155
 156     {{ items|join:", " }}
 157
 158 looks like this in Jinja2::
 159
 160     {{ items|join(', ') }}
 161
 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.
 164
 165 Tests
 166 ~~~~~
 167
 168 In addition to filters there also are tests you can perform using the is
 169 operator.  Here are some examples::
 170
 171     {% if user.user_id is odd %}
 172         {{ user.username|e }} is odd
 173     {% else %}
 174         hmm. {{ user.username|e }} looks pretty normal
 175     {% endif %}
 176
 177 Loops
 178 ~~~~~
 179
 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.
 183
 184
 185 Mako
 186 ----
 187
 188 .. highlight:: html+mako
 189
 190 If you have used Mako so far and want to switch to Jinja2 you can configure
 191 Jinja2 to look more like Mako:
 192
 193 .. sourcecode:: python
 194
 195     env = Environment('<%', '%>', '${', '}', '%')
 196
 197 Once the environment is configure like that Jinja2 should be able to interpret
 198 a small subset of Mako templates.  Jinja2 does not support embedded Python code
 199 so you would have to move that out of the template.  The syntax for defs (in
 200 Jinja2 defs are called macros) and template inheritance is different too.  The
 201 following Mako template::
 202
 203     <%inherit file="layout.html" />
 204     <%def name="title()">Page Title</%def>
 205     <ul>
 206     % for item in list:
 207         <li>${item}</li>
 208     % endfor
 209     </ul>
 210
 211 Looks like this in Jinja2 with the above configuration::
 212
 213     <% extends "layout.html" %>
 214     <% block title %>Page Title<% endblock %>
 215     <% block body %>
 216     <ul>
 217     % for item in list:
 218         <li>${item}</li>
 219     % endfor
 220     </ul>
 221     <% endblock %>