Changes between Version 8 and Version 9 of TracInterfaceCustomization


Ignore:
Timestamp:
10/05/2023 07:15:55 AM (7 months ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracInterfaceCustomization

    v8 v9  
    5656== Site Appearance
    5757
    58 Trac is using [http://jinja.pocoo.org/ Jinja2] as the templating engine. 
     58Trac is using [http://jinja.pocoo.org/ Jinja2] as the templating engine.
    5959
    6060We have put in place a number of "placeholder" in the form of "include" directives. These files don't need to exist, but if they do, their content will be processed by Jinja2 as well. As such, they can make use of other "include" directives, or any other feature of Jinja2 to generate dynamic content.
    … …  
    6363 - `site_head.html`, which can be used to add content inside the generated `<head>` element
    6464 - `site_header.html`, which can be used to **prepend** content inside the generated `<body>` element, before the standard content generated by Trac
    65  - `site_header.html`, which can be used to **append** content inside the generated `<body>` element, after the standard content generated by Trac
     65 - `site_footer.html`, which can be used to **append** content inside the generated `<body>` element, after the standard content generated by Trac
    6666
    6767Say you want to add a link to a custom stylesheet, and then your own header and footer. Save the following content as `site_head.html`, `site_header.html` and `site_footer.html` inside your projects `templates/` directory (each Trac project can have their own "placeholder" files) e.g. `/path/to/env/templates/site_head.html`:
    … …  
    9393
    9494Notice that as Jinja2 is mostly content agnostic, you are free to open some `<div>` element in the `site_header.html` file and only close it in `site_footer.html` file.
    95 Besides, as in any other Trac Jinja2 template, you can use some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overriden using the [TracIni#trac-htdocs_location-option "[trac] htdocs_location"] setting.
     95Besides, as in any other Trac Jinja2 template, you can use some Trac specific features, for example the `${href.chrome('site/style.css')}` attribute references `style.css` in the environment's `htdocs/` directory. In a similar fashion `${chrome.htdocs_location}` is used to specify the common `htdocs/` directory belonging to a Trac installation. That latter location can however be overridden using the [TracIni#trac-htdocs_location-option "[trac] htdocs_location"] setting.
    9696
    9797Example snippet of adding introduction text to the new ticket form (but not shown during preview):
    … …  
    194194== Project Templates
    195195
    196 The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use `site_{head,header,footer}.html` templates whenever possible, see [#SiteAppearance]. Using `site_{head,header,footer}.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifiations to the newer version. If not, new Trac features or bug fixes may not work as expected.
     196The appearance of each individual Trac environment, ie instance of a project, can be customized independently of other projects, even those hosted on the same server. The recommended way is to use `site_{head,header,footer}.html` templates whenever possible, see [#SiteAppearance]. Using `site_{head,header,footer}.html` means changes are made to the original templates as they are rendered, and you should not normally need to redo modifications whenever Trac is upgraded. If you do make a copy of `theme.html` or any other Trac template, you need to migrate your modifications to the newer version. If not, new Trac features or bug fixes may not work as expected.
    197197
    198198With that word of caution, any Trac template may be copied and customized. The default Trac templates are located in the Trac egg or wheel, such as `/usr/lib/pythonVERSION/site-packages/Trac-VERSION.egg/trac/templates, ../trac/ticket/templates, ../trac/wiki/templates`. The [#ProjectList] template file is called `index.html`, while the template responsible for main layout is called `theme.html`. Page assets such as images and CSS style sheets are located in the egg's or wheel's `trac/htdocs` directory.