Context Navigation

← Previous Change
Wiki History
Next Change →

Example

Timestamp:: Feb 2, 2017, 12:15:40 AM (7 years ago)
Author:: Christian Boos
Comment:: more distinctive comment rows

Legend:

: Unmodified
: Added
: Removed
: Modified

TracDev/PortingFromGenshiToJinja/Example

-              v3
+              v4
 }}}
 |-----------------------------------------------------------------------------
+|||| Block comments ||
+{{{#!td colspan=2 style="font-style: italic"
+  Block comments
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| This is the equivalent of Genshi's `<py:include href="layout.html" />`. We have to do the extends before outputing any content on our own, otherwise it would show up in the final result. Once we made the `extends`, only the content written within //blocks// will matter. ||
+{{{#!td colspan=2 style="font-style: italic"
+ This is the equivalent of Genshi's `<py:include href="layout.html" />`. We have to do the extends before outputing any content on our own, otherwise it would show up in the final result. Once we made the `extends`, only the content written within //blocks// will matter. ||
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| Let's directly make the jump to HTML5, while we're at it (I'm not sure what is the current state of the HTML5 support in Genshi, but it no longer matters) ||
+{{{#!td colspan=2 style="font-style: italic"
+ Let's directly make the jump to HTML5, while we're at it (I'm not sure what is the current state of the HTML5 support in Genshi, but it no longer matters)
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
 {{{#!td
 No need for exotic namespace declarations.
 Note that we can't use a `with` declaration that would encompass the ''head'' and ''content'' blocks we'll define in a moment, as this would force the generation of content twice, once by having the with block present in the template, and a second time because of the extends and the call of the blocks.
+{{{#!td colspan=2 style="font-style: italic"
+  No need for exotic namespace declarations.
+ Note that we can't use a `with` declaration that would encompass the ''head'' and ''content'' blocks we'll define in a moment, as this would force the generation of content twice, once by having the with block present in the template, and a second time because of the extends and the call of the blocks.
 }}}
 |-----------------------------------------------------------------------------
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| See above, this will be converted to an initial `extends` statement. ||
+{{{#!td colspan=2 style="font-style: italic"
+ See above, this will be converted to an initial `extends` statement.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
 {{{#!td colspan=2
 The content of the <title> element is placed in the ''title'' block,
 followed by the content of the parent ''title'' block (`${ super() }`).
 When closing the block, we reuse the name of the block.
 Note that while the only thing that really matters in an extending template
 is the content of the blocks, we try hard to keep a correct HTML structure
 for the whole template page, so that its HTML content can be validated in a
 standalone way (cf. [#jinjachecker]). This is why we add the <html>, <head> and
 <title> tags.
 We explained earlier why the title block has to be outside of the ''head'' block:
 to avoid appearing twice, once as part of the head block, and the second time
 when we call `${ super() }` in order to retrieve the content of the parent ''head''
 block.
 Finally, we define some variables at the beginning of the block (corresponding to
 some which were part of the `py:with` attribute in the `<html>` tag, in the Genshi
 template).
+{{{#!td colspan=2 style="font-style: italic"
+ The content of the <title> element is placed in the ''title'' block,
+ followed by the content of the parent ''title'' block (`${ super() }`).
+ When closing the block, we reuse the name of the block.
+ Note that while the only thing that really matters in an extending template
+ is the content of the blocks, we try hard to keep a correct HTML structure
+ for the whole template page, so that its HTML content can be validated in a
+ standalone way (cf. [#jinjachecker]). This is why we add the <html>, <head> and
+ <title> tags.
+ We explained earlier why the title block has to be outside of the ''head'' block:
+ to avoid appearing twice, once as part of the head block, and the second time
+ when we call `${ super() }` in order to retrieve the content of the parent ''head''
+ block.
+ Finally, we define some variables at the beginning of the block (corresponding to
+ some which were part of the `py:with` attribute in the `<html>` tag, in the Genshi
+ template).
 }}}
 |-----------------------------------------------------------------------------
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| With Jinja2, the logic is now clearly distinct from the content. ||
+{{{#!td colspan=2 style="font-style: italic"
+ With Jinja2, the logic is now clearly distinct from the content.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| No changes here, except for some reformatting (we try to stay below 80 chars for nicer future side-by-side diffs). ||
+{{{#!td colspan=2 style="font-style: italic"
+ No changes here, except for some reformatting (we try to stay below 80 chars for nicer future side-by-side diffs).
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| We close the ''head'' block. ||
+{{{#!td colspan=2 style="font-style: italic"
+ We close the ''head'' block.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| We start the ''content'' block. As before with the ''header'' block, we define some variables at the beginning of the block. ||
+{{{#!td colspan=2 style="font-style: italic"
+ We start the ''content'' block. As before with the ''header'' block, we define some variables at the beginning of the block.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
 {{{#!td colspan=2
 Here we illustrate the i18n changes.
 First, any sentence that corresponds to visible end-user text that should be
 translated has to be marked somehow.
 One way is to use the standard i18n calls,
 `_`, `ngettext()`, etc.
 The other way is to use `trans` blocks.
 There are two big differences with their Genshi i18n equivalent:
  - variable substitutions can only be those of direct variables,
    no kind of expression is allowed, even as simple as attribute
    lookup
  - Jinja2, markup neutral as it is, will not do any substitutions
    on the markup found in a trans block; what would have ended
    in a Genshi bracketed expression `... [1:diff]` in the catalogs
    will now remain HTML markup: `... <a href="${href}">diff</a>`.
 Note that one can use a `with` statement for breaking up the
 assignments needed on multiple separate lines.
 Smaller lists of variables can be placed on the `trans` line directly.
+{{{#!td colspan=2 style="font-style: italic"
+ Here we illustrate the i18n changes.
+ First, any sentence that corresponds to visible end-user text that should be
+ translated has to be marked somehow.
+ One way is to use the standard i18n calls,
+ `_`, `ngettext()`, etc.
+ The other way is to use `trans` blocks.
+ There are two big differences with their Genshi i18n equivalent:
+  - variable substitutions can only be those of direct variables,
+    no kind of expression is allowed, even as simple as attribute
+    lookup
+  - Jinja2, markup neutral as it is, will not do any substitutions
+    on the markup found in a trans block; what would have ended
+    in a Genshi bracketed expression `... [1:diff]` in the catalogs
+    will now remain HTML markup: `... <a href="${href}">diff</a>`.
+ Note that one can use a `with` statement for breaking up the
+ assignments needed on multiple separate lines.
+ Smaller lists of variables can be placed on the `trans` line directly.
 }}}
 |-----------------------------------------------------------------------------
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| Jinja2 includes also know about their context, so that make them kind of parametric. ||
+{{{#!td colspan=2 style="font-style: italic"
+ Jinja2 includes also know about their context, so that make them kind of parametric.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| Again, even when there's a lot of control lines, it's a bit easier to immediately spot the actual content in Jinja2 templates, due to the clearer syntactic difference. ||
+{{{#!td colspan=2 style="font-style: italic"
+  Again, even when there's a lot of control lines, it's a bit easier to immediately spot the actual content in Jinja2 templates, due to the clearer syntactic difference.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
 {{{#!td
 A `<py:choose>` and its series of `<py:when>` translates very smoothly into a sequence of `if / elif` statements.
 Special care should be taken when producing attributes dynamically, as it's the
 case here for `selected`. We use the `htmlattr` filter that takes care of
 producing the right value for the attribute depending on its content: with
 a truth value, we'll output `selected="selected"` otherwise we'll just omit
 the parameter.
+{{{#!td colspan=2 style="font-style: italic"
+ A `<py:choose>` and its series of `<py:when>` translates very smoothly into a sequence of `if / elif` statements.
+ Special care should be taken when producing attributes dynamically, as it's the
+ case here for `selected`. We use the `htmlattr` filter that takes care of
+ producing the right value for the attribute depending on its content: with
+ a truth value, we'll output `selected="selected"` otherwise we'll just omit
+ the parameter.
 }}}
 |-----------------------------------------------------------------------------
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| We pass `attachments` as `alist` to the included template. ||
+{{{#!td colspan=2 style="font-style: italic"
+ We pass `attachments` as `alist` to the included template.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| Here's the first use of the `for` statement. Straightforward. ||
+{{{#!td colspan=2 style="font-style: italic"
+ Here's the first use of the `for` statement. Straightforward.
+}}}
 |-----------------------------------------------------------------------------
 {{{#!td
 …
 }}}
 |-----------------------------------------------------------------------------
+|||| Once we're done with the `<div id="content">`, we also call `${ super() }` to re-insert the parent content of the ''content'' block, i.e. the altlinks div and the late_links/late_scripts logic. ||
+|-----------------------------------------------------------------------------
+{{{#!td colspan=2 style="font-style: italic"
+  Once we're done with the `<div id="content">`, we also call `${ super() }` to re-insert the parent content of the ''content'' block, i.e. the altlinks div and the late_links/late_scripts logic.
+}}}
+|-----------------------------------------------------------------------------