Changes between Version 28 and Version 29 of TracDev/PortingFromGenshiToJinja
- Timestamp:
- Jan 6, 2017, 5:03:25 PM (7 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/PortingFromGenshiToJinja
v28 v29 4 4 The following documentation corresponds to the [Proposals/Jinja Jinja] development proposal; it will be in Trac 1.3.x if all goes well \\ 5 5 (Git branch: [log:cboos.git@jinja2] - [https://github.com/cboos/trac.git github mirror]). 6 7 Track the integration progress in #12639. 6 8 }}} 7 9 … … 14 16 Compare the 'j...' Jinja templates found in source:cboos.git/trac/templates@jinja2 with their corresponding Genshi ones. 15 17 16 In the first part of this document, we try to cover all the Genshi features used by Trac and present their Jinja2 equivalent. Whenever possible, we tried to minimize these differences by customizing the Jinja2 syntax. For example, we use `${...}` for variable expansion, like Genshi does, instead of `{{...}}`. Another aspect of our usage convention is that we favor [#ifthenelse line statements] over `{% ... %}`. So even someone familiar with the "default" Jinja2 syntax should glance through this document to see how "we" use Jinja2 .18 In the first part of this document, we try to cover all the Genshi features used by Trac and present their Jinja2 equivalent. Whenever possible, we tried to minimize these differences by customizing the Jinja2 syntax. For example, we use `${...}` for variable expansion, like Genshi does, instead of `{{...}}`. Another aspect of our usage convention is that we favor [#ifthenelse line statements] over `{% ... %}`. So even someone familiar with the "default" Jinja2 syntax should glance through this document to see how "we" use Jinja2, as summarized in the table below. 17 19 18 20 The last part of the document describes the Python code changes, focusing notably on how to replace the deprecated `ITemplateStreamFilter` interface. … … 20 22 Note that Genshi will be supported concurrently with Jinja2 only for a short while, including the deprecated `ITemplateStreamFilter` interface, but probably only during the 1.3.x development period, and at most for the 1.4-stable period. If for some reason you're stuck to having to support Genshi templates, you'll have to stick to Trac 1.2.x or 1.3.x. But you really should make the transition effort as Jinja2 templates are 5-10x faster than their Genshi equivalent, for only a 1/5th of the cost in memory usage. 21 23 22 24 == The Jinja2 syntax 25 26 The Jinja2 template engine is quite flexible and its syntax can be customized to some extent. We took this opportunity to make it as close as possible to the Genshi template syntax, in particular for the variable expansion. 27 28 We use the following configuration: 29 || key || value || example / explanation 30 || extensions || jinja2.ext.with_ jinja2.ext.i18n || `with` directive can be used ([#with more]) 31 || block_start_string || {% || \ 32 {{{#!td rowspan=2 33 `{% if cond %} value {% endif %}` possible (but discouraged) 34 }}} 35 |-- 36 || block_end_string || %} || 37 || variable_start_string || ${ || \ 38 {{{#!td rowspan=2 39 `${the_variable}` (but not `$the_variable`) 40 ([#expandavariable more]) 41 }}} 42 |-- 43 || variable_end_string || } || 44 || line_statement_prefix || # || \ 45 {{{#!td 46 {{{ 47 # if cond: 48 value 49 # endif 50 }}} 51 (preferred form) ([#if more]) 52 }}} 53 |-- 54 || line_comment_prefix || ## || `## comments are good` 55 || trim_blocks || yes || whitespace removal after a block 56 || lstrip_blocks || yes || whitespace removal before a block 57 || newstyle_gettext || yes || i.e. like the Trac `gettext` 23 58 24 59 == Changes in the HTML … … 95 130 96 131 It is also possible to pass "parameters" to included templates. 97 Those are not actually declared parameters, simply variables expected to be available in the template that can be set for the scope of one specific include. This works exactly like in Genshi, with a withstatement:132 Those are not actually declared parameters, simply variables expected to be available in the template that can be set for the scope of one specific include. This works exactly like in Genshi, with a `with` statement: 98 133 99 134 - Genshi … … 165 200 If you really have to, you can also use the block style: 166 201 {{{#!html+jinja 167 { % if flag %}<b>OK</b>{% else %}<i>!!!</i>{% endif %}202 {{ if flag }}<b>OK</b>{{ else }}<i>!!!</i>{{ endif }} 168 203 }}} 169 204 However this goes against readability and processing via the [./Checker jinjachecker] tool, so we really advise that you stick to the use of //[http://jinja.pocoo.org/docs/dev/templates/#line-statements line statements]//.
