docs/extensions.rst

   1 .. _jinja-extensions:
   2
   3 Extensions
   4 ==========
   5
   6 Jinja2 supports extensions that can add extra filters, tests, globals or even
   7 extend the parser.  The main motivation of extensions is it to move often used
   8 code into a reusable class like adding support for internationalization.
   9
  10
  11 Adding Extensions
  12 -----------------
  13
  14 Extensions are added to the Jinja2 environment at creation time.  Once the
  15 environment is created additional extensions cannot be added.  To add an
  16 extension pass a list of extension classes or import paths to the
  17 `environment` parameter of the :class:`Environment` constructor.  The following
  18 example creates a Jinja2 environment with the i18n extension loaded::
  19
  20     jinja_env = Environment(extensions=['jinja2.ext.i18n'])
  21
  22
  23 .. _i18n-extension:
  24
  25 i18n Extension
  26 --------------
  27
  28 **Import name:** `jinja2.ext.i18n`
  29
  30 Jinja2 currently comes with one extension, the i18n extension.  It can be
  31 used in combination with `gettext`_ or `babel`_.  If the i18n extension is
  32 enabled Jinja2 provides a `trans` statement that marks the wrapped string as
  33 translatable and calls `gettext`.
  34
  35 After enabling dummy `_` function that forwards calls to `gettext` is added
  36 to the environment globals.  An internationalized application then has to
  37 provide at least an `gettext` and optoinally a `ngettext` function into the
  38 namespace.  Either globally or for each rendering.
  39
  40 After enabling of the extension the environment provides the following
  41 additional methods:
  42
  43 .. method:: jinja2.Environment.install_gettext_translations(translations)
  44
  45     Installs a translation globally for that environment.  The tranlations
  46     object provided must implement at least `ugettext` and `ungettext`.
  47     The `gettext.NullTranslations` and `gettext.GNUTranslations` classes
  48     as well as `Babel`_\s `Translations` class are supported.
  49
  50 .. method:: jinja2.Environment.install_null_translations()
  51
  52     Install dummy gettext functions.  This is useful if you want to prepare
  53     the application for internationalization but don't want to implement the
  54     full internationalization system yet.
  55
  56 .. method:: jinja2.Environment.uninstall_gettext_translations()
  57
  58     Uninstall the translations again.
  59
  60 .. method:: jinja2.Environment.extract_translations(source)
  61
  62     Extract localizable strings from the given template node or source.
  63
  64     For every string found this function yields a ``(lineno, function,
  65     message)`` tuple, where:
  66
  67     * `lineno` is the number of the line on which the string was found,
  68     * `function` is the name of the `gettext` function used (if the
  69       string was extracted from embedded Python code), and
  70     *  `message` is the string itself (a `unicode` object, or a tuple
  71        of `unicode` objects for functions with multiple string arguments).
  72
  73     If `Babel`_ is installed :ref:`the babel integration <babel-integration>`
  74     can be used to extract strings for babel.
  75
  76 For a web application that is available in multiple languages but gives all
  77 the users the same language (for example a multilingual forum software
  78 installed for a French community) may load the translations once and add the
  79 translation methods to the environment at environment generation time::
  80
  81     translations = get_gettext_translations()
  82     env = Environment(extensions=['jinja2.ext.i18n'])
  83     env.install_gettext_translations(translations)
  84
  85 The `get_gettext_translations` function would return the translator for the
  86 current configuration.  (For example by using `gettext.find`)
  87
  88 The usage of the `i18n` extension for template designers is covered as part
  89 :ref:`of the template documentation <i18n-in-templates>`.
  90
  91 .. _gettext: http://docs.python.org/dev/library/gettext
  92 .. _Babel: http://babel.edgewall.org/
  93
  94
  95 do
  96 ~~
  97
  98 **Import name:** `jinja2.ext.do`
  99
 100 The do aka expression-statement extension adds a simple `do` tag to the
 101 template engine that works like a variable expression but ignores the
 102 return value.
 103
 104 .. _loopcontrols-extension:
 105
 106 loopcontrols
 107 ~~~~~~~~~~~~
 108
 109 **Import name:** `jinja2.ext.loopcontrols`
 110
 111 This extension adds support for `break` and `continue` in loops.  After
 112 enabling Jinja2 provides those two keywords which work exactly like in
 113 Python.
 114
 115
 116 .. _writing-extensions:
 117
 118 Writing Extensions
 119 ------------------
 120
 121 .. module:: jinja2.ext
 122
 123 By writing extensions you can add custom tags to Jinja2.  This is a non trival
 124 task and usually not needed as the default tags and expressions cover all
 125 common use cases.  The i18n extension is a good example of why extensions are
 126 useful, another one would be fragment caching.
 127
 128 When writing extensions you have to keep in mind that you are working with the
 129 Jinja2 template compiler which does not validate the node tree you are possing
 130 to it.  If the AST is malformed you will get all kinds of compiler or runtime
 131 errors that are horrible to debug.  Always make sure you are using the nodes
 132 you create correctly.  The API documentation below shows which nodes exist and
 133 how to use them.
 134
 135 Example Extension
 136 ~~~~~~~~~~~~~~~~~
 137
 138 The following example implements a `cache` tag for Jinja2 by using the
 139 `Werkzeug`_ caching contrib module:
 140
 141 .. literalinclude:: cache_extension.py
 142     :language: python
 143
 144 And here is how you use it in an environment::
 145
 146     from jinja2 import Environment
 147     from werkzeug.contrib.cache import SimpleCache
 148
 149     env = Environment(extensions=[FragmentCacheExtension])
 150     env.fragment_cache = SimpleCache()
 151
 152 .. _Werkzeug: http://werkzeug.pocoo.org/
 153
 154 Extension API
 155 ~~~~~~~~~~~~~
 156
 157 Extensions always have to extend the :class:`jinja2.ext.Extension` class:
 158
 159 .. autoclass:: Extension
 160     :members: parse, attr, call_method
 161
 162     .. attribute:: identifier
 163
 164         The identifier of the extension.  This is always the true import name
 165         of the extension class and must not be changed.
 166
 167     .. attribute:: tags
 168
 169         If the extension implements custom tags this is a set of tag names
 170         the extension is listening for.
 171
 172 Parser API
 173 ~~~~~~~~~~
 174
 175 The parser passed to :meth:`Extension.parse` provides ways to parse
 176 expressions of different types.  The following methods may be used by
 177 extensions:
 178
 179 .. autoclass:: jinja2.parser.Parser
 180     :members: parse_expression, parse_tuple, parse_assign_target,
 181               parse_statements, free_identifier, fail
 182
 183     .. attribute:: filename
 184
 185         The filename of the template the parser processes.  This is **not**
 186         the load name of the template.  For the load name see :attr:`name`.
 187         For templates that were not loaded form the file system this is
 188         `None`.
 189
 190     .. attribute:: name
 191
 192         The load name of the template.
 193
 194     .. attribute:: stream
 195
 196         The current :class:`~jinja2.lexer.TokenStream`
 197
 198 .. autoclass:: jinja2.lexer.TokenStream
 199    :members: push, look, eos, skip, next, next_if, skip_if, expect
 200
 201    .. attribute:: current
 202
 203         The current :class:`~jinja2.lexer.Token`.
 204
 205 .. autoclass:: jinja2.lexer.Token
 206     :members: test, test_any
 207
 208     .. attribute:: lineno
 209
 210         The line number of the token
 211
 212     .. attribute:: type
 213
 214         The type of the token.  This string is interned so you may compare
 215         it with arbitrary strings using the `is` operator.
 216
 217     .. attribute:: value
 218
 219         The value of the token.
 220
 221 AST
 222 ~~~
 223
 224 The AST (Abstract Syntax Tree) is used to represent a template after parsing.
 225 It's build of nodes that the compiler then converts into executable Python
 226 code objects.  Extensions that provide custom statements can return nodes to
 227 execute custom Python code.
 228
 229 The list below describes all nodes that are currently available.  The AST may
 230 change between Jinja2 versions but will stay backwards compatible.
 231
 232 For more information have a look at the repr of :meth:`jinja2.Environment.parse`.
 233
 234 .. module:: jinja2.nodes
 235
 236 .. jinjanodes::
 237
 238 .. autoexception:: Impossible