Navigation Bar Add-On

<--
   Contributions to this add-on are appreciated. Please update the contrib page at
   http://twiki.org/cgi-bin/view/Plugins/NavBarAddOn or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/NavBarAddOnDev.
   If you are a TWiki contributor please update the add-on in the SVN repository.
-->

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.

<--Tabs optionally may have pulldown menus.-->

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.

<--A tab may have a pulldown menu, which is defined by a nested bullet list.-->

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%

<-- commented out until pulldowns are implemented: 

 

 

 Pulldown 1 of tab 3
 
 Pulldown 2 of tab 3
 
 Pulldown 3 of tab 3
 
 
-->

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)
tab_active_style	Style of active tab, overloading inactive tab style	NAVBARADDON_TAB_ACTIVE_STYLE setting
tab_inactive_style	Style of inactive tab	NAVBARADDON_TAB_INACTIVE_STYLE setting
navbar_style	Style of navigation bar	NAVBARADDON_NAVBAR_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

<-- commented out until pulldowns are implemented:




 pulldown_style 
 Style of pulldown 
 NAVBARADDON_PULLDOWN_STYLE setting 


 pulldown_link_style 
 Style of pulldown link 
 NAVBARADDON_PULLDOWN_LINK_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:

%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%

<-- actual bullet list, use when pulldowns are implemented: 

 %ICON{home}% Home
 
 Goals
 
 Projects 

 Project statistics
 
 Create new project
 
 
 Tasks 

 Task statistics
 
 Create new task
 
 
 Meetings
 
 Statistics
 
-->

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;

<-- 

 Style of pulldown: 

 Set NAVBARADDON_PULLDOWN_STYLE = 
 
 
 Style of pulldown link: 

 Set NAVBARADDON_PULLDOWN_LINK_STYLE = 
 
 
-->

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.

<--=====================================
%STARTSECTION{start}%<style type="text/css" media="all">
#navBar_%id%
{
  margin: 0;
  padding: 10px 10px 0 10px;
  background-color: #f0f0f4;
%IF{ "defined 'NAVBARADDON_NAVBAR_STYLE'" then="  %NAVBARADDON_NAVBAR_STYLE%;" else="<nop>" }%
%IF{ "defined 'navbar_style'" then="  %navbar_style%" else="<nop>" }%
}
#navBar_%id% ul
{
  list-style: none;
  margin: 0;
  padding: 0;
}
#navBar_%id% ul li
{
  float: left;
  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;
%IF{ "defined 'NAVBARADDON_TAB_INACTIVE_STYLE'" then="  %NAVBARADDON_TAB_INACTIVE_STYLE%;" else="<nop>" }%
%IF{ "defined 'tab_inactive_style'" then="  %tab_inactive_style%" else="<nop>" }%
}
#navBar_%id% ul li a,
#navBar_%id% ul li a:link,
#navBar_%id% ul li a:visited {
  display: block;
  margin: 0;
  padding: 2px 10px;
  color: #222255;
  text-decoration: none;
  border-width: 0px;
  border-style: none;
%IF{ "defined 'NAVBARADDON_TAB_LINK_STYLE'" then="  %NAVBARADDON_TAB_LINK_STYLE%;" else="<nop>" }%
%IF{ "defined 'tab_link_style'" then="  %tab_link_style%" else="<nop>" }%
}
#navBar_%id% ul li a:hover,
#navBar_%id% ul li a:active {
  display: block;
  margin: 0;
  padding: 2px 10px;
  color: #000022;
  text-decoration: none;
  border-width: 0px;
  border-style: none;
  background-color: #f0f0ff;
%IF{ "defined 'NAVBARADDON_TAB_HOVER_STYLE'" then="  %NAVBARADDON_TAB_HOVER_STYLE%;" else="<nop>" }%
%IF{ "defined 'tab_hover_style'" then="  %tab_hover_style%" else="<nop>" }%
}
</style>
<script type="text/javascript">
 $(document).ready(function () {
  $("#navBar_%id%").children( 'ul' ).children( 'li' ).each( function( index ) {
    var topic = $(this).find('a').attr('href').replace( /.*\//, '' );
    if( %IF{ "defined 'active'" then="topic=='%active%' || " }% topic=='%BASETOPIC%' ) {
      var activeStyle = "background-color: #ffffff; border-color: #dddddf;";
%IF{ "defined 'NAVBARADDON_TAB_ACTIVE_STYLE'" then="    activeStyle=activeStyle+'%NAVBARADDON_TAB_ACTIVE_STYLE%;'" else="<nop>" }%
%IF{ "defined 'tab_active_style'" then="    activeStyle=activeStyle+';%tab_active_style%'" else="<nop>" }%
      var styleArr = activeStyle.split( / *; */ );
      for( i = 0; i < styleArr.length; i++) {
        var keyVal = styleArr[i].split( / *: */ );
        if( keyVal[0].length>0) {
          $(this).css( keyVal[0], keyVal[1] );
        }
      }
    }
  });
 });
</script>
<div id="navBar_%id%">%ENDSECTION{start}%

=========================================-->

<--=====================================
%STARTSECTION{end}%<div style="clear: both"></div>
</div>%ENDSECTION{end}%

=========================================-->

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:	<-- versions below in reverse order -->
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