1Frequently Asked Questions
2==========================
3
4This page answers some of the often asked questions about Jinja.
5
6.. highlight:: html+jinja
7
8Why is it called Jinja?
9-----------------------
10
11The name Jinja was chosen because it's the name of a Japanese temple and
12temple and template share a similar pronunciation.  It is not named after
13the city in Uganda.
14
15How fast is it?
16---------------
17
18We really hate benchmarks especially since they don't reflect much.  The
19performance of a template depends on many factors and you would have to
20benchmark different engines in different situations.  The benchmarks from the
21testsuite show that Jinja has a similar performance to `Mako`_ and is between
2210 and 20 times faster than Django's template engine or Genshi.  These numbers
23should be taken with tons of salt as the benchmarks that took these numbers
24only test a few performance related situations such as looping.  Generally
25speaking the performance of a template engine doesn't matter much as the
26usual bottleneck in a web application is either the database or the application
27code.
28
29.. _Mako: https://www.makotemplates.org/
30
31How Compatible is Jinja with Django?
32------------------------------------
33
34The default syntax of Jinja matches Django syntax in many ways.  However
35this similarity doesn't mean that you can use a Django template unmodified
36in Jinja.  For example filter arguments use a function call syntax rather
37than a colon to separate filter name and arguments.  Additionally the
38extension interface in Jinja is fundamentally different from the Django one
39which means that your custom tags won't work any longer.
40
41Generally speaking you will use much less custom extensions as the Jinja
42template system allows you to use a certain subset of Python expressions
43which can replace most Django extensions.  For example instead of using
44something like this::
45
46    {% load comments %}
47    {% get_latest_comments 10 as latest_comments %}
48    {% for comment in latest_comments %}
49        ...
50    {% endfor %}
51
52You will most likely provide an object with attributes to retrieve
53comments from the database::
54
55    {% for comment in models.comments.latest(10) %}
56        ...
57    {% endfor %}
58
59Or directly provide the model for quick testing::
60
61    {% for comment in Comment.objects.order_by('-pub_date')[:10] %}
62        ...
63    {% endfor %}
64
65Please keep in mind that even though you may put such things into templates
66it still isn't a good idea.  Queries should go into the view code and not
67the template!
68
69Isn't it a terrible idea to put Logic into Templates?
70-----------------------------------------------------
71
72Without a doubt you should try to remove as much logic from templates as
73possible.  But templates without any logic mean that you have to do all
74the processing in the code which is boring and stupid.  A template engine
75that does that is shipped with Python and called `string.Template`.  Comes
76without loops and if conditions and is by far the fastest template engine
77you can get for Python.
78
79So some amount of logic is required in templates to keep everyone happy.
80And Jinja leaves it pretty much to you how much logic you want to put into
81templates.  There are some restrictions in what you can do and what not.
82
83Jinja neither allows you to put arbitrary Python code into templates nor
84does it allow all Python expressions.  The operators are limited to the
85most common ones and more advanced expressions such as list comprehensions
86and generator expressions are not supported.  This keeps the template engine
87easier to maintain and templates more readable.
88
89Why is Autoescaping not the Default?
90------------------------------------
91
92There are multiple reasons why automatic escaping is not the default mode
93and also not the recommended one.  While automatic escaping of variables
94means that you will less likely have an XSS problem it also causes a huge
95amount of extra processing in the template engine which can cause serious
96performance problems.  As Python doesn't provide a way to mark strings as
97unsafe Jinja has to hack around that limitation by providing a custom
98string class (the :class:`Markup` string) that safely interacts with safe
99and unsafe strings.
100
101With explicit escaping however the template engine doesn't have to perform
102any safety checks on variables.  Also a human knows not to escape integers
103or strings that may never contain characters one has to escape or already
104HTML markup.  For example when iterating over a list over a table of
105integers and floats for a table of statistics the template designer can
106omit the escaping because he knows that integers or floats don't contain
107any unsafe parameters.
108
109Additionally Jinja is a general purpose template engine and not only used
110for HTML/XML generation.  For example you may generate LaTeX, emails,
111CSS, JavaScript, or configuration files.
112
113Why is the Context immutable?
114-----------------------------
115
116When writing a :func:`contextfunction` or something similar you may have
117noticed that the context tries to stop you from modifying it.  If you have
118managed to modify the context by using an internal context API you may
119have noticed that changes in the context don't seem to be visible in the
120template.  The reason for this is that Jinja uses the context only as
121primary data source for template variables for performance reasons.
122
123If you want to modify the context write a function that returns a variable
124instead that one can assign to a variable by using set::
125
126    {% set comments = get_latest_comments() %}
127
128My tracebacks look weird. What's happening?
129-------------------------------------------
130
131Jinja can rewrite tracebacks so they show the template lines numbers and
132source rather than the underlying compiled code, but this requires
133special Python support. CPython <3.7 requires ``ctypes``, and PyPy
134requires transparent proxy support.
135
136If you are using Google App Engine, ``ctypes`` is not available. You can
137make it available in development, but not in production.
138
139.. code-block:: python
140
141    import os
142    if os.environ.get('SERVER_SOFTWARE', '').startswith('Dev'):
143        from google.appengine.tools.devappserver2.python import sandbox
144        sandbox._WHITE_LIST_C_MODULES += ['_ctypes', 'gestalt']
145
146Credit for this snippet goes to `Thomas Johansson
147<https://stackoverflow.com/questions/3086091/debug-jinja2-in-google-app-engine/3694434#3694434>`_
148
149My Macros are overridden by something
150-------------------------------------
151
152In some situations the Jinja scoping appears arbitrary:
153
154layout.tmpl:
155
156.. sourcecode:: jinja
157
158    {% macro foo() %}LAYOUT{% endmacro %}
159    {% block body %}{% endblock %}
160
161child.tmpl:
162
163.. sourcecode:: jinja
164
165    {% extends 'layout.tmpl' %}
166    {% macro foo() %}CHILD{% endmacro %}
167    {% block body %}{{ foo() }}{% endblock %}
168
169This will print ``LAYOUT`` in Jinja.  This is a side effect of having
170the parent template evaluated after the child one.  This allows child
171templates passing information to the parent template.  To avoid this
172issue rename the macro or variable in the parent template to have an
173uncommon prefix.
174
175.. _Jinja 1: https://pypi.org/project/Jinja/
176