Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 1 | Integration |
| 2 | =========== |
| 3 | |
| 4 | Jinja2 provides some code for integration into other tools such as frameworks, |
| 5 | the `Babel`_ library or your favourite editor for fancy code highlighting. |
| 6 | This is a brief description of whats included. |
| 7 | |
Ron DuPlain | e5763b3 | 2012-03-13 14:53:15 -0700 | [diff] [blame^] | 8 | Files to help integration are available |
| 9 | `here. <https://github.com/mitsuhiko/jinja2/tree/master/ext>`_ |
| 10 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 11 | .. _babel-integration: |
| 12 | |
| 13 | Babel Integration |
| 14 | ----------------- |
| 15 | |
| 16 | Jinja provides support for extracting gettext messages from templates via a |
| 17 | `Babel`_ extractor entry point called `jinja2.ext.babel_extract`. The Babel |
| 18 | support is implemented as part of the :ref:`i18n-extension` extension. |
| 19 | |
| 20 | Gettext messages extracted from both `trans` tags and code expressions. |
| 21 | |
| 22 | To extract gettext messages from templates, the project needs a Jinja2 section |
| 23 | in its Babel extraction method `mapping file`_: |
| 24 | |
| 25 | .. sourcecode:: ini |
| 26 | |
Armin Ronacher | 2b22874 | 2008-05-18 20:29:32 +0200 | [diff] [blame] | 27 | [jinja2: **/templates/**.html] |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 28 | encoding = utf-8 |
| 29 | |
| 30 | The syntax related options of the :class:`Environment` are also available as |
| 31 | configuration values in the mapping file. For example to tell the extraction |
| 32 | that templates use ``%`` as `line_statement_prefix` you can use this code: |
| 33 | |
| 34 | .. sourcecode:: ini |
| 35 | |
Armin Ronacher | 2b22874 | 2008-05-18 20:29:32 +0200 | [diff] [blame] | 36 | [jinja2: **/templates/**.html] |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 37 | encoding = utf-8 |
| 38 | line_statement_prefix = % |
| 39 | |
| 40 | :ref:`jinja-extensions` may also be defined by passing a comma separated list |
| 41 | of import paths as `extensions` value. The i18n extension is added |
| 42 | automatically. |
| 43 | |
Armin Ronacher | 1161915 | 2011-12-15 11:50:27 +0100 | [diff] [blame] | 44 | .. versionchanged:: 2.7 |
| 45 | |
| 46 | Until 2.7 template syntax errors were always ignored. This was done |
| 47 | since many people are dropping non template html files into the |
| 48 | templates folder and it would randomly fail. The assumption was that |
| 49 | testsuites will catch syntax errors in templates anyways. If you don't |
| 50 | want that behavior you can add ``silent=false`` to the settings and |
| 51 | exceptions are propagated. |
| 52 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 53 | .. _mapping file: http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration |
| 54 | |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 55 | Pylons |
| 56 | ------ |
| 57 | |
Armin Ronacher | ba80826 | 2008-05-09 14:38:09 +0200 | [diff] [blame] | 58 | With `Pylons`_ 0.9.7 onwards it's incredible easy to integrate Jinja into a |
| 59 | Pylons powered application. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 60 | |
Armin Ronacher | ba80826 | 2008-05-09 14:38:09 +0200 | [diff] [blame] | 61 | The template engine is configured in `config/environment.py`. The configuration |
| 62 | for Jinja2 looks something like that:: |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 63 | |
Armin Ronacher | ba80826 | 2008-05-09 14:38:09 +0200 | [diff] [blame] | 64 | from jinja2 import Environment, PackageLoader |
| 65 | config['pylons.app_globals'].jinja_env = Environment( |
| 66 | loader=PackageLoader('yourapplication', 'templates') |
| 67 | ) |
| 68 | |
| 69 | After that you can render Jinja templates by using the `render_jinja` function |
| 70 | from the `pylons.templating` module. |
| 71 | |
| 72 | Additionally it's a good idea to set the Pylons' `c` object into strict mode. |
| 73 | Per default any attribute to not existing attributes on the `c` object return |
| 74 | an empty string and not an undefined object. To change this just use this |
| 75 | snippet and add it into your `config/environment.py`:: |
| 76 | |
| 77 | config['pylons.strict_c'] = True |
| 78 | |
| 79 | .. _Pylons: http://www.pylonshq.com/ |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 80 | |
| 81 | TextMate |
| 82 | -------- |
| 83 | |
Ron DuPlain | e5763b3 | 2012-03-13 14:53:15 -0700 | [diff] [blame^] | 84 | Inside the `ext` folder at the root of the Jinja2 project there is a bundle for |
| 85 | TextMate that supports syntax highlighting for Jinja1 and Jinja2 for text based |
| 86 | templates as well as HTML. It also contains a few often used snippets. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 87 | |
| 88 | Vim |
| 89 | --- |
| 90 | |
Armin Ronacher | decf7e3 | 2008-05-09 11:54:07 +0200 | [diff] [blame] | 91 | A syntax plugin for `Vim`_ exists in the Vim-scripts directory as well as the |
Ron DuPlain | e5763b3 | 2012-03-13 14:53:15 -0700 | [diff] [blame^] | 92 | `ext` folder at the root of the Jinja2 project. `The script |
| 93 | <http://www.vim.org/scripts/script.php?script_id=1856>`_ supports Jinja1 and |
| 94 | Jinja2. Once installed two file types are available `jinja` and `htmljinja`. |
| 95 | The first one for text based templates, the latter for HTML templates. |
Armin Ronacher | decf7e3 | 2008-05-09 11:54:07 +0200 | [diff] [blame] | 96 | |
| 97 | Copy the files into your `syntax` folder. |
Armin Ronacher | ed98cac | 2008-05-07 08:42:11 +0200 | [diff] [blame] | 98 | |
| 99 | .. _Babel: http://babel.edgewall.org/ |
Armin Ronacher | decf7e3 | 2008-05-09 11:54:07 +0200 | [diff] [blame] | 100 | .. _Vim: http://www.vim.org/ |