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 .. _mapping file: http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration
  42
  43 Pylons
  44 ------
  45
  46 With `Pylons`_ 0.9.7 onwards it's incredible easy to integrate Jinja into a
  47 Pylons powered application.
  48
  49 The template engine is configured in `config/environment.py`.  The configuration
  50 for Jinja2 looks something like that::
  51
  52     from jinja2 import Environment, PackageLoader
  53     config['pylons.app_globals'].jinja_env = Environment(
  54         loader=PackageLoader('yourapplication', 'templates')
  55     )
  56
  57 After that you can render Jinja templates by using the `render_jinja` function
  58 from the `pylons.templating` module.
  59
  60 Additionally it's a good idea to set the Pylons' `c` object into strict mode.
  61 Per default any attribute to not existing attributes on the `c` object return
  62 an empty string and not an undefined object.  To change this just use this
  63 snippet and add it into your `config/environment.py`::
  64
  65     config['pylons.strict_c'] = True
  66
  67 .. _Pylons: http://www.pylonshq.com/
  68
  69 TextMate
  70 --------
  71
  72 Inside the `ext` folder of Jinja2 there is a bundle for TextMate that supports
  73 syntax highlighting for Jinja1 and Jinja2 for text based templates as well as
  74 HTML.  It also contains a few often used snippets.
  75
  76 Vim
  77 ---
  78
  79 A syntax plugin for `Vim`_ exists in the Vim-scripts directory as well as the
  80 ext folder of Jinja2.  `The script <http://www.vim.org/scripts/script.php?script_id=1856>`_
  81 supports Jinja1 and Jinja2.  Once installed two file types are available `jinja`
  82 and `htmljinja`.  The first one for text based templates, the latter for HTML
  83 templates.
  84
  85 Copy the files into your `syntax` folder.
  86
  87 .. _Babel: http://babel.edgewall.org/
  88 .. _Vim: http://www.vim.org/