Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 204 lines (152 sloc) 8.497 kb
fd31049 @mitsuhiko all calls are proxied by context.call now so that we can inject environm...
authored
1 Frequently Asked Questions
2 ==========================
3
4 This page answers some of the often asked questions about Jinja.
5
6 .. highlight:: html+jinja
7
8 Why is it called Jinja?
9 -----------------------
10
11 The name Jinja was chosen because it's the name of a Japanese temple and
12 temple and template share a similar pronunciation. It is not named after
accd062 @afandian Kampala is the capital of Uganda! Jinja's significant, but not the capit...
afandian authored
13 the city in Uganda.
fd31049 @mitsuhiko all calls are proxied by context.call now so that we can inject environm...
authored
14
15 How fast is it?
16 ---------------
17
18 We really hate benchmarks especially since they don't reflect much. The
19 performance of a template depends on many factors and you would have to
20 benchmark different engines in different situations. The benchmarks from the
5dfbfc1 @mitsuhiko updated FAQ for performance numbers. I guess I should remove that point...
authored
21 testsuite show that Jinja2 has a similar performance to `Mako`_ and is between
22 10 and 20 times faster than Django's template engine or Genshi. These numbers
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
23 should be taken with tons of salt as the benchmarks that took these numbers
61a5a24 @mitsuhiko fixed a bug in error reporting and some small documentation updates
authored
24 only test a few performance related situations such as looping. Generally
25 speaking the performance of a template engine doesn't matter much as the
26 usual bottleneck in a web application is either the database or the application
27 code.
fd31049 @mitsuhiko all calls are proxied by context.call now so that we can inject environm...
authored
28
29 .. _Mako: http://www.makotemplates.org/
30
31 How Compatible is Jinja2 with Django?
32 -------------------------------------
33
34 The default syntax of Jinja2 matches Django syntax in many ways. However
35 this similarity doesn't mean that you can use a Django template unmodified
36 in Jinja2. For example filter arguments use a function call syntax rather
37 than a colon to separate filter name and arguments. Additionally the
38 extension interface in Jinja is fundamentally different from the Django one
39 which means that your custom tags won't work any longer.
40
41 Generally speaking you will use much less custom extensions as the Jinja
42 template system allows you to use a certain subset of Python expressions
43 which can replace most Django extensions. For example instead of using
44 something like this::
45
46 {% load comments %}
47 {% get_latest_comments 10 as latest_comments %}
48 {% for comment in latest_comments %}
49 ...
50 {% endfor %}
51
52 You will most likely provide an object with attributes to retrieve
53 comments from the database::
54
55 {% for comment in models.comments.latest(10) %}
56 ...
57 {% endfor %}
58
59 Or directly provide the model for quick testing::
60
61 {% for comment in Comment.objects.order_by('-pub_date')[:10] %}
62 ...
63 {% endfor %}
64
65 Please keep in mind that even though you may put such things into templates
604b846 @dennda Fix typo. Closes #343
dennda authored
66 it still isn't a good idea. Queries should go into the view code and not
fd31049 @mitsuhiko all calls are proxied by context.call now so that we can inject environm...
authored
67 the template!
68
69 Isn't it a terrible idea to put Logic into Templates?
70 -----------------------------------------------------
71
72 Without a doubt you should try to remove as much logic from templates as
73 possible. But templates without any logic mean that you have to do all
74 the processing in the code which is boring and stupid. A template engine
75 that does that is shipped with Python and called `string.Template`. Comes
76 without loops and if conditions and is by far the fastest template engine
77 you can get for Python.
78
79 So some amount of logic is required in templates to keep everyone happy.
80 And Jinja leaves it pretty much to you how much logic you want to put into
81 templates. There are some restrictions in what you can do and what not.
82
83 Jinja2 neither allows you to put arbitrary Python code into templates nor
84 does it allow all Python expressions. The operators are limited to the
85 most common ones and more advanced expressions such as list comprehensions
86 and generator expressions are not supported. This keeps the template engine
87 easier to maintain and templates more readable.
88
89 Why is Autoescaping not the Default?
90 ------------------------------------
91
92 There are multiple reasons why automatic escaping is not the default mode
93 and also not the recommended one. While automatic escaping of variables
94 means that you will less likely have an XSS problem it also causes a huge
95 amount of extra processing in the template engine which can cause serious
96 performance problems. As Python doesn't provide a way to mark strings as
97 unsafe Jinja has to hack around that limitation by providing a custom
98 string class (the :class:`Markup` string) that safely interacts with safe
99 and unsafe strings.
100
101 With explicit escaping however the template engine doesn't have to perform
102 any safety checks on variables. Also a human knows not to escape integers
103 or strings that may never contain characters one has to escape or already
104 HTML markup. For example when iterating over a list over a table of
105 integers and floats for a table of statistics the template designer can
106 omit the escaping because he knows that integers or floats don't contain
107 any unsafe parameters.
108
109 Additionally Jinja2 is a general purpose template engine and not only used
110 for HTML/XML generation. For example you may generate LaTeX, emails,
111 CSS, JavaScript, or configuration files.
112
113 Why is the Context immutable?
114 -----------------------------
115
116 When writing a :func:`contextfunction` or something similar you may have
117 noticed that the context tries to stop you from modifying it. If you have
118 managed to modify the context by using an internal context API you may
119 have noticed that changes in the context don't seem to be visible in the
120 template. The reason for this is that Jinja uses the context only as
121 primary data source for template variables for performance reasons.
122
123 If you want to modify the context write a function that returns a variable
124 instead that one can assign to a variable by using set::
125
126 {% set comments = get_latest_comments() %}
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
127
10c34da @mitsuhiko Documented switch to MarkupSafe
authored
128 What is the speedups module and why is it missing?
129 --------------------------------------------------
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
130
3ef2043 @mitsuhiko updated documentation
authored
131 To achieve a good performance with automatic escaping enabled, the escaping
10c34da @mitsuhiko Documented switch to MarkupSafe
authored
132 function was also implemented in pure C in older Jinja2 releases and used if
133 Jinja2 was installed with the speedups module.
134
135 Because this feature itself is very useful for non-template engines as
136 well it was moved into a separate project on PyPI called `MarkupSafe`_.
137
138 Jinja2 no longer ships with a C implementation of it but only the pure
139 Python implementation. It will however check if MarkupSafe is available
140 and installed, and if it is, use the Markup class from MarkupSafe.
141
142 So if you want the speedups, just import MarkupSafe.
143
144 .. _MarkupSafe: http://pypi.python.org/pypi/MarkupSafe
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
145
146 My tracebacks look weird. What's happening?
147 --------------------------------------------
148
10c34da @mitsuhiko Documented switch to MarkupSafe
authored
149 If the debugsupport module is not compiled and you are using a Python
150 installation without ctypes (Python 2.4 without ctypes, Jython or Google's
151 AppEngine) Jinja2 is unable to provide correct debugging information and
152 the traceback may be incomplete. There is currently no good workaround
153 for Jython or the AppEngine as ctypes is unavailable there and it's not
154 possible to use the debugsupport extension.
3ef2043 @mitsuhiko updated documentation
authored
155
c1bc164 @mitsuhiko Added GAE debugging snippet
authored
156 If you are working in the Google Appengine development server you can
157 whitelist the ctypes module to restore the tracebacks. This however won't
158 work in production environments::
159
160 import os
161 if os.environ.get('SERVER_SOFTWARE', '').startswith('Dev'):
162 from google.appengine.tools.dev_appserver import HardenedModulesHook
163 HardenedModulesHook._WHITE_LIST_C_MODULES += ['_ctypes', 'gestalt']
164
165 Credit for this snippet goes to `Thomas Johansson
166 <http://stackoverflow.com/questions/3086091/debug-jinja2-in-google-app-engine/3694434#3694434>`_
167
3ef2043 @mitsuhiko updated documentation
authored
168 Why is there no Python 2.3 support?
169 -----------------------------------
170
171 Python 2.3 is missing a lot of features that are used heavily in Jinja2. This
172 decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes
173 harder to maintain the code for older Python versions. If you really need
174 Python 2.3 support you either have to use `Jinja 1`_ or other templating
175 engines that still support 2.3.
176
2f0d659 @mitsuhiko Reverted [73b04625ab54]. The old behavior is the new behavior, the othe...
authored
177 My Macros are overriden by something
178 ------------------------------------
2b48839 @mitsuhiko added a deprecation warning for a variable assignment, scope bug
authored
179
2f0d659 @mitsuhiko Reverted [73b04625ab54]. The old behavior is the new behavior, the othe...
authored
180 In some situations the Jinja scoping appears arbitrary:
2b48839 @mitsuhiko added a deprecation warning for a variable assignment, scope bug
authored
181
182 layout.tmpl:
183
184 .. sourcecode:: jinja
185
186 {% macro foo() %}LAYOUT{% endmacro %}
187 {% block body %}{% endblock %}
188
189 child.tmpl:
190
191 .. sourcecode:: jinja
192
193 {% extends 'layout.tmpl' %}
194 {% macro foo() %}CHILD{% endmacro %}
195 {% block body %}{{ foo() }}{% endblock %}
196
2f0d659 @mitsuhiko Reverted [73b04625ab54]. The old behavior is the new behavior, the othe...
authored
197 This will print ``LAYOUT`` in Jinja2. This is a side effect of having
198 the parent template evaluated after the child one. This allows child
199 templates passing information to the parent template. To avoid this
200 issue rename the macro or variable in the parent template to have an
201 uncommon prefix.
2b48839 @mitsuhiko added a deprecation warning for a variable assignment, scope bug
authored
202
3ef2043 @mitsuhiko updated documentation
authored
203 .. _Jinja 1: http://jinja.pocoo.org/1/
Something went wrong with that request. Please try again.