Edgewall Software

Changes between Version 2 and Version 3 of TracDev/HtmlTemplates


Ignore:
Timestamp:
Jan 15, 2017, 1:10:36 AM (7 years ago)
Author:
Christian Boos
Comment:

remove some 'j's, update source: links

Legend:

Unmodified
Added
Removed
Modified

  • TracDev/HtmlTemplates

    v2 v3  
    1414
    1515I've never really tried the TH:ThemeEnginePlugin plugin, or alternatives, so I can't be sure if I got it right, but from what I can see in Trac's code base itself, the idea with Genshi-based themeing (and page architecture in general) was to have a dynamically loaded "theme" template page that would primarily be in charge of the main structure of all HTML pages.
     16
     17=== The search.html template
    1618
    1719Let's take the example of a simple "end user" page, the search.html page.
    … …  
    108110An example of another theme page: [https://github.com/chevah/trac-bootstrap-theme/blob/master/templates/theme.html trac-bootstrap-theme's theme.html].
    109111
    110 
     112=== The admin.html template as container for other templates
    111113
    112114Note that this scheme can be extended to additional intermediate levels,
    … …  
    176178as it can reuse it inside its block (by calling `super()`) or not.
    177179
     180=== The search.html template
    178181Let's transpose the previous example of the search.html template.
    179 For as long as we'll have both template engines coexisting,
    180 we'll prefix the new Jinja2 templates with a `j`.
     182
    181183So we're now discussing:
    182  - jsearch.html, which extends
    183    - jlayout.html, which extends
    184      - jtheme.html (as this is our default theme page)
    185 
    186 A template which extends another can redefine the content of the //named blocks// defined in the extended template. This redefinition may or may not refer to the original content of the block in the extended template (`${ super() }`).
     184 - [source:cboos.git/trac/search/templates/search.html@jinja2-trunk-r15341 search.html], which extends
     185   - [source:cboos.git/trac/templates/layout.html@jinja2-trunk-r15341 layout.html], which extends
     186     - [source:cboos.git/trac/templates/theme.html@jinja2-trunk-r15341 theme.html] (as this is our default theme page)
     187
     188A template which extends another can redefine the content of the //named blocks// defined in the extended template. This redefinition may or may not include the original content of the block in the extended template (`${ super() }`).
    187189
    188190We first give an overview of the three templates and how their content will be combined in the generated output.
    189191
    190192
    191 
    192193|--------------------------------------------------------------------------
    193 ||  __jtheme.html__    || \
    194 ||  __jlayout.html__ \\ //# extends jtheme.html//   || \
    195 ||  __jsearch.html__ \\ //# extends jlayout.html//  ||
     194||  __theme.html__    || \
     195||  __layout.html__ \\ //# extends theme.html//   || \
     196||  __search.html__ \\ //# extends layout.html//  ||
    196197|--------------------------------------------------------------------------
    197198{{{#!td style="vertical-align:top"
    … …  
    349350
    350351Let's have a closer look at the content of each template, starting with the
    351 most specific template, in our example the
    352 [source:cboos.git/trac/search/templates/jsearch.html jsearch.html] page:
     352most specific template, in our example the [source:cboos.git/trac/search/templates/search.html@jinja2-trunk-r15341 search.html] page:
    353353{{{#!html+jinja
    354 # extends 'jlayout.html'
     354# extends 'layout.html'
    355355
    356356<!DOCTYPE html>
    … …  
    378378</html>
    379379}}}
    380  - it starts by //extending// the jlayout.html page (`# extends 'jlayout.html')
     380 - it starts by //extending// the layout.html page (`# extends 'layout.html')
    381381 - then it redefines the ''title'', ''head'' and ''content'' blocks,
    382382   and has to place a `${ super() }` expression in order to insert the default
    383383   content proposed by the extended template at the right place;
    384384   note that the presence of the `<html>`, `<head>` and `<body>` tags here
    385    is strictly "decorative", it will be ignored in the final output. As we're
    386    in a template extending another, only what's in the redefined blocks matters.
    387 
    388 These blocks are first defined in the extended template, jlayout.html.
    389 
    390 The [source:cboos.git/trac/templates/jlayout.html jlayout.html] page looks like this:
     385   is strictly "decorative", they will be ignored in the final output. As we're
     386   in a template extending another, **only what's in the redefined blocks matters**.
     387   This is especially important to remember, as this can be a source of error:
     388   for example, no matter that you added your `<script>` tags to the `<head>` of your
     389   template, they will only make it in the final output if you took care of placing
     390   them within the `# block head`... (e.g. [changeset:a47b48a3/cboos.git#file6 this fix])
     391
     392These blocks are first defined in the extended template, layout.html.
     393
     394The [source:cboos.git/trac/templates/layout.html@jinja2-trunk-r15341 layout.html] page looks like this:
    391395{{{#!html+jinja
    392 # extends ('j' + chrome.theme)
     396# extends chrome.theme
    393397
    394398<!DOCTYPE html>
    … …  
    418422</html>
    419423}}}
    420  - first **dynamically** //extends// in turn some "theme" page (`# extends ('j' + chrome.theme)`)
    421  - then the jlayout.html template defines a few blocks:
     424 - first **dynamically** //extends// in turn some "theme" page (`# extends chrome.theme`)
     425 - then the layout.html template defines a few blocks:
    422426    - the ''head'' block and its ''title'' sub-block; here we understand why we've put
    423       the ''title'' block **outside** of the ''head'' block in the jsearch.html template:
    424       the jlayout.html's ''head'' block contains among other things a `<title>` element,
     427      the ''title'' block **outside** of the ''head'' block in the search.html template:
     428      the layout.html's ''head'' block contains among other things a `<title>` element,
    425429      and we're reusing  that default content in the inheriting ''head'' block; if in
    426       jsearch.html we had defined the <title> element in the ''head'' block as well,
     430      search.html we had defined the <title> element in the ''head'' block as well,
    427431      we would have had two of these <title> elements in that block
    428432    - the ''content'' block which is filled with some predefined, generic content,
    … …  
    431435
    432436By default, this theme template will be our
    433 [source:cboos.git/trac/templates/jtheme.html jtheme.html] page:
     437[source:cboos.git/trac/templates/theme.html@jinja2-trunk-r15341 theme.html] page:
    434438{{{#!html+jinja
    435439
    … …  
    461465 - it defines a ''head'' block inside an otherwise empty `<head>` element;
    462466   this means this is simply a "slot" that will be filled by the content
    463    of the `head` block in the extending templates (in this case, jlayout.html)
     467   of the `head` block in the extending templates (in this case, layout.html)
    464468 - it contains a `<body>` element;
    465469   as we want to replicate what the original theme.html did,
    466470   what we want to achieve here is to provide a ''slot''
    467471   at the place where we want to insert the content
    468    produced by the jlayout.html template;
     472   produced by the layout.html template;
    469473   I didn't name that inner block "body", as this could be confusing:
    470474   we're not in control of the `<body>` element there, just of
    … …  
    475479have to redefine the ''body'' block which contains all of the default structure
    476480(possibly reusing the content of that block by a call to `${ super() }`).
    477 In our case, neither jsearch.html nor jlayout.html redefine the `body` block,
    478 as they're happy with what jtheme does with it.
     481In our case, neither search.html nor layout.html redefine the `body` block,
     482as they're happy with what theme does with it.
    479483
    480484
    … …  
    484488readily doable with Genshi ("top-down" control).
    485489
     490=== The admin.html template as container for other templates
    486491
    487492Like what we did with Genshi, this scheme can be extended to support additional intermediate levels. We did that for the admin and the preference panels.
    488493
    489 Let's take for example the Logging admin panel, [source:cboos.git/trac/admin/templates/jadmin_logging.html jadmin_logging.html]:
     494Let's take for example the Logging admin panel,
     495[source:cboos.git/trac/admin/templates/admin_logging.html@jinja2-trunk-r15341 admin_logging.html]:
    490496{{{#!html+jinja
    491497# extends "jadmin.html"
    … …  
    506512</html>
    507513}}}
    508  - it starts by extending the jadmin.html page
     514 - it starts by extending the admin.html page
    509515 - then it provides the `<head>` and `<body>` elements specific to that panel,
    510516   more precisely the //admintitle// and //adminpanel// blocks (if some JavaScript
    511517   or other resources are needed, the //head// could be redefined as well)
    512518   
    513 The [source:cboos.git/trac/admin/templates/jadmin.html@jinja2 jadmin.html] page
    514 is similar to the jsearch.html page in that it extends the jlayout.html:
     519The [source:cboos.git/trac/admin/templates/admin.html@jinja2-trunk-r15341 admin.html] template
     520is similar to the search.html page in that it extends the layout.html:
    515521{{{#!html+jinja
    516522# extends "jlayout.html"
    … …  
    543549}}}
    544550
    545 //See [1df4e05c/cboos.git] for the full conversion of admin.html -> jadmin.html and admin_logging.html -> jadmin_logging.html.//
    546 
     551//See [1df4e05c/cboos.git] for the initial full conversion of admin.html -> jadmin.html and admin_logging.html -> jadmin_logging.html)//
    547552
    548553I omitted the discussion of the