Changes between Version 2 and Version 3 of TracInterfaceCustomization

Timestamp:

Sep 5, 2013, 10:55:41 AM (11 years ago)

Author:

trac

Comment:

--

TracInterfaceCustomization

@@ -1 +1 @@
 = Customizing the Trac Interface =
 [[TracGuideToc]]
+[[PageOutline]]
 
 == Introduction ==
@@ -15 +16 @@
 
 === Logo ===
-Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs` and "`common/`" for the common ones).
+Change the `src` setting to `site/` followed by the name of your image file.  The `width` and `height` settings should be modified to match your image's dimensions (the Trac chrome handler uses "`site/`" for files within the project directory `htdocs`, and "`common/`" for the common `htdocs` directory belonging to a Trac installation). Note that 'site/' is not a placeholder for your project name, it is the actual prefix that should be used (literally). For example, if your project is named 'sandbox', and the image file is 'red_logo.gif' then the 'src' setting would be 'site/red_logo.gif', not 'sandbox/red_logo.gif'.
 
 {{{
@@ -26 +27 @@
 
 === Icon ===
-Icons should be a 16x16 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.
+Icons should be a 32x32 image in `.gif` or `.ico` format.  Change the `icon` setting to `site/` followed by the name of your icon file.  Icons will typically be displayed by your web browser next to the site's URL and in the `Bookmarks` menu.
 
 {{{
@@ -40 +41 @@
 }}}
 
+Should your browser have issues with your favicon showing up in the address bar, you may put a "?" (less the quotation marks) after your favicon file extension. 
+
+{{{
+[project]
+icon = /favicon.ico?
+}}}
+
 == Custom Navigation Entries ==
 The new [mainnav] and [metanav] can now be used to customize the text and link used for the navigation items, or even to disable them (but not for adding new ones).
 
-In the following example, we rename the link to the Wiki start "Home", and hide the "Help/Guide". We also make the "View Tickets" entry link to a specific report .
+In the following example, we rename the link to the Wiki start "Home", and hide the "!Help/Guide". We also make the "View Tickets" entry link to a specific report .
 {{{
 [mainnav]
@@ -55 +63 @@
 See also TracNavigation for a more detailed explanation of the mainnav and metanav terms.
 
-== Site Appearance ==
+== Site Appearance == #SiteAppearance
 
 Trac is using [http://genshi.edgewall.org Genshi] as the templating engine. Documentation is yet to be written, in the meantime the following tip should work.
 
 Say you want to add a link to a custom stylesheet, and then your own
-header and footer.  Create a file {{{/path/to/env/templates/site.html}}} or {{{/path/to/inherit/option/templates_dir/site.html}}}, with contents like this:
+header and footer. Save the following content as `site.html` inside your projects `templates/` directory (each Trac project can have their own `site.html`), e.g. {{{/path/to/env/templates/site.html}}}:
 
 {{{
@@ -90 +98 @@
 </html>
 }}}
-Note that this references your environment's `htdocs/style.css`.
-
-Example snippet of adding introduction text to the new ticket form (hide when preview):
-
-{{{
-#!xml
+
+Those who are familiar with XSLT may notice that Genshi templates bear some similarities. However, there are some Trac specific features - for example `${href.chrome('site/style.css')}` attribute references a CSS file placed into 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-config|[trac] htdocs_location]] configuration setting.
+
+`site.html` is one file to contain all your modifications. It usually works using the `py:match` directive (element or attribute), and it allows you to modify the page as it renders - the matches hook onto specific sections depending on what it tries to find
+and modify them.
+See [http://groups.google.com/group/trac-users/browse_thread/thread/70487fb2c406c937/ this thread] for a detailed explanation of the above example `site.html`.
+A `site.html` can contain any number of such `py:match` sections for whatever you need to modify. This is all Genshi, so the [http://genshi.edgewall.org/wiki/Documentation/xml-templates.html docs on the exact syntax] can be found there.
+
+
+Example snippet of adding introduction text to the new ticket form (but not shown during preview):
+
+{{{#!xml
 <form py:match="div[@id='content' and @class='ticket']/form" py:attrs="select('@*')">
   <py:if test="req.environ['PATH_INFO'] == '/newticket' and (not 'preview' in req.args)">
@@ -104 +118 @@
 }}}
 
-If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaroud - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others:
+This example illustrates a technique of using `req.environ['PATH_INFO']` to limit scope of changes to one view only. For instance, to make changes in `site.html` only for timeline and avoid modifying other sections - use  `req.environ['PATH_INFO'] == '/timeline'` condition in `<py:if>` test.
+
+More examples snippets for `site.html` can be found at [trac:wiki:CookBook/SiteHtml CookBook/SiteHtml].
+
+Example snippets for `style.css` can be found at [trac:wiki:CookBook/SiteStyleCss CookBook/SiteStyleCss].
+
+If the environment is upgraded from 0.10 and a `site_newticket.cs` file already exists, it can actually be loaded by using a workaround - providing it contains no ClearSilver processing. In addition, as only one element can be imported, the content needs some sort of wrapper such as a `<div>` block or other similar parent container. The XInclude namespace must be specified to allow includes, but that can be moved to document root along with the others:
 {{{
 #!xml
@@ -116 +136 @@
 }}}
 
-Also note that the `site.html` (despite its name) can be put in a common templates directory - see the `[inherit] templates_dir` option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
-
-== Project List ==
+Also note that the `site.html` (despite its name) can be put in a common templates directory - see the [[TracIni#inherit-section|[inherit] templates_dir]] option. This could provide easier maintainence (and a migration path from 0.10 for larger installations) as one new global `site.html` file can be made to include any existing header, footer and newticket snippets.
+
+== Project List == #ProjectList
+
 You can use a custom Genshi template to display the list of projects if you are using Trac with multiple projects.  
 
@@ -151 +172 @@
 Once you've created your custom template you will need to configure the webserver to tell Trac where the template is located (pls verify ... not yet changed to 0.11):
 
+For [wiki:TracModWSGI mod_wsgi]:
+{{{
+os.environ['TRAC_ENV_INDEX_TEMPLATE'] = '/path/to/template'
+}}}
+
 For [wiki:TracFastCgi FastCGI]:
 {{{
@@ -159 +185 @@
 For [wiki:TracModPython mod_python]:
 {{{
+PythonOption TracEnvParentDir /parent/dir/of/projects
 PythonOption TracEnvIndexTemplate /path/to/template
 }}}
@@ -179 +206 @@
    }}}
 
+== Project Templates ==
+
+The appearance of each individual Trac environment (that is, instance of a project) can be customized independently of other projects, even those hosted by the same server. The recommended way is to use a `site.html` template (see [#SiteAppearance]) whenever possible. Using `site.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.
+
+With that word of caution, any Trac template may be copied and customized. The default Trac templates are located inside the installed Trac egg (`/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 `trac/htdocs` directory.
+
+However, do not edit templates or site resources inside the Trac egg - installing Trac again can completely delete your modifications. Instead use one of two alternatives:
+ * For a modification to one project only, copy the template to project `templates` directory.
+ * For a modification shared by several projects, copy the template to a shared location and have each project point to this location using the `[inherit] templates_dir =` trac.ini option.
+
+Trac resolves requests for a template by first looking inside the project, then in any inherited templates location, and finally inside the Trac egg.
+
+Trac caches templates in memory by default to improve performance. To apply a template you need to restart the server.
+
 ----
 See also TracGuide, TracIni