Context Navigation

Changes between Version 41 and Version 42 of TracDev/PortingFromGenshiToJinja

Timestamp:: Jan 28, 2017, 12:38:17 AM (7 years ago)
Author:: Christian Boos
Comment:: major restructuring of the page, start with examples, continue with the code changes, finish with the detailed guide of the differences in the template syntax

Legend:

: Unmodified
: Added
: Removed
: Modified

TracDev/PortingFromGenshiToJinja

-              v41
+              v42
 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 [milestone:1.4].
+For migrating your own templates, a good way to start is to learn from examples.
+Compare the  [source:cboos.git/trac/templates@jinja2-trunk-r15379 Jinja2 trac/templates] with their [source:trunk/trac/templates Genshi counterpart].
+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.
+The last part of the document describes the Python code changes, focusing notably on how to replace the deprecated `ITemplateStreamFilter` interface.
+Note that Genshi will be supported concurrently with Jinja2 only for a short while, for the 1.3.x development period and 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.1. 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.
+== The Jinja2 syntax
+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.
+We use the following configuration:
+|| key || value || example / explanation
+|| extensions ||  jinja2.ext.with_  jinja2.ext.i18n  || `with` directive can be used ([#with more])
+|| block_start_string ||  {%  || \
+{{{#!td rowspan=2
+`{% if cond %} value {% endif %}` possible (but discouraged)
+}}}
+|--
+|| block_end_string ||  %}  ||
+|| variable_start_string ||  ${  || \
+{{{#!td rowspan=2
+`${the_variable}` (but not `$the_variable`)
+([#expandavariable more])
+}}}
+|--
+|| variable_end_string ||  }  ||
+|| line_statement_prefix ||  #  || \
+{{{#!td
+{{{
+# if cond:
+value
+# endif
+}}}
+(preferred form) ([#if more])
+}}}
+|--
+|| line_comment_prefix ||  ##  || `## comments are good`
+|| trim_blocks ||  yes  || whitespace removal after a block
+|| lstrip_blocks ||  yes  || whitespace removal before a block
+|| newstyle_gettext ||  yes  || i.e. like the Trac `gettext`
+== Changes in the HTML
+We took the opportunity to switch to HTML5 while performing this template overhaul.
+You should probably do the same.
+This usually won't change anything for your templates, except for a few details.
+The doctype and the <html> element should be changed from Genshi's:
+{{{#!html+genshi
+<!DOCTYPE html
+    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"
+      xmlns:py="http://genshi.edgewall.org/"
+      xmlns:i18n="http://genshi.edgewall.org/i18n"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+}}}
+to the somewhat simpler:
+{{{#!xml
+<!DOCTYPE html>
+<html>
+}}}
+Special care should be taken when dealing with //void elements//.
+In XHTML, it's fine to write:
+{{{#!xml
+<div id="description"/>
+}}}
+However, when going to HTML5, you should use instead:
+{{{#!xml
+<div id="description"></div>
+}}}
+The valid [https://www.w3.org/TR/html-markup/syntax.html#void-elements void elements] in HTML5 are limited to the following list:
+ - area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track, wbr
+== Changes in the template syntax
+Most of the time, the porting is a straightforward operation.
+=== expand a variable
+ - Genshi [[html+genshi(<b>$the_variable</b>)]]
+ - Jinja2 [[html+jinja(<b>${the_variable}</b>)]]
+Note that Jinja2 doesn't support the `$the_variable` style, the curly braces are mandatory.
+Tip:
+{{{#!shell
+sed -i -e 's,\$\([a-z_][a-z._]*\),${\1},g' template.html
+}}}
+=== expand a simple computation
+ - Genshi [[html+genshi(<b>${the_variable + 1}</b>)]]
+ - Jinja2 [[html+jinja(<b>${the_variable + 1}</b>)]]
+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 [#set set complex variables] below for more involved examples.
+Another customization we made to Jinja2 is to avoid having a Python `None` value be expanded to the `"None"` string. Instead, we make it produce an empty string, like Genshi did.
+=== include another template   #include
+ - Genshi [[xml(<xi:include href="the_file.html"><xi:fallback/></xi:include>)]]
+ - Jinja2 [[xml(# include "the_file.html" ignore missing)]]
+See [http://jinja.pocoo.org/docs/dev/templates/#include include] doc. Note that the `ignore missing` part is mandatory no templates are given to the `include` directive. This includes the following situation:
+{{{#!html+jinja
+# include "sometemplate.html" if false
+}}}
+This alone would raise an error. The correct thing to write is:
+{{{#!html+jinja
+# include "sometemplate.html" if false ignore missing
+}}}
+It is also possible to pass "parameters" to included templates.
+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:
+ - Genshi
+   {{{#!html+genshi
+        <xi:include href="ticket_box.html" py:with="can_append = False; preview_mode = False"/>
+   }}}
+ - Jinja
+   {{{#!html+jinja
+      # with
+      #   set can_append = false
+      #   set preview_mode = false
+      #   include "ticket_box.html"
+      # endwith
+   }}}
+See [http://jinja.pocoo.org/docs/dev/extensions/#with-statement with] doc.
+In passing, note how the boolean constants slightly differ from Python, `False` becomes `false`, `True` becomes `true` and `None` is `none`.
+Caveat: contrary to the Genshi way, one shouldn't include the `"layout.html"` template in order to inherit the default page layout. There's a big difference in the way template "inheritance" works between Genshi and Jinja2, see HtmlTemplates#Jinjaarchitecture for all the details.
+Despite these differences, we kept the same spirit and there's actually also a `"layout.html"` template that you can "inherit" from (as well as a `"theme.html"` template that the layout inherits in turn). But instead of "including" it in your template, you "extend" it:
+{{{#!html+jinja
+# extends "layout.html"
+}}}
+But this is not the place to go further in the details about how extending works, refer to the [http://jinja.pocoo.org/docs/dev/templates/#extends extends] documentation and to the link above for how this applies to Trac.
+=== simple if...then (no else)   #if
+ - Genshi [[xml(<py:if test="flag"><b>OK</b></py:if>)]] or simply: [[xml(<b py:if="flag">OK</b>)]]
+ - Jinja2
+   {{{#!html+jinja
+   # if flag:
+   <b>OK</b>
+   # endif
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#if if] doc.
+=== if...then...else
+ - Genshi
+   {{{#!html+genshi
+<py:choose test="flag">
+  <py:when test="True">
+    <b>OK</b>
+  </py:when>
+  <py:otherwise>
+   <i>!!!</i>
+  </py:otherwise>
+</py:choose>
+   }}}
+   or simply:
+   {{{#!html+genshi
+<py:choose>
+ <b py:when="flag">OK</b>
+ <i py:otherwise="">!!!</i>
+</py:choose>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+ # if flag:
+ <b>OK</b>
+ # else:
+ <i>!!!</i>
+ # endif
+   }}}
+If you really have to, you can also use the block style:
+{{{#!html+jinja
+{{ if flag }}<b>OK</b>{{ else }}<i>!!!</i>{{ endif }}
+}}}
+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]//.
+=== iterate over a collection   #for
+ - Genshi
+   {{{#!html+genshi
+<ul>
+  <py:for each="element in list">
+    <li>$element</li>
+  </py:for>
+</ul>
+   }}}
+   or simply:
+   {{{#!html+genshi
+<ul>
+  <li py:for="element in list">$element</li>
+</ul>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+<ul>
+  # for element in list:
+  <li>${element}</li>
+  # endfor
+</ul>
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#for for] doc.
+==== No need for `enumerate`
+ - Genshi:
+{{{#!html+genshi
+          <tr py:for="idx,option in enumerate(section.options)"
+              class="${'modified' if option.modified else None}">
+            <th py:if="idx == 0" class="section"
+                rowspan="${len(section.options)}">${section.name}</th>
+}}}
+ - Jinja2:
+{{{#!html+jinja
+          #   for option in section.options:
+          <tr ${{'class': 'modified' if option.modified}|htmlattr}>
+            #   if loop.first:
+            <th class="section"
+                rowspan="${len(section.options)}">${section.name}</th>
+}}}
+All common uses (and more) for such an `idx` variable are addressed by the special `loop` variable.
+See [http://jinja.pocoo.org/docs/dev/templates/#for loop] doc.
+=== define a macro   #macro
+ - Genshi
+   {{{#!html+genshi
+<py:def function="entry(key, val='--')">
+ <dt>$key</dt><dd>$val</dd>
+</py:def>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+ # macro entry(key, val='--')
+ <dt>${key}</dt><dd>${val}</dd>
+ # endmacro
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#macros macros] doc.
+=== set a variable
+ - Genshi
+   {{{#!html+genshi
+<py:with vars="count = len(collection)">
+We have ${count &gt; 10 and 'too much' or count} elements.
+</py:with>
+   }}}
+   Note that we had to use `&gt;` in Genshi, we can't use `>` directly.
+ - Jinja2
+   {{{#!html+jinja
+# set count = len(collection)
+We have ${'too much' if count is greaterthan(10) else count} elements.
+   }}}
+   Note that we avoid using `>` in Jinja2 expressions as well, but simply to avoid that XML/HTML text editors get confused. We added a few custom tests for that (`greaterthan`, `greaterthanorequal`, `lessthan`, `lessthanorequal`).
+See [http://jinja.pocoo.org/docs/dev/templates/#tests tests] doc.
+=== set several variables in a scope #with
+ - Genshi
+   {{{#!html+genshi
+<html py:with="is_query = report.sql.startswith('query:');
+               new_report = action == 'new' and not is_query;
+               new_query = action == 'new' and is_query">
+  ...
+</html>
+   }}}
+   The variables are set for the scope of the element in which they are set (here <html>,
+   so the whole document)
+ - Jinja2
+   {{{#!html+jinja
+    #   with
+    #     set is_query = report.sql.startswith('query:')
+    #     set new_report = action == 'new' and not is_query
+    ...
+    #   endwith
+   }}}
+But actually you will only use `with` in specific situations, like for wrapping an include directive (see [#include]). If you're already within a `for`, a `block` or a `macro`, the scope of the assignment is already limited to that of this directive.
+See [http://jinja.pocoo.org/docs/dev/templates/#assignments set] and [http://jinja.pocoo.org/docs/dev/templates/#with-statement with] docs.
+In addition, `with` can also be used to better control how the successive `set` on a given variable are being applied (see for example [1e25c852/cboos.git] and [cc1b959e/cboos.git]).
+Finally be careful when using `with`: don't wrap a `block` directive within a `with`. If you want to set a global scope for the document (like in our <html> example above), it's tempting to use a single `with` statement, for clarity. But that would wrap all blocks defined in the template and strange results would ensue.
+=== set HTML attributes   #htmlattr
+In Genshi, an attribute with a `None` value wouldn't be output. However, Jinja2 doesn't know what an attribute is (or anything else about HTML, XML for that matter), so we have to use a special filter, `htmlattr`, to reproduce this behavior:
+ - Genshi:
+{{{#!html+genshi
+          <tr class="${'disabled' if all(not component.enabled for module in plugin.modules.itervalues()
+                                         for component in module.components.itervalues()) else None}">
+}}}
+ - Jinja2:
+{{{#!html+jinja
+          #   set components = plugin.modules|map(attribute='components')|flatten
+          <tr${{'class': 'disabled' if not components|selectattr('enabled')
+               }|htmlattr}>
+}}}
+(the `htmlattr` filter will add a space if needed; that way, if the condition is true, you end up with `<tr class="disabled">`, otherwise with just `<tr>`)
+If you wonder why the `if all(...)` expression morphed into `if not components|...`, it's because Jinja2 expressions are similar to Python expressions, but not quite the same.
+=== set complex variables   #set
+Note that Jinja2 expressions are a subset of Python expressions, and for the sake of simplicity the generator expressions are not part of that subset. This limitation often requires one to make creative use of [http://jinja.pocoo.org/docs/dev/templates/#filters filters], [http://jinja.pocoo.org/docs/dev/templates/#builtin-filters built-in] or custom (`min`, `max`, `trim`, `flatten`).
+A few more examples:
+||= Genshi ||= Jinja2 ||
+|| `${', '.join([p.name for p in faulty_plugins])}` || \
+|| `${faulty_plugins|map('name')|join(', ')}` ||
+|| `sum(1 for change in changes if 'cnum' in change)` || \
+|| `changes|selectattr('cnum')|list|count` ||
+|| `sum(1 for change in changes if 'cnum' not in change)` || \
+|| `changes|rejectattr('cnum')|list|count` ||
+|| ... || ... ||
+=== conditional wrappers
+There's no direct equivalent to the `py:strip`, but it can often be emulated with an `if/else/endif`.
+ - Genshi
+   {{{#!html+genshi
+     <a py:strip="not url" href="$url">$plugin.name</a>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+     # if url:
+     <a href="${url}">${plugin.name}</a>
+     # else:
+     ${plugin.name}
+     # endif
+   }}}
+If the repeated content is complex, one can use a //block assignment// (see below).
+=== i18n   #trans
+Genshi had a pretty good notion of what was a piece of translatable text within an HTML template,
+but Jinja2 doesn't, so there's no "guessing" and no i18n will happen unless explicitly asked.
+This can be done in two ways. First, with translation expressions, using the familiar `_()` gettext function (`gettext` and `ngettext` also supported).
+ - Genshi: [[xml(<strong>Trac detected an internal error:</strong>)]]
+ - Jinja2: [[xml(<strong>${_("Trac detected an internal error:")}</strong>)]]
+Second, using `trans` directives.
+ - Genshi:
+   {{{#!html+genshi
+                <p i18n:msg="create">Otherwise, please ${create_ticket(tracker)} a new bug report
+                describing the problem and explain how to reproduce it.</p>
+   }}}
+ - Jinja2:
+   {{{#!html+jinja
+                <p>
+                  # trans create = create_ticket(tracker)
+                  Otherwise, please ${create} a new bug report
+                  describing the problem and explain how to reproduce it.
+                  # endtrans
+                </p>
+   }}}
+   another example, without assignment:
+   {{{#!html+jinja
+            #   trans formatted
+            In the default time zone, this would be displayed
+            as <strong>${formatted}</strong>.
+            #   endtrans
+   }}}
+   last example, two expanded variables, with and without assignment:
+   {{{#!html+jinja
+            #   trans tz = nowtz.tzname(), formatted
+            In your time zone ${tz}, this would be displayed as
+            <strong>${formatted}</strong>.
+            #   endtrans
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#i18n i18n] doc.
+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+genshi
+              <p i18n:msg="">There was an internal error in Trac.
+                It is recommended that you notify your local
+                <a py:strip="not project.admin" href="mailto:${project.admin}">
+                    Trac administrator</a> with the information needed to
+                reproduce the issue.
+              </p>
+   }}}
+ - Jinja2:
+   {{{#!html+jinja
+              <p>
+                # set trac_admin = _("Trac administrator")
+                # set project_admin
+                #   if project.admin:
+                <a href="mailto:${project.admin}">${trac_admin}</a>
+                #   else:
+                ${trac_admin}
+                #   endif
+                # endset
+                # trans project_admin
+                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
+              </p>
+   }}}
+Note that another tricky case is when you want to use `gettext` and one of the variables is Markup. Using the `|safe` filter is needed, but that's not enough, as currently `gettext()` doesn't support Markup, you need to use `tgettext()` which is available with the `tag_` shortcut:
+{{{#!html+jinja
+  <em>
+    # set preferences_link
+    <a href="${href.prefs()}" class="trac-target-new">${
+      _("Preferences")}</a>
+    # endset
+    ${tag_("Set your email in %(preferences_link)s",
+           preferences_link=preferences_link|safe)}
+  </em>
+}}}
+== Examples
+== Overview
+We start we some examples, showing both the legacy Genshi templates and the new Jinja2 templates, highlighting their main differences.
+The second part of the document describes the Python code changes, from what you need to change to trigger the use of the Jinja2 renderer instead of the legacy Genshi renderer which still kicks in if nothing changes, to the new ways of generating content. Finally we go to great length to explain the most difficult part of the migration, how to replace the deprecated `ITemplateStreamFilter` interface which has no direct equivalent with Jinja2.
+In the last 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.
+Note that Genshi will be supported concurrently with Jinja2 only for a short while, for the 1.3.x development period and for the 1.4-stable period. This support will be removed in Trac [milestone:1.5.1]. 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.1. 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 their cost in memory usage.
+== Examples!
+Before going into the details of the code changes involved and the precise differences in the template syntax between the two systems, let's see at a glance how the templates look like.
 === Standalone template
 …
 In this small example, there's no common Trac layout used (as the index is a bit special).
 For how a "normal" template looks like, see for example
 [source:trac/templates/diff_form.html@jinja2-trunk-r15379 diff_form.html], another small template.
+[source:cboos.git/trac/templates/diff_view.html@jinja2-trunk-r15379 diff_form.html], another small template. The generic templates in [source:cboos.git/trac/templates@jinja2-trunk-r15379 trac/templates] are also interesting because we still have their Genshi equivalent close by, in [source:cboos.git/trac/templates/genshi@jinja2-trunk-r15379 trac/templates/genshi], so you can easily compare them if you're stuck during the migration of your own templates.
 Note that a Jinja2 .html template can usually be rendered directly in the browser, to have a rough idea about how it will look like:
 …
 But we also have a complete conversion [./Example example], which displays the Genshi wiki_view.html template and the Jinja2 wiki_view.html template side-by-side, along with comments explaining the conversion choices.
+=== Tips and tricks
+ - when you need to output a plain "#" character at the beginning of a line, this will be parsed as a line statement; the trick here is to use an empty inline comment as a prefix: `{##}# ...` (see [61e8d9ec/cboos.git])
+ - when you need to output indented text, this can be made difficult due to our `lstrip_block` configuration setting; you can work around this by embedding Python strings with the exact whitespace content you need in variable expressions: `    ${"\t  "}` (see [0fdef480/cboos.git])
 == Changes in the controllers ==
 …
+== Migrating to Jinja2 templates
+=== The Jinja2 syntax used by Trac
+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.
+We use the following configuration:
+|| key || value || example / explanation
+|| extensions ||  jinja2.ext.with_  jinja2.ext.i18n  || `with` directive can be used ([#with more])
+|| block_start_string ||  {%  || \
+{{{#!td rowspan=2
+`{% if cond %} value {% endif %}` possible (but discouraged)
+}}}
+|--
+|| block_end_string ||  %}  ||
+|| variable_start_string ||  ${  || \
+{{{#!td rowspan=2
+`${the_variable}` (but not `$the_variable`)
+([#expandavariable more])
+}}}
+|--
+|| variable_end_string ||  }  ||
+|| line_statement_prefix ||  #  || \
+{{{#!td
+{{{
+# if cond:
+value
+# endif
+}}}
+(preferred form) ([#if more])
+}}}
+|--
+|| line_comment_prefix ||  ##  || `## comments are good`
+|| trim_blocks ||  yes  || whitespace removal after a block
+|| lstrip_blocks ||  yes  || whitespace removal before a block
+|| newstyle_gettext ||  yes  || i.e. like the Trac `gettext`
+=== HTML differences between Jinja2 and Genshi templates
+We took the opportunity to **switch to HTML5** while performing this template overhaul.
+You should probably do the same.
+This usually won't change anything for your templates, except for a few details.
+The doctype and the <html> element should be changed from Genshi's:
+{{{#!html+genshi
+<!DOCTYPE html
+    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml"
+      xmlns:py="http://genshi.edgewall.org/"
+      xmlns:i18n="http://genshi.edgewall.org/i18n"
+      xmlns:xi="http://www.w3.org/2001/XInclude">
+}}}
+to the somewhat simpler:
+{{{#!xml
+<!DOCTYPE html>
+<html>
+}}}
+Special care should be taken when dealing with //void elements//.
+In XHTML, it's fine to write:
+{{{#!xml
+<div id="description"/>
+}}}
+However, when going to HTML5, you should use instead:
+{{{#!xml
+<div id="description"></div>
+}}}
+The valid [https://www.w3.org/TR/html-markup/syntax.html#void-elements void elements] in HTML5 are limited to the following list:
+ - area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track, wbr
+=== Detailed guide of differences between Jinja2 and Genshi
+Most of the time, the porting is a straightforward operation.
+==== expand a variable
+ - Genshi [[html+genshi(<b>$the_variable</b>)]]
+ - Jinja2 [[html+jinja(<b>${the_variable}</b>)]]
+Note that Jinja2 doesn't support the `$the_variable` style, the curly braces are mandatory.
+Tip:
+{{{#!shell
+sed -i -e 's,\$\([a-z_][a-z._]*\),${\1},g' template.html
+}}}
+==== expand a simple computation
+ - Genshi [[html+genshi(<b>${the_variable + 1}</b>)]]
+ - Jinja2 [[html+jinja(<b>${the_variable + 1}</b>)]]
+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 [#set set complex variables] below for more involved examples.
+Another customization we made to Jinja2 is to avoid having a Python `None` value be expanded to the `"None"` string. Instead, we make it produce an empty string, like Genshi did.
+==== include another template   #include
+ - Genshi [[xml(<xi:include href="the_file.html"><xi:fallback/></xi:include>)]]
+ - Jinja2 [[xml(# include "the_file.html" ignore missing)]]
+See [http://jinja.pocoo.org/docs/dev/templates/#include include] doc. Note that the `ignore missing` part is mandatory no templates are given to the `include` directive. This includes the following situation:
+{{{#!html+jinja
+# include "sometemplate.html" if false
+}}}
+This alone would raise an error. The correct thing to write is:
+{{{#!html+jinja
+# include "sometemplate.html" if false ignore missing
+}}}
+It is also possible to pass "parameters" to included templates.
+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:
+ - Genshi
+   {{{#!html+genshi
+        <xi:include href="ticket_box.html" py:with="can_append = False; preview_mode = False"/>
+   }}}
+ - Jinja
+   {{{#!html+jinja
+      # with
+      #   set can_append = false
+      #   set preview_mode = false
+      #   include "ticket_box.html"
+      # endwith
+   }}}
+See [http://jinja.pocoo.org/docs/dev/extensions/#with-statement with] doc.
+In passing, note how the boolean constants slightly differ from Python, `False` becomes `false`, `True` becomes `true` and `None` is `none`.
+Caveat: contrary to the Genshi way, one shouldn't include the `"layout.html"` template in order to inherit the default page layout. There's a big difference in the way template "inheritance" works between Genshi and Jinja2, see HtmlTemplates#Jinjaarchitecture for all the details.
+Despite these differences, we kept the same spirit and there's actually also a `"layout.html"` template that you can "inherit" from (as well as a `"theme.html"` template that the layout inherits in turn). But instead of "including" it in your template, you "extend" it:
+{{{#!html+jinja
+# extends "layout.html"
+}}}
+But this is not the place to go further in the details about how extending works, refer to the [http://jinja.pocoo.org/docs/dev/templates/#extends extends] documentation and to the link above for how this applies to Trac.
+==== simple if...then (no else)   #if
+ - Genshi [[xml(<py:if test="flag"><b>OK</b></py:if>)]] or simply: [[xml(<b py:if="flag">OK</b>)]]
+ - Jinja2
+   {{{#!html+jinja
+   # if flag:
+   <b>OK</b>
+   # endif
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#if if] doc.
+==== if...then...else
+ - Genshi
+   {{{#!html+genshi
+<py:choose test="flag">
+  <py:when test="True">
+    <b>OK</b>
+  </py:when>
+  <py:otherwise>
+   <i>!!!</i>
+  </py:otherwise>
+</py:choose>
+   }}}
+   or simply:
+   {{{#!html+genshi
+<py:choose>
+ <b py:when="flag">OK</b>
+ <i py:otherwise="">!!!</i>
+</py:choose>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+ # if flag:
+ <b>OK</b>
+ # else:
+ <i>!!!</i>
+ # endif
+   }}}
+If you really have to, you can also use the block style:
+{{{#!html+jinja
+{{ if flag }}<b>OK</b>{{ else }}<i>!!!</i>{{ endif }}
+}}}
+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]//.
+==== iterate over a collection   #for
+ - Genshi
+   {{{#!html+genshi
+<ul>
+  <py:for each="element in list">
+    <li>$element</li>
+  </py:for>
+</ul>
+   }}}
+   or simply:
+   {{{#!html+genshi
+<ul>
+  <li py:for="element in list">$element</li>
+</ul>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+<ul>
+  # for element in list:
+  <li>${element}</li>
+  # endfor
+</ul>
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#for for] doc.
+===== No need for `enumerate`
+ - Genshi:
+{{{#!html+genshi
+          <tr py:for="idx,option in enumerate(section.options)"
+              class="${'modified' if option.modified else None}">
+            <th py:if="idx == 0" class="section"
+                rowspan="${len(section.options)}">${section.name}</th>
+}}}
+ - Jinja2:
+{{{#!html+jinja
+          #   for option in section.options:
+          <tr ${{'class': 'modified' if option.modified}|htmlattr}>
+            #   if loop.first:
+            <th class="section"
+                rowspan="${len(section.options)}">${section.name}</th>
+}}}
+All common uses (and more) for such an `idx` variable are addressed by the special `loop` variable.
+See [http://jinja.pocoo.org/docs/dev/templates/#for loop] doc.
+==== define a macro   #macro
+ - Genshi
+   {{{#!html+genshi
+<py:def function="entry(key, val='--')">
+ <dt>$key</dt><dd>$val</dd>
+</py:def>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+ # macro entry(key, val='--')
+ <dt>${key}</dt><dd>${val}</dd>
+ # endmacro
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#macros macros] doc.
+==== set a variable
+ - Genshi
+   {{{#!html+genshi
+<py:with vars="count = len(collection)">
+We have ${count &gt; 10 and 'too much' or count} elements.
+</py:with>
+   }}}
+   Note that we had to use `&gt;` in Genshi, we can't use `>` directly.
+ - Jinja2
+   {{{#!html+jinja
+# set count = len(collection)
+We have ${'too much' if count is greaterthan(10) else count} elements.
+   }}}
+   Note that we avoid using `>` in Jinja2 expressions as well, but simply to avoid that XML/HTML text editors get confused. We added a few custom tests for that (`greaterthan`, `greaterthanorequal`, `lessthan`, `lessthanorequal`).
+See [http://jinja.pocoo.org/docs/dev/templates/#tests tests] doc.
+==== set several variables in a scope #with
+ - Genshi
+   {{{#!html+genshi
+<html py:with="is_query = report.sql.startswith('query:');
+               new_report = action == 'new' and not is_query;
+               new_query = action == 'new' and is_query">
+  ...
+</html>
+   }}}
+   The variables are set for the scope of the element in which they are set (here <html>,
+   so the whole document)
+ - Jinja2
+   {{{#!html+jinja
+    #   with
+    #     set is_query = report.sql.startswith('query:')
+    #     set new_report = action == 'new' and not is_query
+    ...
+    #   endwith
+   }}}
+But actually you will only use `with` in specific situations, like for wrapping an include directive (see [#include]). If you're already within a `for`, a `block` or a `macro`, the scope of the assignment is already limited to that of this directive.
+See [http://jinja.pocoo.org/docs/dev/templates/#assignments set] and [http://jinja.pocoo.org/docs/dev/templates/#with-statement with] docs.
+In addition, `with` can also be used to better control how the successive `set` on a given variable are being applied (see for example [1e25c852/cboos.git] and [cc1b959e/cboos.git]).
+Finally be careful when using `with`: don't wrap a `block` directive within a `with`. If you want to set a global scope for the document (like in our <html> example above), it's tempting to use a single `with` statement, for clarity. But that would wrap all blocks defined in the template and strange results would ensue.
+==== set HTML attributes   #htmlattr
+In Genshi, an attribute with a `None` value wouldn't be output. However, Jinja2 doesn't know what an attribute is (or anything else about HTML, XML for that matter), so we have to use a special filter, `htmlattr`, to reproduce this behavior:
+ - Genshi:
+{{{#!html+genshi
+          <tr class="${'disabled' if all(not component.enabled for module in plugin.modules.itervalues()
+                                         for component in module.components.itervalues()) else None}">
+}}}
+ - Jinja2:
+{{{#!html+jinja
+          #   set components = plugin.modules|map(attribute='components')|flatten
+          <tr${{'class': 'disabled' if not components|selectattr('enabled')
+               }|htmlattr}>
+}}}
+(the `htmlattr` filter will add a space if needed; that way, if the condition is true, you end up with `<tr class="disabled">`, otherwise with just `<tr>`)
+If you wonder why the `if all(...)` expression morphed into `if not components|...`, it's because Jinja2 expressions are similar to Python expressions, but not quite the same.
+=== set complex variables   #set
+Note that Jinja2 expressions are a subset of Python expressions, and for the sake of simplicity the generator expressions are not part of that subset. This limitation often requires one to make creative use of [http://jinja.pocoo.org/docs/dev/templates/#filters filters], [http://jinja.pocoo.org/docs/dev/templates/#builtin-filters built-in] or custom (`min`, `max`, `trim`, `flatten`).
+A few more examples:
+||= Genshi ||= Jinja2 ||
+|| `${', '.join([p.name for p in faulty_plugins])}` || \
+|| `${faulty_plugins|map('name')|join(', ')}` ||
+|| `sum(1 for change in changes if 'cnum' in change)` || \
+|| `changes|selectattr('cnum')|list|count` ||
+|| `sum(1 for change in changes if 'cnum' not in change)` || \
+|| `changes|rejectattr('cnum')|list|count` ||
+|| ... || ... ||
+==== conditional wrappers
+There's no direct equivalent to the `py:strip`, but it can often be emulated with an `if/else/endif`.
+ - Genshi
+   {{{#!html+genshi
+     <a py:strip="not url" href="$url">$plugin.name</a>
+   }}}
+ - Jinja2
+   {{{#!html+jinja
+     # if url:
+     <a href="${url}">${plugin.name}</a>
+     # else:
+     ${plugin.name}
+     # endif
+   }}}
+If the repeated content is complex, one can use a //block assignment// (see below).
+==== i18n   #trans
+Genshi had a pretty good notion of what was a piece of translatable text within an HTML template,
+but Jinja2 doesn't, so there's no "guessing" and no i18n will happen unless explicitly asked.
+This can be done in two ways. First, with translation expressions, using the familiar `_()` gettext function (`gettext` and `ngettext` also supported).
+ - Genshi: [[xml(<strong>Trac detected an internal error:</strong>)]]
+ - Jinja2: [[xml(<strong>${_("Trac detected an internal error:")}</strong>)]]
+Second, using `trans` directives.
+ - Genshi:
+   {{{#!html+genshi
+                <p i18n:msg="create">Otherwise, please ${create_ticket(tracker)} a new bug report
+                describing the problem and explain how to reproduce it.</p>
+   }}}
+ - Jinja2:
+   {{{#!html+jinja
+                <p>
+                  # trans create = create_ticket(tracker)
+                  Otherwise, please ${create} a new bug report
+                  describing the problem and explain how to reproduce it.
+                  # endtrans
+                </p>
+   }}}
+   another example, without assignment:
+   {{{#!html+jinja
+            #   trans formatted
+            In the default time zone, this would be displayed
+            as <strong>${formatted}</strong>.
+            #   endtrans
+   }}}
+   last example, two expanded variables, with and without assignment:
+   {{{#!html+jinja
+            #   trans tz = nowtz.tzname(), formatted
+            In your time zone ${tz}, this would be displayed as
+            <strong>${formatted}</strong>.
+            #   endtrans
+   }}}
+See [http://jinja.pocoo.org/docs/dev/templates/#i18n i18n] doc.
+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+genshi
+              <p i18n:msg="">There was an internal error in Trac.
+                It is recommended that you notify your local
+                <a py:strip="not project.admin" href="mailto:${project.admin}">
+                    Trac administrator</a> with the information needed to
+                reproduce the issue.
+              </p>
+   }}}
+ - Jinja2:
+   {{{#!html+jinja
+              <p>
+                # set trac_admin = _("Trac administrator")
+                # set project_admin
+                #   if project.admin:
+                <a href="mailto:${project.admin}">${trac_admin}</a>
+                #   else:
+                ${trac_admin}
+                #   endif
+                # endset
+                # trans project_admin
+                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
+              </p>
+   }}}
+Note that another tricky case is when you want to use `gettext` and one of the variables is Markup. Using the `|safe` filter is needed, but that's not enough, as currently `gettext()` doesn't support Markup, you need to use `tgettext()` which is available with the `tag_` shortcut:
+{{{#!html+jinja
+  <em>
+    # set preferences_link
+    <a href="${href.prefs()}" class="trac-target-new">${
+      _("Preferences")}</a>
+    # endset
+    ${tag_("Set your email in %(preferences_link)s",
+           preferences_link=preferences_link|safe)}
+  </em>
+}}}
+==== Tips and tricks
+ - when you need to output a plain "#" character at the beginning of a line, this will be parsed as a line statement; the trick here is to use an empty inline comment as a prefix: `{##}# ...` (see [61e8d9ec/cboos.git])
+ - when you need to output indented text, this can be made difficult due to our `lstrip_block` configuration setting; you can work around this by embedding Python strings with the exact whitespace content you need in variable expressions: `    ${"\t  "}` (see [0fdef480/cboos.git])