== Extension Point : ''INavigationContributor'' ==

||'''Interface'''||''INavigationContributor''||'''Since'''||0.9||
||'''Module'''||''trac.web.chrome''||'''Source'''||[source:trunk/trac/web/chrome.py#L67 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 [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IRequestHandler 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 [wiki:TracDev/ComponentArchitecture] and of course [wiki: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 ==

The following example adds an item to the main navigation bar, named 'sample'. It is rendered as a hyperlink ''Sample'' referencing a resource ''./sample/''. (Assume some other component implements a request handler for this resource and requests the permission 'SAMPLE_VIEW'.)

{{{#!python
from trac.core import implements, Component
from trac.web.chrome import INavigationContributor

class SampleNavigationContributor(Component):

    implements(INavigationContributor)

    # INavigationContributor methods

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

    def get_navigation_items(self, req):
        if 'SAMPLE_VIEW' in req.perm:
            yield ('mainnav', 'sample', 
                   tag.a(_("Sample"), href=req.href.sample()))
}}}

== Available Implementations ==

  * Wiki:
    * [source:trunk/trac/wiki/web_ui.py#L83 trac.wiki.web_ui.WikiModule][[br]]
      Defines the ''Wiki'' item in the main navigation bar, and the ''!Help/Guide'' item in the meta-navigation bar.
  * Timeline:
    * [source:trunk/trac/timeline/web_ui.py#L83 trac.wiki.web_ui.TimelineModule][[br]]
      Defines the ''Timeline'' item in the main navigation bar.
  * Ticketing:
    * [source:trunk/trac/ticket/web_ui.py#L144 trac.ticket.web_ui.TicketModule][[br]]
      Defines the ''New Ticket'' item in the main navigation bar. Activates that item or ''View Tickets'' for manipulating existing tickets.
    * [source:trunk/trac/ticket/query.py#L855 trac.ticket.query.QueryModule][[br]]
      Defines the ''View Tickets'' item in the main navigation bar.
    * [source:trunk/trac/ticket/report.py#L67 trac.ticket.report.ReportModule][[br]]
      Also defines a version of the ''View Tickets'' item in the main navigation bar.
    * [source:trunk/trac/ticket/roadmap.py#L351 trac.ticket.roadmap.RoadmapModule][[br]]
      Defines the ''Roadmap'' item in the main navigation bar.
    * [source:trunk/trac/ticket/roadmap.py#L554 trac.ticket.roadmap.MilestoneModule][[br]]
      Does not define any items. Activates the ''Roadmap'' item.
  * Version Control:
    * [source:trunk/trac/versioncontrol/web_ui/browser.py#L288 trac.versioncontrol.web_ui.roadmap.BrowserModule][[br]]
      Defines the ''Browse Source'' item in the main navigation bar.
    * [source:trunk/trac/versioncontrol/web_ui/changeset.py#168 trac.versioncontrol.web_ui.changeset.ChangesetModule][[br]]
      Does not define any items. Activates the ''Browse Source'' item.
    * [source:trunk/trac/versioncontrol/web_ui/log.py#56 trac.versioncontrol.web_ui.log.LogModule][[br]]
      Does not define any items. Activates the ''Browse Source'' item.
 * Search:
    * [source:trunk/trac/search/web_ui.py#L62 trac.search.web_ui.SearchModule][[br]]
      Defines the ''Search'' item in the main navigation bar.
 * Preferences:
    * [source:trunk/trac/prefs/web_ui.py#L46 trac.prefs.web_ui.PreferencesModule][[br]]
      Defines the ''Preferences'' item in the meta-navigation bar.
 * About:
    * [source:trunk/trac/about.py#L40 trac.about.AboutModule][[br]]
      Defines the ''About Trac'' item in the meta-navigation bar.
 * Authentication:
    * [source:trunk/trac/web/auth.py#L63 trac.web.auth.LoginModule][[br]]
      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 ==

 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_web_chrome.html#trac.web.chrome.INavigationContributor 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 [wiki:TracIni#trac-section 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 [wiki:TracIni#trac-section trac section of trac.ini] using ''default_handler''.