{{{#!div class="important" style="padding: 0em 2em; margin: 2em 0"
** Warning **
The following documentation corresponds to an experimental branch ([[Proposals/Jinja]] / [log:cboos.git@jinja2]).
}}}
[[PageOutline(2-3)]]
= Porting Templates from Genshi to Jinja2
The following documentation is primarily targeted at plugin developers who wish to adapt their Genshi templates to the Jinja2 template engine that will be used in Trac 1.4.
For migrating your own templates, a good way to start is to learn from examples.
Compare the 'j...' Jinja templates found in source:cboos.git/trac/templates@jinja2 with their corresponding Genshi ones.
Note that Genshi will **not** be supported concurrently with Jinja2.
If for some reason you're stuck to having to support Genshi templates, you'll have to stick to Trac 1.2.x. But you really should make the transition effort as Jinja2 templates are 5-10x faster than their Genshi equivalent, for a 1/5th of the cost in memory usage.
== Changes in the template syntax
Most of the time, the porting is a straightforward operation.
=== expand a variable
- Genshi [[xml($the_variable)]]
- Jinja2 [[xml(${the_variable})]]
Tip:
{{{#!shell
sed -ie 's,\$\([a-z_][a-z._]*\),${\1},g' template.html
}}}
=== expand a simple computation
- Genshi [[xml(${the_variable + 1})]]
- Jinja2 [[xml(${the_variable + 1})]]
However, Jinja2 expressions are only //similar// to Python expressions, there are a few differences and limitations, see [http://jinja.pocoo.org/docs/dev/templates/#expressions expressions] doc.
See also [#setcomplexvariabels set complex variables] below for more involved examples.
=== include another template
- Genshi [[xml(
Otherwise, please ${create_ticket(tracker)} a new bug report describing the problem and explain how to reproduce it.
}}} - Jinja2: {{{#!html+jinja# trans create = create_ticket(tracker) Otherwise, please ${create} a new bug report describing the problem and explain how to reproduce it. # endtrans
}}} Note that only direct variable expansions are supported in `trans` blocks, nothing more complex. So one way to deal with complex translatable content is to factor out the complex parts in variable blocks. See [http://jinja.pocoo.org/docs/dev/templates/#block-assignments block assignments] doc. - Genshi: {{{#!html+genshiThere was an internal error in Trac. It is recommended that you notify your local Trac administrator with the information needed to reproduce the issue.
}}} - Jinja2: {{{#!html+jinja# set trac_admin = _("Trac administrator") # set project_admin # if project.admin: ${trac_admin} # else: ${trac_admin} # endif # endset # trans project_admin = project_admin|safe There was an internal error in Trac. It is recommended that you notify your local ${project_admin} with the information needed to reproduce the issue. # endtrans
}}} (the need for the `|safe` filter in the above might go away once the following issue //[https://github.com/mitsuhiko/jinja2/issues/490 Should set blocks be safe by default]// gets fixed) == Examples Let's first take a simple full-contained example from the Trac source, the simple index.html / jindex.html templates. - Genshi [source:sandbox/genshi/templates/index.html@3728 index.html]: {{{#!html+genshi