Navigation Bar Add-On

Add tabbed navigation bars to TWiki topics


Add tabbed navigation bars to TWiki topics. A navigation bar can be defined once for a set of topics and then simply included in those topics. One tab is highlighted, e.g. shown active.


There are two steps:

  • Step 1: Create a navigation bar in a web
  • Step 2: Use the navigation bar in topics of that web

1. Create Navigation Bar

A navigation bar is defined by a bullet list in a topic. Each bullet represents a tab. Bullets must be links of format [[...][...]] or <a href="...">...</a>, and must not contain any text next to the link. Link labels may contain TWikiDocGraphics icons.

The basic structure of a navigation bar topic is as follows:

%INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="demo" }%
   * [[WebHome][%ICON{home}% Home]]
   * [[PageTwo][Tab 2]]
   * [[PageThree][Tab 3]]
   * [[PageFour][Tab 4]]
%INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="end" }%

The bullet list is enclosed in two includes: On top, the "start" section is included, at the end, the "end" section. Finally, all is enclosed in STARTINCLUDE and STOPINCLUDE so that topics that include the navigation bar only include the relevant part.

Additional parameters may be specified when including the "start" section:

Parameter Description Default
id ID of navigation bar. Use only alphanumeric characters and underscore none, must be specified
active Specify which tab is active. Only needed if other topics than the current one need to be highlighted. See note below. (none)
navbar_style Style of navigation bar NAVBARADDON_NAVBAR_STYLE setting
tab_inactive_style Style of inactive tab NAVBARADDON_TAB_INACTIVE_STYLE setting
tab_active_style Style of active tab, overloading inactive tab style NAVBARADDON_TAB_ACTIVE_STYLE setting
tab_link_style Style of tab link NAVBARADDON_TAB_LINK_STYLE setting
tab_hover_style Style of tab link on hover NAVBARADDON_TAB_HOVER_STYLE setting

Note: The active tab can be set in several ways. It is set automatically if a tab link matches the current topic name. Sometimes it is desirable to highlight a tab with other topics as well, such as highlighting a Tasks tab for all task topics. This can be achieved by passing the active parameter along from the including topic to the include, such as:
  %INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="sample1" %IF{ "defined 'active'" then="active=\"%active%\"" }% }%
Alternatively, you can set it to the active parameter with fallback to the parent topic. This will automatically highlight all children, such as all task topics of the TaskTracker:
  %INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="sample2" %IF{ "defined 'active'" then="active=\"%active%\"" else="active=\"%META{ "parent" dontrecurse="on" format="$topic" }%\"" }% }%
Finally, one could define a preference setting per topic, and pass that along. Example assuming an ACTIVE_TAB setting:
  %INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="sample3" active="%ACTIVE_TAB%" }%

You can use the create new navigation bar wizard to generate a navigation bar topic. Navigation bars are based on the NavBarAddOnTemplate.

2. Use Navigation Bar

Include the navigation bar topic in each participating topic. Examples:

  • %INCLUDE{ "MyOwnNavBar" }%
  • %INCLUDE{ "MyOwnNavBar" active="MyProject" }%

A tab is automatically highlighted based on the following rules, in this order:

  • the INCLUDE has an active="..." parameter, and it's value is found in the tab link
  • the current topic name is found in the tab link

See working NavBarAddOnExample

Example Navigation Bar

Write this:

%INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="example1" %IF{ "defined 'active'" then="active=\"%active%\"" }% }%
   * [[WebHome][%ICON{home}% Home]]
   * [[ProjectGoals][Goals]]
   * [[ProjectTracker][Projects]]
   * [[TaskTracker][Tasks]]
   * [[MeetingMinutes][Meetings]]
   * [[WebStatistics][Statistics]]
%INCLUDE{ "TWiki.NavBarAddOn" section="end" }%

To get this navigation bar:

Assuming this navigation bar is defined in a "ProjectNavBar" topic you can include it in each task page like this:

%INCLUDE{ "ProjectNavBar" active="TaskTracker" }%

Embed Navigation Bar in Skin

A navigation bar can be embedded in a skin, for example in the top bar (TopMenuSkinTopBar) of the TWiki:Plugins.TopMenuSkin as in this screenhot:


This can be done as follows:

Step 1. Create a navigation bar topic, such as this WebNavigationBar:

%INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="start" id="WebNavBar" 
 navbar_style="padding: 0; background-color: #e4e9f0"
   * [[WebHome][Home]]
   * [[WebSearch][Search]]
   * [[WebNotify][Notifications]]
%INCLUDE{ "%SYSTEMWEB%.NavBarAddOn" section="end" }%

Step 2. Install TopMenuSkin version 2011-03-09 or later if you need web-specific navigation bars in the skin.

Step 3. To get web-specific navigation bars in the top bar, clone the TopMenuSkinTopBar to that web, else modify the TopMenuSkinTopBar in the TWiki web.

Step 4. TopMenuSkinTopBar modifications: Include the WebNavigationBar as follows:

 active="%IF{ "defined 'NAVBAR_ACTIVE_TAB'" then="%NAVBAR_ACTIVE_TAB%" else="%BASETOPIC%" }%"
As for layout, make sure the include is vertically aligned at the bottom of the top bar so that the active white tab blends nicely into the main topic content.

Step 5. Topics that match the tab link are highlighted automatically. If you want other topics to show a tab as active, add a NAVBAR_ACTIVE_TAB setting to the topic. For example, to highlight the Search tab, add this to WebSearchAdvanced:

   * Set NAVBAR_ACTIVE_TAB = WebSearch

Enhancement Ideas

  • Prevent wrapping of tabs, make tab overflow hidden
  • Optional pulldown menus for tabs, similar to TopMenuSkin pulldowns
  • Rounded corners using CSS/JavaScript that works with colors specified for background, line, active and inactive tabs
  • Multiple & selectable themes for tabs

Add-On Settings

The following settings document the default add-on settings. Not not change them here (they are not defined here). To overload site-wide, copy the settings to Main.TWikiPreferences, to overload on a web level. copy to the web's WebPreferences topic.

  • Style of navigation bar:
    • Set NAVBARADDON_NAVBAR_STYLE = margin: 0; padding: 10px 10px 0 10px; background-color: #f0f0f4;
  • Style of inactive tab:
    • Set NAVBARADDON_TAB_INACTIVE_STYLE = margin: 1px 12px 0 1px; border-width: 1px; border-style: solid solid none solid; padding: 0; vertical-align: middle; min-width: 60px; width: auto; text-align: center; font-size: 11pt; white-space: nowrap; border-color: #c0c0c8; background-color: #dddddf;
  • Style of active tab, overloading inactive tab:
    • Set NAVBARADDON_TAB_ACTIVE_STYLE = border-color: #dddddf; background-color: #ffffff;
  • Style of tab link:
    • Set NAVBARADDON_TAB_LINK_STYLE = margin: 0; padding: 2px 10px; color: #222255;
  • Style of tab link on hover:
    • Set NAVBARADDON_TAB_HOVER_STYLE = margin: 0; padding: 2px 10px; color: #000022; background-color: #f0f0ff;

Add-On Engine

This section defines the logic of the navigation bar so that it can be used by navigation bar topics with simple INCLUDEs. View the raw text of this topic to look under the hood.

Add-On Installation Instructions

Note: You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/NavBarAddOn.txt Plugin topic
      data/TWiki/NavBarAddOnCreateNewNavBar.txt Create nav-bar wizard topic
      data/TWiki/NavBarAddOnExample.txt Example nav-bar topic
      data/TWiki/NavBarAddOnTemplate.txt Template topic for new nav-bar topics
      lib/TWiki/Contrib/ Plugin Perl module (only needed for automated installation)
      pub/TWiki/NavBarAddOn/screenshot.gif Screenshot
    • Set the ownership of the extracted directories and files to the webserver user.

  • Test if the installation was successful:
    • The navigation bar should look like this screenshot:
    • Click on the navigation bar on top to verify that the navigation is working as expected

Add-On Info

  • Set SHORTDESCRIPTION = Add tabbed navigation bars to TWiki topics

Add-on Author: TWiki:Main.PeterThoeny
Copyright: © 2005-2011 TWiki:Main.PeterThoeny
© 2011 EmpowerEcosystems
© 2008-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Add-on Version: 2011-03-16
Change History:  
2011-03-16: TWikibug:Item6660: Changed template to not depend on format parameter of URLPARAM, which is only available in TWiki-5.1
2011-03-15: TWikibug:Item6660: Rewritten add-on using jQuery, style sheets and sectional includes; adding wizard to create new navigation bars
2005-07-15: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.3 (TWiki 5.0)
CPAN Dependencies: none
Other Dependencies: JQueryPlugin
Perl Version: 5.005
Add-on Home:


Edit | Attach | Watch | Print version | History: r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r1 - 2011-03-16 - TWikiContributor
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    TWiki All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback
Note: Please contribute updates to this topic on at TWiki:TWiki.NavBarAddOn