| 60 | == Implementation details |
| 61 | |
| 62 | === Themeing |
| 63 | ==== Genshi thene |
| 64 | I'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 the following: |
| 65 | |
| 66 | Let's take the example of a simple "end user" page |
| 67 | (e.g. [source:tags/trac-1.0.9/trac/search/templates/search.html search.html]): |
| 68 | - it starts by including the layout.html page: |
| 69 | {{{#!xml |
| 70 | <xi:include href="layout.html" /> |
| 71 | }}} |
| 72 | - the [source:tags/trac-1.0.9/trac/templates/layout.html layout.html] page: |
| 73 | - defines `<py:match>` filters for transforming the content provided |
| 74 | in `<head>` and `<body>` elements |
| 75 | - then **dynamically** includes some "theme" page: |
| 76 | {{{#!xml |
| 77 | <xi:include href="$chrome.theme"><xi:fallback /></xi:include> |
| 78 | }}} |
| 79 | - by default, this will be our |
| 80 | [source:tags/trac-1.0.9/trac/templates/theme.html theme.html]: |
| 81 | - it simply defines a `<py:match>` filter on the `<body>` tag |
| 82 | (the one that will be produced by the previously applied filters, |
| 83 | i.e. the output of the `<py:match>` from the layout.html) |
| 84 | - the search.html page then provide the `<head>` and `<body>` elements |
| 85 | specific to that search page; these elements will be processed by the |
| 86 | `<py:match>`es filters defined so far in the order in which |
| 87 | they have been included (so first the ones defined in layout.html, |
| 88 | then the one for the `body` defined in theme.html) |
| 89 | |
| 90 | The scheme can be extended with more intermediate levels, |
| 91 | for example what we have for the admin panels, e.g the |
| 92 | [source:tags/trac-1.0.9/trac/admin/templates/admin_basics.html admin_basics.html] panel: |
| 93 | - it starts by including the admin.html page: |
| 94 | {{{#!xml |
| 95 | <xi:include href="admin.html" /> |
| 96 | }}} |
| 97 | - the [source:tags/trac-1.0.9/trac/admin/templates/admin.html admin.html] page |
| 98 | - defines `<py:match>` filters for `<head>` and `<body>`, |
| 99 | which in turn will produce modified `<head>` and `<body>` elements |
| 100 | - it then includes the layout.html page (see above) |
| 101 | - then it provides the `<head>` and `<body>` elements specific to that panel |
| 102 | (they will be process by the `<py:match>` filters in the order seen, so |
| 103 | first those from admin.html, then those from layout.html and finally those |
| 104 | from the dynamically included theme page |
| 105 | |
| 106 | Feel free to brush up your Genshi craft by reading ([G:GenshiTutorial#AddingaLayoutTemplate]), |
| 107 | as I just did ;-) |
| 108 | |
| 109 | So this dynamic theme template has the last say, and can theoretically re-order |
| 110 | the content generated by the previous filters any way it likes. |
| 111 | In practice (at least in our default theme.html), it's just a `<py:match once>` |
| 112 | template which appends a footer to the content of the `<body>` element produced |
| 113 | so far. |
| 114 | |
| 115 | An example of another theme page: [https://github.com/chevah/trac-bootstrap-theme/blob/master/templates/theme.html trac-bootstrap-theme's theme.html]. |
| 116 | |