docs/integration.rst

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