Trac User Interface Guidelines

Introduction

This document is an analysis and a proposal for adding consistency between module navigation and local navigation. This proposal was drafted by ChristopherLenz and is open to comments and suggestions from the community. These guidelines aren't official.

Current Situation

While the navigation interface provided by Trac is in general clean and minimalistic, some problems of redundancy and inconsistency can be identified. 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 "Last change" in the Wiki module, another example are the "Previous / Next" links in the changeset module or ticket 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 (5. and 6.) can together be referred to as Context Navigation. However, they are currently not clearly defined and their use is not consistent throughout the different modules. Let's look at a couple of examples:

Wiki:

In the Wiki, the module navigation (item 5 in the list above) contains the links "Start Page", "Index by Title", "Index by Date" and "Last Change". 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.

Browser:

While browsing a directory or a file, the module navigation is empty. The local navigation contains a link to the Revision Log and to the Last Change for the path being browsed. There's also a form that allows switching to a different revision by entering the revision number.

View Tickets:

When viewing the list of available reports, two module navigation links are available: Available Reports and Custom Query. Both remain available when opening a specific report. However, when viewing the report list or the custom query, only the alternative view remains selectable.

Possible Solutions

For usability purposes there is a need to fix these 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 occasional user. More places to look at searching for navigational elements means more confusion and 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.

Suggestions #694 and #695 are related to the idea of a wiki hierarchy and a wiki navigation menu… —mario

---

I would like to have that tree of folders on the left or as a JS-pulldown at the top. BTW how is the menu on trac's own site created (id="proj-left") ? Ticket #332 doesn't elaborate on this.

This need not be a full blown tree-menu. One level would be great too, but like I said this should be manageable by trac-admin.

---

In addition to your nice and clear analysis of the trac navigation system, I'd like to raise an issue that I do not think you address, concerning what you call "Module" and "Local" navigation. When using trac, I feel there is a lot of inconsistency here and lots of room for improvement. It seems to me that these links/actions should be further broken down into 3 categories as opposed to the 2 that you propose:

• Module Navigation Links, for links that are useful and makes sense irrespective of whichever page we are in the module, i.e. these links do not change between module pages… for example, currently below "View Tickets" we sometimes get a "Custom Query" link, e.g. when showing a report, but not always, e.g. when displaying a ticket. But, to me it seems interesting to have the Custom Query link on every page below "View Tickets"… Furthermore, on the "Custom Query" itself, the link should not disappear, and thus be consistent with higher level navigation practices (that latter point is "fixed" now — cboos)
• Page Links, for links that make sense exclusively for this one module page, irrespective of the current mode of the page. E.g. different views of the same page.
• Page Mode Options, for actions that depend on the current page mode, such as View, Modify, … these actions are acting on this same page, and therefore should appear as appropriate. All actions should also be rendered as buttons (as active or disabled), as this implies more clearly their nature (that latter point is "fixed" now — cboos). Also, you may want in some cases to be able to display these multiple times on the same page, for convenience… such as the "Save Changes", "Cancel" options when editing a wiki page could be in 2 places, below the main textarea as well as below the previewed content (this is the case for e.g. View Differences… buttons — cboos). —mario

To follow-up on the Page Mode Options idea, I think that there should be an easy way to switch between different "aspects" of the same resource, maybe using "tabs" a la Wikipedia.

• For Wiki pages, in addition to the default article, there could be an History mode and a Discussion page (comments for wiki pages, similar to the ones we currently have for tickets). Improving upon Wikipedia, the article tab could even show the actual WikiPageName, which would answer to the feature request expressed above.
• For Ticket pages, we could as well have a View, History and eventually a SubTickets page.
• For a Changeset we could have a Discussion page as well.
• For the TracBrowser, we could integrate the Revision Log view as an History tab.

—ChristianBoos

---

One of the things I was hoping for, but haven't run across, is an easy way to edit and extend the existing navigation and page layout using Wiki pages and markup. I have been using ​SnipSnap for some time, and have only recently been looking at Trac. I really like the simplicity and features integrated into Trac, but I do miss the ability to use the built-in Wiki editing to manage my page contents. For example, SnipSnap provides 1 or more portlets, which utilize the standard wiki markup to allow a wiki to customize sidebars and other areas. If I had this capability in Trac, I could then manage and organize my wiki and the various navigation links how I see fit, without having to make changes to the *.cs files or jump through other hurdles. Would this be possible, and if so, how feasible is it with the current codebase?

—James

---

See also: TracDev/ScratchPad, #633, #10012 and keywords~=layout (the closed tickets there could be interesting for retrieving past design decisions)