| | 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 | |
