Armin Ronacher | fd31049 | 2008-05-25 00:16:51 +0200 | [diff] [blame] | 1 | Frequently Asked Questions |
| 2 | ========================== |
| 3 | |
| 4 | This page answers some of the often asked questions about Jinja. |
| 5 | |
| 6 | .. highlight:: html+jinja |
| 7 | |
Armin Ronacher | fd31049 | 2008-05-25 00:16:51 +0200 | [diff] [blame] | 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 |
Joe Wass | accd062 | 2011-05-19 03:58:05 -0700 | [diff] [blame] | 13 | the city in Uganda. |
Armin Ronacher | fd31049 | 2008-05-25 00:16:51 +0200 | [diff] [blame] | 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 |
Armin Ronacher | 5dfbfc1 | 2008-05-25 18:10:12 +0200 | [diff] [blame] | 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 |
Armin Ronacher | 5411ce7 | 2008-05-25 11:36:22 +0200 | [diff] [blame] | 23 | should be taken with tons of salt as the benchmarks that took these numbers |
Armin Ronacher | 61a5a24 | 2008-05-26 12:07:44 +0200 | [diff] [blame] | 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. |
Armin Ronacher | fd31049 | 2008-05-25 00:16:51 +0200 | [diff] [blame] | 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 |
Christopher Denter | 604b846 | 2009-04-28 01:50:32 +0200 | [diff] [blame] | 66 | it still isn't a good idea. Queries should go into the view code and not |
Armin Ronacher | fd31049 | 2008-05-25 00:16:51 +0200 | [diff] [blame] | 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() %} |
Armin Ronacher | 5411ce7 | 2008-05-25 11:36:22 +0200 | [diff] [blame] | 127 | |
Armin Ronacher | 5411ce7 | 2008-05-25 11:36:22 +0200 | [diff] [blame] | 128 | My tracebacks look weird. What's happening? |
| 129 | -------------------------------------------- |
| 130 | |
Armin Ronacher | 10c34da | 2010-08-17 12:10:27 +0200 | [diff] [blame] | 131 | If the debugsupport module is not compiled and you are using a Python |
| 132 | installation without ctypes (Python 2.4 without ctypes, Jython or Google's |
| 133 | AppEngine) Jinja2 is unable to provide correct debugging information and |
| 134 | the traceback may be incomplete. There is currently no good workaround |
| 135 | for Jython or the AppEngine as ctypes is unavailable there and it's not |
| 136 | possible to use the debugsupport extension. |
Armin Ronacher | 3ef2043 | 2008-06-09 18:27:19 +0200 | [diff] [blame] | 137 | |
Alex Chan | 972c030 | 2015-04-05 22:42:34 +0100 | [diff] [blame] | 138 | If you are working in the Google AppEngine development server you can |
Armin Ronacher | c1bc164 | 2011-09-25 14:30:12 +0200 | [diff] [blame] | 139 | whitelist the ctypes module to restore the tracebacks. This however won't |
| 140 | work in production environments:: |
| 141 | |
| 142 | import os |
| 143 | if os.environ.get('SERVER_SOFTWARE', '').startswith('Dev'): |
| 144 | from google.appengine.tools.dev_appserver import HardenedModulesHook |
| 145 | HardenedModulesHook._WHITE_LIST_C_MODULES += ['_ctypes', 'gestalt'] |
| 146 | |
| 147 | Credit for this snippet goes to `Thomas Johansson |
| 148 | <http://stackoverflow.com/questions/3086091/debug-jinja2-in-google-app-engine/3694434#3694434>`_ |
| 149 | |
Markus Unterwaditzer | 06a8f5b | 2015-06-01 17:15:43 +0200 | [diff] [blame] | 150 | Why is there no Python 2.3/2.4/2.5/3.1/3.2 support? |
| 151 | --------------------------------------------------- |
Armin Ronacher | 3ef2043 | 2008-06-09 18:27:19 +0200 | [diff] [blame] | 152 | |
| 153 | Python 2.3 is missing a lot of features that are used heavily in Jinja2. This |
| 154 | decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes |
| 155 | harder to maintain the code for older Python versions. If you really need |
| 156 | Python 2.3 support you either have to use `Jinja 1`_ or other templating |
| 157 | engines that still support 2.3. |
| 158 | |
Markus Unterwaditzer | 06a8f5b | 2015-06-01 17:15:43 +0200 | [diff] [blame] | 159 | Python 2.4/2.5/3.1/3.2 support was removed when we switched to supporting |
| 160 | Python 2 and 3 by the same sourcecode (without using 2to3). It was required to |
| 161 | drop support because only Python 2.6/2.7 and >=3.3 support byte and unicode |
| 162 | literals in a way compatible to each other version. If you really need support |
| 163 | for older Python 2 (or 3) versions, you can just use Jinja2 2.6. |
| 164 | |
Jonas Nockert | bdd09dd | 2013-02-23 20:34:47 +0100 | [diff] [blame] | 165 | My Macros are overridden by something |
Armin Ronacher | da94a8b | 2013-05-20 14:06:59 +0100 | [diff] [blame] | 166 | ------------------------------------- |
Armin Ronacher | 2b48839 | 2009-09-18 19:32:46 +0200 | [diff] [blame] | 167 | |
Armin Ronacher | 2f0d659 | 2009-10-26 11:53:27 +0100 | [diff] [blame] | 168 | In some situations the Jinja scoping appears arbitrary: |
Armin Ronacher | 2b48839 | 2009-09-18 19:32:46 +0200 | [diff] [blame] | 169 | |
| 170 | layout.tmpl: |
| 171 | |
| 172 | .. sourcecode:: jinja |
| 173 | |
| 174 | {% macro foo() %}LAYOUT{% endmacro %} |
| 175 | {% block body %}{% endblock %} |
| 176 | |
| 177 | child.tmpl: |
| 178 | |
| 179 | .. sourcecode:: jinja |
| 180 | |
| 181 | {% extends 'layout.tmpl' %} |
| 182 | {% macro foo() %}CHILD{% endmacro %} |
| 183 | {% block body %}{{ foo() }}{% endblock %} |
| 184 | |
Armin Ronacher | 2f0d659 | 2009-10-26 11:53:27 +0100 | [diff] [blame] | 185 | This will print ``LAYOUT`` in Jinja2. This is a side effect of having |
| 186 | the parent template evaluated after the child one. This allows child |
| 187 | templates passing information to the parent template. To avoid this |
| 188 | issue rename the macro or variable in the parent template to have an |
| 189 | uncommon prefix. |
Armin Ronacher | 2b48839 | 2009-09-18 19:32:46 +0200 | [diff] [blame] | 190 | |
Armin Ronacher | 3ef2043 | 2008-06-09 18:27:19 +0200 | [diff] [blame] | 191 | .. _Jinja 1: http://jinja.pocoo.org/1/ |