[[PageOutline(2-5,Contents,pullout)]]

= Add custom items to main and meta navigation bar

{{{#!box info
**Notice:** The functionality provided by this plugin has been added to the Trac core in [trac:milestone:1.3.2]. See [trac:#11317]. You should uninstall the plugin and modify your configuration when upgrading to Trac 1.3.2 or later.
}}}

== Description

Starting with release 0.11, Trac allows existing items in the main and meta navigation bar menu items to be [TracInterfaceCustomization#CustomNavigationEntries customized], however it does not allow custom items to be added. This plugin allows you to add custom items ("buttons") to both the main and the meta navigation bar. Item name, title and URL can be specified in trac.ini, as well as an optional permission the user is required to have to see the item.

See also: MenusPlugin, TracTabPlugin.

== Bugs/Feature Requests

Existing bugs and feature requests for NavAddPlugin are 
[report:9?COMPONENT=NavAddPlugin here].

If you have any issues, create a 
[/newticket?component=NavAddPlugin new ticket].

[[TicketQuery(component=NavAddPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:navaddplugin here].

== Source

You can check out NavAddPlugin from [/svn/navaddplugin here] using Subversion, or [source:navaddplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Configuration

Enable in your `trac.ini` file with:
{{{#!ini
[components]
navadd.* = enabled
}}}

All configuration settings are to be kept in a section called `[navadd]` in `trac.ini`. The basic syntax is:

 `add_items = <item>,<item>,...`:: comma-separated list of items that will be added; only items that are listed here will be processed.

'''Note''': All items need to be in lowercase. If you use any uppercase character it will not work.

And then for each item:
 `<item>.title = <title>`:: the name (title) of the button
 `<item>.url = <url>`:: the URL the button should link to; please note that TracLinks syntax is not supported here yet
 `<item>.perm = <permission>`:: an optional permission that a user needs to have in order to see the button.   If unspecified, then all users will see the button.
 `<item>.target = <navbar_name>`:: the name of the navigation bar the button should be added to; only `mainnav` and `metanav` have been tested so far, other names probably work as well.

This is the configuration I use on [http://madwifi-project.org madwifi-project.org] to add a link to the imprint in the meta navigation bar, and a link to our download section on sf.net in the main navigation bar:

{{{#!ini
[navadd]
add_items = imprint,download
imprint.title = Impressum/Imprint
imprint.url = wiki/Impressum
#imprint.perm = WIKI_VIEW
imprint.target = metanav
download.title = Download
download.url = http://sourceforge.net/project/showfiles.php?group_id=82936&amp;package_id=85233
#download.perm = WIKI_VIEW
download.target = mainnav
}}}

The formats for the `url` parameter are the same as for the `href` parameter described at TracNavigation#Notes.

== Ordering of buttons

Buttons which are added with this plugin can be ordered in the usual way, ie by specifying the actual order in section `[trac]`, keywords `mainnav` and `metanav` in TracIni. See TracNavigation#nav-order.

Let's assume that you add a button `Download` to your main navigation bar (same as in the configuration example above), and you want it to appear right after the `Wiki` button. The configuration then looks like (Trac < 1.2):

{{{#!ini
[trac]
mainnav = wiki,download,timeline,roadmap,browser,tickets,newticket
}}}

For Trac >= 1.2, the same configuration is:
{{{#!ini
[mainnav]
wiki = 1
download = 2
timeline = 3
roadmap = 4
browser = 5
tickets = 6
newticket = 7
}}}


== Recent Changes

[[ChangeLog(navaddplugin, 3)]]

== Author/Contributors

'''Author:''' [wiki:otaku42] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''