Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 1 | .. _jinja-extensions: |
| 2 | |
| 3 | Extensions |
| 4 | ========== |
| 5 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 6 | Jinja2 supports extensions that can add extra filters, tests, globals or even |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 7 | extend the parser. The main motivation of extensions is to move often used |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 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 |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 17 | `extensions` parameter of the :class:`Environment` constructor. The following |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 18 | example creates a Jinja2 environment with the i18n extension loaded:: |
| 19 | |
Armin Ronacher | 09c002e | 2008-05-10 22:21:30 +0200 | [diff] [blame] | 20 | jinja_env = Environment(extensions=['jinja2.ext.i18n']) |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 21 | |
| 22 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 23 | .. _i18n-extension: |
| 24 | |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 25 | i18n Extension |
| 26 | -------------- |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 27 | |
Armin Ronacher | 5d2733f | 2008-05-15 23:26:52 +0200 | [diff] [blame] | 28 | **Import name:** `jinja2.ext.i18n` |
| 29 | |
Chad Whitacre | e53659d | 2015-02-05 14:53:19 -0500 | [diff] [blame] | 30 | The i18n extension can be used in combination with `gettext`_ or `babel`_. If |
| 31 | the i18n extension is enabled Jinja2 provides a `trans` statement that marks |
| 32 | the wrapped string as translatable and calls `gettext`. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 33 | |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 34 | After enabling, dummy `_` function that forwards calls to `gettext` is added |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 35 | to the environment globals. An internationalized application then has to |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 36 | provide a `gettext` function and optionally an `ngettext` function into the |
| 37 | namespace, either globally or for each rendering. |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 38 | |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 39 | Environment Methods |
| 40 | ~~~~~~~~~~~~~~~~~~~ |
| 41 | |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 42 | After enabling the extension, the environment provides the following |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 43 | additional methods: |
| 44 | |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 45 | .. method:: jinja2.Environment.install_gettext_translations(translations, newstyle=False) |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 46 | |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 47 | Installs a translation globally for that environment. The translations |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 48 | object provided must implement at least `ugettext` and `ungettext`. |
| 49 | The `gettext.NullTranslations` and `gettext.GNUTranslations` classes |
| 50 | as well as `Babel`_\s `Translations` class are supported. |
| 51 | |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 52 | .. versionchanged:: 2.5 newstyle gettext added |
| 53 | |
| 54 | .. method:: jinja2.Environment.install_null_translations(newstyle=False) |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 55 | |
| 56 | Install dummy gettext functions. This is useful if you want to prepare |
| 57 | the application for internationalization but don't want to implement the |
| 58 | full internationalization system yet. |
| 59 | |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 60 | .. versionchanged:: 2.5 newstyle gettext added |
| 61 | |
| 62 | .. method:: jinja2.Environment.install_gettext_callables(gettext, ngettext, newstyle=False) |
| 63 | |
| 64 | Installs the given `gettext` and `ngettext` callables into the |
| 65 | environment as globals. They are supposed to behave exactly like the |
| 66 | standard library's :func:`gettext.ugettext` and |
| 67 | :func:`gettext.ungettext` functions. |
| 68 | |
| 69 | If `newstyle` is activated, the callables are wrapped to work like |
| 70 | newstyle callables. See :ref:`newstyle-gettext` for more information. |
| 71 | |
| 72 | .. versionadded:: 2.5 |
| 73 | |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 74 | .. method:: jinja2.Environment.uninstall_gettext_translations() |
| 75 | |
| 76 | Uninstall the translations again. |
| 77 | |
| 78 | .. method:: jinja2.Environment.extract_translations(source) |
| 79 | |
| 80 | Extract localizable strings from the given template node or source. |
| 81 | |
| 82 | For every string found this function yields a ``(lineno, function, |
| 83 | message)`` tuple, where: |
| 84 | |
| 85 | * `lineno` is the number of the line on which the string was found, |
| 86 | * `function` is the name of the `gettext` function used (if the |
| 87 | string was extracted from embedded Python code), and |
| 88 | * `message` is the string itself (a `unicode` object, or a tuple |
| 89 | of `unicode` objects for functions with multiple string arguments). |
| 90 | |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 91 | If `Babel`_ is installed, :ref:`the babel integration <babel-integration>` |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 92 | can be used to extract strings for babel. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 93 | |
| 94 | For a web application that is available in multiple languages but gives all |
| 95 | the users the same language (for example a multilingual forum software |
| 96 | installed for a French community) may load the translations once and add the |
| 97 | translation methods to the environment at environment generation time:: |
| 98 | |
| 99 | translations = get_gettext_translations() |
Armin Ronacher | 2b22874 | 2008-05-18 20:29:32 +0200 | [diff] [blame] | 100 | env = Environment(extensions=['jinja2.ext.i18n']) |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 101 | env.install_gettext_translations(translations) |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 102 | |
| 103 | The `get_gettext_translations` function would return the translator for the |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 104 | current configuration. (For example by using `gettext.find`) |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 105 | |
| 106 | The usage of the `i18n` extension for template designers is covered as part |
| 107 | :ref:`of the template documentation <i18n-in-templates>`. |
| 108 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 109 | .. _gettext: http://docs.python.org/dev/library/gettext |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 110 | .. _Babel: http://babel.edgewall.org/ |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 111 | |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 112 | .. _newstyle-gettext: |
| 113 | |
| 114 | Newstyle Gettext |
| 115 | ~~~~~~~~~~~~~~~~ |
| 116 | |
| 117 | .. versionadded:: 2.5 |
| 118 | |
| 119 | Starting with version 2.5 you can use newstyle gettext calls. These are |
| 120 | inspired by trac's internal gettext functions and are fully supported by |
| 121 | the babel extraction tool. They might not work as expected by other |
| 122 | extraction tools in case you are not using Babel's. |
| 123 | |
| 124 | What's the big difference between standard and newstyle gettext calls? In |
| 125 | general they are less to type and less error prone. Also if they are used |
| 126 | in an autoescaping environment they better support automatic escaping. |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 127 | Here are some common differences between old and new calls: |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 128 | |
| 129 | standard gettext: |
| 130 | |
| 131 | .. sourcecode:: html+jinja |
| 132 | |
| 133 | {{ gettext('Hello World!') }} |
| 134 | {{ gettext('Hello %(name)s!')|format(name='World') }} |
| 135 | {{ ngettext('%(num)d apple', '%(num)d apples', apples|count)|format( |
| 136 | num=apples|count |
| 137 | )}} |
| 138 | |
| 139 | newstyle gettext looks like this instead: |
| 140 | |
| 141 | .. sourcecode:: html+jinja |
| 142 | |
| 143 | {{ gettext('Hello World!') }} |
| 144 | {{ gettext('Hello %(name)s!', name='World') }} |
| 145 | {{ ngettext('%(num)d apple', '%(num)d apples', apples|count) }} |
| 146 | |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 147 | The advantages of newstyle gettext are that you have less to type and that |
Armin Ronacher | ffaa2e7 | 2010-05-29 20:57:16 +0200 | [diff] [blame] | 148 | named placeholders become mandatory. The latter sounds like a |
| 149 | disadvantage but solves a lot of troubles translators are often facing |
| 150 | when they are unable to switch the positions of two placeholder. With |
| 151 | newstyle gettext, all format strings look the same. |
| 152 | |
| 153 | Furthermore with newstyle gettext, string formatting is also used if no |
| 154 | placeholders are used which makes all strings behave exactly the same. |
| 155 | Last but not least are newstyle gettext calls able to properly mark |
| 156 | strings for autoescaping which solves lots of escaping related issues many |
| 157 | templates are experiencing over time when using autoescaping. |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 158 | |
Armin Ronacher | 6df604e | 2008-05-23 22:18:38 +0200 | [diff] [blame] | 159 | Expression Statement |
| 160 | -------------------- |
Armin Ronacher | 5d2733f | 2008-05-15 23:26:52 +0200 | [diff] [blame] | 161 | |
| 162 | **Import name:** `jinja2.ext.do` |
| 163 | |
Armin Ronacher | 6df604e | 2008-05-23 22:18:38 +0200 | [diff] [blame] | 164 | The "do" aka expression-statement extension adds a simple `do` tag to the |
Armin Ronacher | 5d2733f | 2008-05-15 23:26:52 +0200 | [diff] [blame] | 165 | template engine that works like a variable expression but ignores the |
| 166 | return value. |
| 167 | |
Armin Ronacher | 3da9031 | 2008-05-23 16:37:28 +0200 | [diff] [blame] | 168 | .. _loopcontrols-extension: |
| 169 | |
Armin Ronacher | 6df604e | 2008-05-23 22:18:38 +0200 | [diff] [blame] | 170 | Loop Controls |
| 171 | ------------- |
Armin Ronacher | 3da9031 | 2008-05-23 16:37:28 +0200 | [diff] [blame] | 172 | |
| 173 | **Import name:** `jinja2.ext.loopcontrols` |
| 174 | |
| 175 | This extension adds support for `break` and `continue` in loops. After |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 176 | enabling, Jinja2 provides those two keywords which work exactly like in |
Armin Ronacher | 3da9031 | 2008-05-23 16:37:28 +0200 | [diff] [blame] | 177 | Python. |
| 178 | |
Armin Ronacher | 9b4cc9f | 2010-02-07 03:55:15 +0100 | [diff] [blame] | 179 | .. _with-extension: |
| 180 | |
| 181 | With Statement |
| 182 | -------------- |
| 183 | |
| 184 | **Import name:** `jinja2.ext.with_` |
| 185 | |
| 186 | .. versionadded:: 2.3 |
| 187 | |
| 188 | This extension adds support for the with keyword. Using this keyword it |
| 189 | is possible to enforce a nested scope in a template. Variables can be |
| 190 | declared directly in the opening block of the with statement or using a |
| 191 | standard `set` statement directly within. |
| 192 | |
Armin Ronacher | fe150f3 | 2010-03-15 02:42:41 +0100 | [diff] [blame] | 193 | .. _autoescape-extension: |
| 194 | |
| 195 | Autoescape Extension |
| 196 | -------------------- |
| 197 | |
| 198 | **Import name:** `jinja2.ext.autoescape` |
| 199 | |
| 200 | .. versionadded:: 2.4 |
| 201 | |
| 202 | The autoescape extension allows you to toggle the autoescape feature from |
| 203 | within the template. If the environment's :attr:`~Environment.autoescape` |
| 204 | setting is set to `False` it can be activated, if it's `True` it can be |
Armin Ronacher | fd72972 | 2010-08-16 12:13:04 +0200 | [diff] [blame] | 205 | deactivated. The setting overriding is scoped. |
Armin Ronacher | fe150f3 | 2010-03-15 02:42:41 +0100 | [diff] [blame] | 206 | |
Armin Ronacher | 5d2733f | 2008-05-15 23:26:52 +0200 | [diff] [blame] | 207 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 208 | .. _writing-extensions: |
| 209 | |
| 210 | Writing Extensions |
| 211 | ------------------ |
| 212 | |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 213 | .. module:: jinja2.ext |
| 214 | |
Jakub Wilk | 3fc008b | 2013-05-25 23:37:34 +0200 | [diff] [blame] | 215 | By writing extensions you can add custom tags to Jinja2. This is a non-trivial |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 216 | task and usually not needed as the default tags and expressions cover all |
| 217 | common use cases. The i18n extension is a good example of why extensions are |
Lucian Ursu | 07497dc | 2013-11-29 14:16:06 +0200 | [diff] [blame] | 218 | useful. Another one would be fragment caching. |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 219 | |
Armin Ronacher | b9e7875 | 2008-05-10 23:36:28 +0200 | [diff] [blame] | 220 | When writing extensions you have to keep in mind that you are working with the |
Oliver Beattie | 6e97b06 | 2011-12-15 09:47:34 +0000 | [diff] [blame] | 221 | Jinja2 template compiler which does not validate the node tree you are passing |
Armin Ronacher | b9e7875 | 2008-05-10 23:36:28 +0200 | [diff] [blame] | 222 | to it. If the AST is malformed you will get all kinds of compiler or runtime |
| 223 | errors that are horrible to debug. Always make sure you are using the nodes |
| 224 | you create correctly. The API documentation below shows which nodes exist and |
| 225 | how to use them. |
| 226 | |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 227 | Example Extension |
| 228 | ~~~~~~~~~~~~~~~~~ |
| 229 | |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 230 | The following example implements a `cache` tag for Jinja2 by using the |
| 231 | `Werkzeug`_ caching contrib module: |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 232 | |
| 233 | .. literalinclude:: cache_extension.py |
| 234 | :language: python |
| 235 | |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 236 | And here is how you use it in an environment:: |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 237 | |
| 238 | from jinja2 import Environment |
| 239 | from werkzeug.contrib.cache import SimpleCache |
| 240 | |
Armin Ronacher | 762079c | 2008-05-08 23:57:56 +0200 | [diff] [blame] | 241 | env = Environment(extensions=[FragmentCacheExtension]) |
| 242 | env.fragment_cache = SimpleCache() |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 243 | |
Armin Ronacher | 6df604e | 2008-05-23 22:18:38 +0200 | [diff] [blame] | 244 | Inside the template it's then possible to mark blocks as cacheable. The |
| 245 | following example caches a sidebar for 300 seconds: |
| 246 | |
| 247 | .. sourcecode:: html+jinja |
| 248 | |
| 249 | {% cache 'sidebar', 300 %} |
| 250 | <div class="sidebar"> |
| 251 | ... |
| 252 | </div> |
| 253 | {% endcache %} |
| 254 | |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 255 | .. _Werkzeug: http://werkzeug.pocoo.org/ |
| 256 | |
| 257 | Extension API |
| 258 | ~~~~~~~~~~~~~ |
| 259 | |
| 260 | Extensions always have to extend the :class:`jinja2.ext.Extension` class: |
| 261 | |
| 262 | .. autoclass:: Extension |
Armin Ronacher | 9ad96e7 | 2008-06-13 22:44:01 +0200 | [diff] [blame] | 263 | :members: preprocess, filter_stream, parse, attr, call_method |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 264 | |
| 265 | .. attribute:: identifier |
| 266 | |
| 267 | The identifier of the extension. This is always the true import name |
| 268 | of the extension class and must not be changed. |
| 269 | |
| 270 | .. attribute:: tags |
| 271 | |
| 272 | If the extension implements custom tags this is a set of tag names |
| 273 | the extension is listening for. |
| 274 | |
| 275 | Parser API |
| 276 | ~~~~~~~~~~ |
| 277 | |
| 278 | The parser passed to :meth:`Extension.parse` provides ways to parse |
| 279 | expressions of different types. The following methods may be used by |
| 280 | extensions: |
| 281 | |
| 282 | .. autoclass:: jinja2.parser.Parser |
Armin Ronacher | 09c002e | 2008-05-10 22:21:30 +0200 | [diff] [blame] | 283 | :members: parse_expression, parse_tuple, parse_assign_target, |
Armin Ronacher | 7f15ef8 | 2008-05-16 09:11:39 +0200 | [diff] [blame] | 284 | parse_statements, free_identifier, fail |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 285 | |
| 286 | .. attribute:: filename |
| 287 | |
| 288 | The filename of the template the parser processes. This is **not** |
Armin Ronacher | 67fdddf | 2008-05-16 09:27:51 +0200 | [diff] [blame] | 289 | the load name of the template. For the load name see :attr:`name`. |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 290 | For templates that were not loaded form the file system this is |
| 291 | `None`. |
| 292 | |
Armin Ronacher | 67fdddf | 2008-05-16 09:27:51 +0200 | [diff] [blame] | 293 | .. attribute:: name |
| 294 | |
| 295 | The load name of the template. |
| 296 | |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 297 | .. attribute:: stream |
| 298 | |
| 299 | The current :class:`~jinja2.lexer.TokenStream` |
| 300 | |
| 301 | .. autoclass:: jinja2.lexer.TokenStream |
Armin Ronacher | fdf9530 | 2008-05-11 22:20:51 +0200 | [diff] [blame] | 302 | :members: push, look, eos, skip, next, next_if, skip_if, expect |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 303 | |
| 304 | .. attribute:: current |
| 305 | |
| 306 | The current :class:`~jinja2.lexer.Token`. |
| 307 | |
| 308 | .. autoclass:: jinja2.lexer.Token |
| 309 | :members: test, test_any |
| 310 | |
| 311 | .. attribute:: lineno |
| 312 | |
| 313 | The line number of the token |
| 314 | |
| 315 | .. attribute:: type |
| 316 | |
| 317 | The type of the token. This string is interned so you may compare |
| 318 | it with arbitrary strings using the `is` operator. |
| 319 | |
| 320 | .. attribute:: value |
| 321 | |
| 322 | The value of the token. |
| 323 | |
Armin Ronacher | d02fc7d | 2008-06-14 14:19:47 +0200 | [diff] [blame] | 324 | There is also a utility function in the lexer module that can count newline |
| 325 | characters in strings: |
| 326 | |
| 327 | .. autofunction:: jinja2.lexer.count_newlines |
| 328 | |
Armin Ronacher | 023b5e9 | 2008-05-08 11:03:10 +0200 | [diff] [blame] | 329 | AST |
| 330 | ~~~ |
| 331 | |
| 332 | The AST (Abstract Syntax Tree) is used to represent a template after parsing. |
| 333 | It's build of nodes that the compiler then converts into executable Python |
| 334 | code objects. Extensions that provide custom statements can return nodes to |
| 335 | execute custom Python code. |
| 336 | |
| 337 | The list below describes all nodes that are currently available. The AST may |
| 338 | change between Jinja2 versions but will stay backwards compatible. |
| 339 | |
| 340 | For more information have a look at the repr of :meth:`jinja2.Environment.parse`. |
| 341 | |
| 342 | .. module:: jinja2.nodes |
| 343 | |
| 344 | .. jinjanodes:: |
| 345 | |
| 346 | .. autoexception:: Impossible |