Extension Point : INavigationContributor

Interface	INavigationContributor	Since	0.9
Module	trac.web.chrome	Source	chrome.py​

The INavigationContributor allows extending and controlling the navigation bars. All implementations are called on each web request to collect the navigation items. Only the implementation that is also the handler of the current request will be called to determine the active navigation item to be highlighted.

Purpose

The INavigationContributor has two purposes:

• It allows a component to define navigation items to be shown in the navigation bars. By default there are two categories:
  • The main navigation bar ('mainnav') contains links to the main Trac modules like Wiki, Timeline etc.
  • The meta-navigation bar ('metanav') is usually located above the main navigation bar and contains links to Login, Preferences etc.
• It allows a component that also implements IRequestHandler to control which navigation item shall be highlighted as the active item for the handled request.
  • By default this only has a visible effect on the main navigation bar.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

Most likely, a component implementing this interface would also at least implement IRequestHandler, define at least one new navigation item and select one of these navigation items as the active item when handling a request.

However, it is also possible to select as the active item one defined by a different contributor. An implementation does not even have to define any new navigation items. (In this case it can simply return [] from get_navigation_items.)

On the other hand, an implementation could also define navigation items, but not implement IRequestHandler. (In this case get_active_navigation_item would never get called.)

Before yielding a navigation item, any required permissions should be checked.

Examples

A INavigationContributor in isolation is not very useful and usually accompanied by implementations of other interfaces. Hence the following example is best understood in context of the ComponentModuleExamples.

In Trac, there is no navigation bar item for components. The following example implementation adds such an item to the main navigation bar:

from trac.core import implements, Component
from trac.web.chrome import INavigationContributor

class ComponentModule(Component):

    implements(INavigationContributor)

    # INavigationContributor methods

    def get_active_navigation_item(self, req):
        return 'component'

    def get_navigation_items(self, req):
        if 'COMPONENT_LIST' in req.perm:
            yield ('mainnav', 'component', 
                   tag.a(_("Components"), href=req.href.component()))

(Missing here are at least implementations of IRequestHandler for the linked URL ./component that activates this item and IPermissionRequestor for the required permission COMPONENT_LIST.)

Available Implementations

• Wiki:
  • trac.wiki.web_ui.WikiModule​
    Defines the Wiki item in the main navigation bar, and the Help/Guide item in the meta-navigation bar.
• Timeline:
  • trac.wiki.web_ui.TimelineModule​
    Defines the Timeline item in the main navigation bar.
• Ticketing:
  • trac.ticket.web_ui.TicketModule​
    Defines the New Ticket item in the main navigation bar. Activates that item or View Tickets for manipulating existing tickets.
  • trac.ticket.query.QueryModule​
    Defines the View Tickets item in the main navigation bar.
  • trac.ticket.report.ReportModule​
    Also defines a version of the View Tickets item in the main navigation bar.
  • trac.ticket.roadmap.RoadmapModule​
    Defines the Roadmap item in the main navigation bar.
  • trac.ticket.roadmap.MilestoneModule​
    Does not define any items. Activates the Roadmap item.
• Version Control:
  • trac.versioncontrol.web_ui.roadmap.BrowserModule​
    Defines the Browse Source item in the main navigation bar.
  • trac.versioncontrol.web_ui.changeset.ChangesetModule​
    Does not define any items. Activates the Browse Source item.
  • trac.versioncontrol.web_ui.log.LogModule​
    Does not define any items. Activates the Browse Source item.

• Search:
  • trac.search.web_ui.SearchModule​
    Defines the Search item in the main navigation bar.
• Preferences:
  • trac.prefs.web_ui.PreferencesModule​
    Defines the Preferences item in the meta-navigation bar.
• About:
  • trac.about.AboutModule​
    Defines the About Trac item in the meta-navigation bar.
• Authentication:
  • trac.web.auth.LoginModule​
    Defines the Login and Logout items in the meta-navigation bar. (Reuses the Login item when logged in to display the logged in as … message.)

Additional Information and References

• ​API Reference
• Note that the contextual navigation bar (usually placed below the main navigation bar) uses an entirely different system.
  • Tickets: #2348

    context navigation (ctxtnav) usually needs much more logic than simply being added to a list, like the INavigationContributor does for mainnav and metanav. So the solution is now to use add_ctxnav to alter existing ctxtnavs use the ITemplateStreamFilter

• Navigation items can also be configured without a INavigationContributor:
  • The order of the items in the main and meta-navigation bars can be configured in the trac section of TracIni using mainnav and metanav.
  • Since 0.11 TracNavigation allows configuring, adding and disabling items entirely by configuration.
• The initially selected (root) navigation item is selected by the request handler / navigation contributor configured in the trac section of trac.ini using default_handler.