Edgewall Software

Version 6 (modified by anonymous, 18 years ago) ( diff )

Trac User Interface Guidelines

No, these aren't real guidelines yet, but we hope they eventually emerge from this document.

This document is an analysis and a proposal initially written by ChristopherLenz, and is open to comments and suggestions from the community.

Current Situation

While the navigation interface provided by Trac 0.7 is in general clean and minimalistic, some problems of redundancy and inconsistency are starting to surface. The goal of this proposal is to clean-up and unify the navigation interface, and ultimately to establish guidelines for how Trac modules should hook into the navigation, so that they integrate nicely with the rest of the system.

Trac currently provides the following navigational elements:

  1. Project link: The project logo in the top left corner of every page
  2. Quick search: The search box in the top right corner of every page
  3. Meta navigation: The horizontal list of links just above the main navigation bar
  4. Main navigation: Primary means for switching between modules (Wiki, Timeline, Browser, etc)
  5. Module navigation: Often rendered as horizontal list of links directly beneath the main navigation bar.
  6. Local navigation: Navigational elements specific to the page currently being viewed. One example is the "toolbar" in the browser modules, another example are the "This report" links in the report module.
  7. Help links: Links to help documents (Wiki pages, actually) relevant to the page currently being viewed
  8. Alternate formats: Links to alternate formats of the current page, such as the RSS feed for the timeline, or the comma-delimited text option for a report
  9. Footer links: Links to Edgewall and Trac

Of this list, items 1, 2, 3, 4 and 9 can together be referred to as the Global Navigation. The global navigation obviously should never change between different modules. Technically, it is generated by the templates header.cs and footer.cs, which are included at the top and bottom of every module template, respectively.

The module- and/or page-specific navigation elements can together be referred to as "Context Navigation". However, they are currently not clearly defined, however, and their use is not consistent throughout the different modules. Let's look at a couple of examples:


In the Wiki, the module navigation (item 5 in the list above) contains the links "Start Page", "Title Index", "Recent Changes" and "Show/Hide History". These links are available independently of whether a page is being viewed or edited. While the first three of these links are "real" module navigation links (the result of activating one of those links is independent of which page of the module is currently being viewed), the fourth is actually page-specific, and is thus a local navigation link.

Also, when adding an attachment to a wiki page, the module navigation goes away. When viewing an attachment, the module navigation is even replaced with what semantically is really a "local" (per-page) navigation, showing the links "View as Text" and "Download File". The first is really an alternate format and should be moved there (item 8 in the list above) for consistency.


While browsing a directory, the module navigation is empty. The local navigation contains a form that allows switching to a different revision by entering the revision number.

When a file is being viewed, the links "Revision Log", "View as Text" and "Download File" are added to the local navigation. In addition, however, those same links also get added to the module navigation (see #431). The same problem exists in the revision log of a file, where the "View Latest Revision" is added both to the local navigation and to the module navigation.


When viewing the list of available reports, two module navigation links are available: "New Report" and "Report Index". Both remain available when opening a specific report, but three local navigation links are added "Edit", "Copy" and "Delete". These local navigation links are rendered differently to the local toolbar in the browser module, namely as a boxed horizontal list in front of the module navigation, prefixed by "This report" (see also #391). When creating or editing a report, only "Report Index" remains available.

There is an additional aspect that has not been considered yet: action-type links. For example, any Wiki page offers two form buttons beneath the content for adding attachments and editing the page. These are only forms so that they are rendered as buttons, and technical could just as easily be plain links (AFAICT). But what makes the editing of a Wiki page any different from the editing of a report, what makes adding an attachment to a Wiki page or ticket any different from adding a new report? Nothing, I believe. At least nothing that should be a concern to the user.


As noted in the introduction, the navigation story in Trac is inconsistent especially when it comes to differentiating between module navigation and local navigation (and in some cases, both of these are also mixed up with the alternate formats navigation). In addition, there is the problem of differentiating between purely navigational links, and action triggers.

Possible Solutions

It is obvious (I hope) that there is a need to fix the inconsistencies in the navigation. Apart from layout details (such as the different look of local navigation links in the browser than in the reports module), there are a basically two drastically different options:

  1. Draw a strong line between module-level and page-level navigation links. Develop a layout that helps the user understand the conceptual difference, so that she can learn to automatically look at the right place when searching for a specific link.
  2. Merge module-level and page-level navigation, as the conceptual difference may not be clear to the occassional user. More places to look at searching for navigational elements means more confusion/frustration with using Trac.

I'm tending towards the first approach, because the recent emergence of visually distinct local navigation elements probably did happen for a reason. In addition, I'd like to see us merging the action triggers with the local navigation, as well as moving all alternate format links into the corresponding navigation element.

Other opinions?

Excellent topic. From a configuration managers point-of-view, I would like to setup a project-specific hierarchical "directory-tree" of Wiki pages (=folders). This should be done with trac-admin (or similar). Then each tree entry (=folder) should be simply converted into some navigation menu in a standard place… I would prefer a vertical 'menu bar' to the left.

The current flexibility of trac Wiki and having a start-page and a title-index is ok, but is a bit tedious to create and a standard navigation layout would be beneficial if users switch between different trac sites.

Attachments (1)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.