docs/faq.rst

   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
  13 the capital city of Uganda.
  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
  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
  23 should be taken with tons of salt as the benchmarks that took these numbers
  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.
  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
  66 it still isn't a good idea.  Queries should go into the view code and not
  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() %}
 127
 128 I don't have the _speedups Module.  Is Jinja slower now?
 129 --------------------------------------------------------
 130
 131 To achieve a good performance with automatic escaping enabled, the escaping
 132 function is also implemented in pure C and used if Jinja2 was installed with
 133 the speedups module.  This happens automatically if a C compiler is available
 134 on the system during installation.
 135
 136 My tracebacks look weird.  What's happening?
 137 --------------------------------------------
 138
 139 If the speedups module is not compiled and you are using a Python installation
 140 without ctypes (Python 2.4 without ctypes, Jython or Google's AppEngine)
 141 Jinja2 is unable to provide correct debugging information and the traceback
 142 may be incomplete.  There is currently no good workaround for Jython or
 143 the AppEngine as ctypes is unavailable there and it's not possible to use
 144 the speedups extension.
 145
 146 Why is there no Python 2.3 support?
 147 -----------------------------------
 148
 149 Python 2.3 is missing a lot of features that are used heavily in Jinja2.  This
 150 decision was made as with the upcoming Python 2.6 and 3.0 versions it becomes
 151 harder to maintain the code for older Python versions.  If you really need
 152 Python 2.3 support you either have to use `Jinja 1`_ or other templating
 153 engines that still support 2.3.
 154
 155 My Macros are overriden by something
 156 ------------------------------------
 157
 158 In some situations the Jinja scoping appears arbitrary:
 159
 160 layout.tmpl:
 161
 162 .. sourcecode:: jinja
 163
 164     {% macro foo() %}LAYOUT{% endmacro %}
 165     {% block body %}{% endblock %}
 166
 167 child.tmpl:
 168
 169 .. sourcecode:: jinja
 170
 171     {% extends 'layout.tmpl' %}
 172     {% macro foo() %}CHILD{% endmacro %}
 173     {% block body %}{{ foo() }}{% endblock %}
 174
 175 This will print ``LAYOUT`` in Jinja2.  This is a side effect of having
 176 the parent template evaluated after the child one.  This allows child
 177 templates passing information to the parent template.  To avoid this
 178 issue rename the macro or variable in the parent template to have an
 179 uncommon prefix.
 180
 181 .. _Jinja 1: http://jinja.pocoo.org/1/