Navigation Bar Add-On

Overview

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.

Usage

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:

%STARTINCLUDE%
%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" }%
%STOPINCLUDE%

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:

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:

%STARTINCLUDE%
%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" }%
%STOPINCLUDE%

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:

-----
%STARTINCLUDE%<nop>
%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" }%
<nop>%STOPINCLUDE%
-----

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:

%INCLUDE{
 "WebNavigationBar"
 active="%IF{ "defined 'NAVBAR_ACTIVE_TAB'" then="%NAVBAR_ACTIVE_TAB%" else="%BASETOPIC%" }%"
}%

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 NavBarAddOn.zip 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/NavBarAddOn.pm	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:	http://TWiki.org/cgi-bin/view/Plugins/NavBarAddOn
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/NavBarAddOnDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/NavBarAddOnAppraisal

Related:

• TWikiAddOns - other add-ons
• NavBarAddOnCreateNewNavBar - wizard to create new nav-bar topic
• NavBarAddOnExample - example nav-bar
• NavBarAddOnTemplate - template used to create new nav-bar topics