Edgewall Software

Changes between Version 3 and Version 4 of TracDev/PortingFromGenshiToJinja/Example


Ignore:
Timestamp:
Feb 2, 2017, 12:15:40 AM (3 years ago)
Author:
Christian Boos
Comment:

more distinctive comment rows

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PortingFromGenshiToJinja/Example

    v3 v4  
    4343}}}
    4444|-----------------------------------------------------------------------------
    45 |||| Block comments ||
     45{{{#!td colspan=2 style="font-style: italic"
     46  Block comments
     47}}}
    4648|-----------------------------------------------------------------------------
    4749{{{#!td
     
    5557}}}
    5658|-----------------------------------------------------------------------------
    57 |||| 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. ||
     59{{{#!td colspan=2 style="font-style: italic"
     60 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. ||
     61}}}
    5862|-----------------------------------------------------------------------------
    5963{{{#!td
     
    7074}}}
    7175|-----------------------------------------------------------------------------
    72 |||| 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) ||
     76{{{#!td colspan=2 style="font-style: italic"
     77 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)
     78}}}
    7379|-----------------------------------------------------------------------------
    7480{{{#!td
     
    9197}}}
    9298|-----------------------------------------------------------------------------
    93 {{{#!td
    94 No need for exotic namespace declarations.
    95 
    96 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.
     99{{{#!td colspan=2 style="font-style: italic"
     100  No need for exotic namespace declarations.
     101
     102 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.
    97103}}}
    98104|-----------------------------------------------------------------------------
     
    107113}}}
    108114|-----------------------------------------------------------------------------
    109 |||| See above, this will be converted to an initial `extends` statement. ||
     115{{{#!td colspan=2 style="font-style: italic"
     116 See above, this will be converted to an initial `extends` statement.
     117}}}
    110118|-----------------------------------------------------------------------------
    111119{{{#!td
     
    134142}}}
    135143|-----------------------------------------------------------------------------
    136 {{{#!td colspan=2
    137 The content of the <title> element is placed in the ''title'' block,
    138 followed by the content of the parent ''title'' block (`${ super() }`).
    139 When closing the block, we reuse the name of the block.
    140 
    141 Note that while the only thing that really matters in an extending template
    142 is the content of the blocks, we try hard to keep a correct HTML structure
    143 for the whole template page, so that its HTML content can be validated in a
    144 standalone way (cf. [#jinjachecker]). This is why we add the <html>, <head> and
    145 <title> tags.
    146 
    147 We explained earlier why the title block has to be outside of the ''head'' block:
    148 to avoid appearing twice, once as part of the head block, and the second time
    149 when we call `${ super() }` in order to retrieve the content of the parent ''head''
    150 block.
    151 
    152 Finally, we define some variables at the beginning of the block (corresponding to
    153 some which were part of the `py:with` attribute in the `<html>` tag, in the Genshi
    154 template).
     144{{{#!td colspan=2 style="font-style: italic"
     145 The content of the <title> element is placed in the ''title'' block,
     146 followed by the content of the parent ''title'' block (`${ super() }`).
     147 When closing the block, we reuse the name of the block.
     148
     149 Note that while the only thing that really matters in an extending template
     150 is the content of the blocks, we try hard to keep a correct HTML structure
     151 for the whole template page, so that its HTML content can be validated in a
     152 standalone way (cf. [#jinjachecker]). This is why we add the <html>, <head> and
     153 <title> tags.
     154
     155 We explained earlier why the title block has to be outside of the ''head'' block:
     156 to avoid appearing twice, once as part of the head block, and the second time
     157 when we call `${ super() }` in order to retrieve the content of the parent ''head''
     158 block.
     159
     160 Finally, we define some variables at the beginning of the block (corresponding to
     161 some which were part of the `py:with` attribute in the `<html>` tag, in the Genshi
     162 template).
    155163}}}
    156164|-----------------------------------------------------------------------------
     
    182190}}}
    183191|-----------------------------------------------------------------------------
    184 |||| With Jinja2, the logic is now clearly distinct from the content. ||
     192{{{#!td colspan=2 style="font-style: italic"
     193 With Jinja2, the logic is now clearly distinct from the content.
     194}}}
    185195|-----------------------------------------------------------------------------
    186196{{{#!td
     
    215225}}}
    216226|-----------------------------------------------------------------------------
    217 |||| No changes here, except for some reformatting (we try to stay below 80 chars for nicer future side-by-side diffs). ||
     227{{{#!td colspan=2 style="font-style: italic"
     228 No changes here, except for some reformatting (we try to stay below 80 chars for nicer future side-by-side diffs).
     229}}}
    218230|-----------------------------------------------------------------------------
    219231{{{#!td
     
    231243}}}
    232244|-----------------------------------------------------------------------------
    233 |||| We close the ''head'' block. ||
     245{{{#!td colspan=2 style="font-style: italic"
     246 We close the ''head'' block.
     247}}}
    234248|-----------------------------------------------------------------------------
    235249{{{#!td
     
    254268}}}
    255269|-----------------------------------------------------------------------------
    256 |||| We start the ''content'' block. As before with the ''header'' block, we define some variables at the beginning of the block. ||
     270{{{#!td colspan=2 style="font-style: italic"
     271 We start the ''content'' block. As before with the ''header'' block, we define some variables at the beginning of the block.
     272}}}
    257273|-----------------------------------------------------------------------------
    258274{{{#!td
     
    302318}}}
    303319|-----------------------------------------------------------------------------
    304 {{{#!td colspan=2
    305 Here we illustrate the i18n changes.
    306 
    307 First, any sentence that corresponds to visible end-user text that should be
    308 translated has to be marked somehow.
    309 
    310 One way is to use the standard i18n calls,
    311 `_`, `ngettext()`, etc.
    312 
    313 The other way is to use `trans` blocks.
    314 There are two big differences with their Genshi i18n equivalent:
    315  - variable substitutions can only be those of direct variables,
    316    no kind of expression is allowed, even as simple as attribute
    317    lookup
    318  - Jinja2, markup neutral as it is, will not do any substitutions
    319    on the markup found in a trans block; what would have ended
    320    in a Genshi bracketed expression `... [1:diff]` in the catalogs
    321    will now remain HTML markup: `... <a href="${href}">diff</a>`.
    322 Note that one can use a `with` statement for breaking up the
    323 assignments needed on multiple separate lines.
    324 Smaller lists of variables can be placed on the `trans` line directly.
     320{{{#!td colspan=2 style="font-style: italic"
     321 Here we illustrate the i18n changes.
     322
     323 First, any sentence that corresponds to visible end-user text that should be
     324 translated has to be marked somehow.
     325
     326 One way is to use the standard i18n calls,
     327 `_`, `ngettext()`, etc.
     328
     329 The other way is to use `trans` blocks.
     330 There are two big differences with their Genshi i18n equivalent:
     331  - variable substitutions can only be those of direct variables,
     332    no kind of expression is allowed, even as simple as attribute
     333    lookup
     334  - Jinja2, markup neutral as it is, will not do any substitutions
     335    on the markup found in a trans block; what would have ended
     336    in a Genshi bracketed expression `... [1:diff]` in the catalogs
     337    will now remain HTML markup: `... <a href="${href}">diff</a>`.
     338 Note that one can use a `with` statement for breaking up the
     339 assignments needed on multiple separate lines.
     340 Smaller lists of variables can be placed on the `trans` line directly.
    325341}}}
    326342|-----------------------------------------------------------------------------
     
    424440}}}
    425441|-----------------------------------------------------------------------------
    426 |||| Jinja2 includes also know about their context, so that make them kind of parametric. ||
     442{{{#!td colspan=2 style="font-style: italic"
     443 Jinja2 includes also know about their context, so that make them kind of parametric.
     444}}}
    427445|-----------------------------------------------------------------------------
    428446{{{#!td
     
    446464}}}
    447465|-----------------------------------------------------------------------------
    448 |||| 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. ||
     466{{{#!td colspan=2 style="font-style: italic"
     467  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.
     468}}}
    449469|-----------------------------------------------------------------------------
    450470{{{#!td
     
    518538}}}
    519539|-----------------------------------------------------------------------------
    520 {{{#!td
    521 A `<py:choose>` and its series of `<py:when>` translates very smoothly into a sequence of `if / elif` statements.
    522 
    523 Special care should be taken when producing attributes dynamically, as it's the
    524 case here for `selected`. We use the `htmlattr` filter that takes care of
    525 producing the right value for the attribute depending on its content: with
    526 a truth value, we'll output `selected="selected"` otherwise we'll just omit
    527 the parameter.
     540{{{#!td colspan=2 style="font-style: italic"
     541 A `<py:choose>` and its series of `<py:when>` translates very smoothly into a sequence of `if / elif` statements.
     542
     543 Special care should be taken when producing attributes dynamically, as it's the
     544 case here for `selected`. We use the `htmlattr` filter that takes care of
     545 producing the right value for the attribute depending on its content: with
     546 a truth value, we'll output `selected="selected"` otherwise we'll just omit
     547 the parameter.
    528548}}}
    529549|-----------------------------------------------------------------------------
     
    550570}}}
    551571|-----------------------------------------------------------------------------
    552 |||| We pass `attachments` as `alist` to the included template. ||
     572{{{#!td colspan=2 style="font-style: italic"
     573 We pass `attachments` as `alist` to the included template.
     574}}}
    553575|-----------------------------------------------------------------------------
    554576{{{#!td
     
    635657}}}
    636658|-----------------------------------------------------------------------------
    637 |||| Here's the first use of the `for` statement. Straightforward. ||
     659{{{#!td colspan=2 style="font-style: italic"
     660 Here's the first use of the `for` statement. Straightforward.
     661}}}
    638662|-----------------------------------------------------------------------------
    639663{{{#!td
     
    684708}}}
    685709|-----------------------------------------------------------------------------
    686 |||| 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. ||
    687 |-----------------------------------------------------------------------------
     710{{{#!td colspan=2 style="font-style: italic"
     711  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.
     712}}}
     713|-----------------------------------------------------------------------------