Nav Plugin

This plugin allows an author to create a set of TWiki Topic pages that together form a logical, ordered set. This could be a for a presentation/slide-show or sections of a document.

Each document set is composed of a number of individual topics and an "index" topic. To link each of these topics together, a variable named %DOCNAME% is introduced.

Based on the value of %DOCNAME%, NavPlugin finds the name of the "index" topic, and parses the contents of it to determine the respective navigation links. The Index lists the individual pages in the order.

If a document does not have a %DOCNAME% variable defined, the document is displayed without the navigation links.

The NavPlugin uses a simple skin (included with the plugin) for the viewing/navigation. A small JavaScript function is used to determine if the navigation icons should be displayed and to insert the correct hyperlinks.

See NavPluginDev for development discussion.

Example

See the example document set NavPluginExample.

Syntax Rules

Title Page

Start the document set with a hyperlink that forces the page to be viewed with the "nav" skin. You could do this from a Title Page.

   =<a href="NavPluginPageOne?skin=nav">Begin the example</a>=   

Index Page

Every document set needs an index page. The index page must be a valid WikiWord name that ends in Index: < SomeWikiName >Index.

The Index page contains an ordered list of TWiki pages. This list must use the bullet syntax and start with an IndexStart and IndexEnd flag in HTML comments.

<!--IndexStart-->
   * NavPluginPageOne
   * NavPluginPageTwo
   * NavPluginLastPage
<!--IndexEnd-->

The index page can be a part of the document set by putting the DOCNAME variable in it. Often, this it's useful for the Index page to double as the "Agenda" or "Table of Contents" of the presentation/document.

On each page, identify that it belongs to a document set

Each page in the document set must have the DOCNAME variable defined. It can defined in an HTML comment so that it's not visible, putting the start/end comment delimeters on the line above it and after it.

The DOCNAME should be set to the base document name, such as "NavPlugin." The plugin source code will automatically append "Index" to this name to determine the next/previous/index hyperlinks.

   <!--
   * Set DOCNAME = SomeWikiName
   -->

First and Last Pages

When you are on the first page, the "Previous" simply reloads the first page in the index. When you get to the last page, the "Next" simply reloads the last page. The TOC always takes you to the index page.

Navigation

When you are viewing with the nav skin, these icons appear at the top of the page

• : Go to previous page in the document set
• : Go to the document set index (i.e. table of contents), identified by DOCNAMEIndex
• : Go to the next page in the document set

If you are viewing with the nave skin and you want to "break-out" so that you can edit one of the pages, edit the URL and remove the ?skin=nav parameter.

NavPlugin Settings

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = This plugin allows a user to easily combine different TWiki topics into one logical document that a user can can easily navigate through "navigation" links displayed at the header and footer of each page.

Plugin Installation Instructions

• Download the ZIP file from the Plugin web (see below)
• Unzip NavPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/NavPlugin.txt	Plugin topic
  data/TWiki/NavPlugin.txt,v	Plugin topic repository
  data/TWiki/NavPluginExample*.txt	Example
  lib/TWiki/Plugins/NavPlugin.pm	Plugin Perl module
  templates/view.nav.tmpl	(skin for navigation)
  pub/Plugins/NavPlugin/*.gif	next, previous, and index images for the nav skin

• Turn on NavPlugin in TWikiPreferences.
• Test if the plugin is correctly installed, by viewing NavPlugin#NewFunctionalityTest

Known Issues/Limitations

All pages referenced in the index must be in the same web as the index page.

Plugin Info

Plugin Author:	MikeBarton, AlbertoBaez
Plugin Version:	30 Jan 2002
Change History:	30 Jan 2002: Initial version
	8 Jul 2003: MikeBarton no longer maintaining this
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.0
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/NavPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/NavPluginDev

Related Topics: TWikiPreferences, TWikiPlugins, DefaultPlugin

-- MikeBarton - 30 Jan 2002

Mike sent me an email saying:

Martin, No plans to continue maintaining the NavPlugin.

Mike

-- MartinCleaver - 08 Jul 2003