%META:TOPICINFO{author="ColasNahaboo" date="1032535508" format="1.0" version="1.9"}%
---++ A navigation bar plugin

Add "Previous, Up To Contents & Next" navigation icons or text to TWiki topics.

---+++ Principle
If a topic contains the key %<nop>NAVBARINDEX%, it is parsed on save for bullet lines
starting with an existing topic name, between the lines containing the keywords %<nop>NAVBARINDEX%
and %N<nop>AVBARINDEXEND% (if present, or end of topic), which creates an index to the topics.
(named =.navbarcache= in each web). Example:
<pre>
%<nop>NAVBARINDEX%
	* <nop>FirstSubTopic optionnally followed by some text
	* <nop>SecondSubTopic with some other text
</pre>

Indexed topics then has the tag %<nop>NAVBAR% expanded into a navigation bar.
(of the form *Prev Up Next*, links to previous topic, index topic and next topic).
This tag should be normally part of the skin template, you do not have to add them to your topics by hand.

It works by maintaining a cache of indexed topics in the web, updated when saving the topics.
It thus needs for the Dec 2001 release a patch to add a plugin hook on save functionality that will
be present in the next stable release (Falll 2002): TWiki:Codev/PluginHookOnSavePatch

It was inspired by the NavPlugin, with the following features:
	* No need to add special tag in indexed pages: only once in the index
	* Faster: NavPlugin could double rendering time of big pages

The %<nop>NAVBAR% tag can accept options, of the form:
<pre>
	%<nop>NAVBAR{prefix="<i>html code...</i>" suffix="<i>html code...</i>" graphics="on"}%
</pre>
	* If NAVBAR is expanded, it will be prefixed and suffixed by the corresponding arguments, if any
	* if graphics is not specified, the navbar is in text form, as <tt>Prev Up Next</tt> links.
	  If set to on, it will use icons. Text will be striked out and icons will be greyed out
	  When there is no previous or no next topic.
	<br> *graphics* can be either the keyword =on=, or a string =XXX= that will be used to get the URL
	  of a set of images, by appending =-next,gif=, =-nexti.gif=, ....
	<br> The default, =graphics="on"= implies for instance:
	<br> =Plugins/NavbarPlugin/nav=
	* another optional argument is *size*, giving additionnal parameters to the =img= tag for 
	  html icons when you use the =graphics= parameter, to giveheight and width for faster 
	  rendering for instance.
	  Its default value (when using
	  =graphics="on"= is:
	<br> =size="width=16 height=16"=

See <nop>NavbarPluginExample at http://koala.ilog.fr/wiki/bin/view/Plugins/NavbarPluginExample

---+++ Plugin Installation Instructions
	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. 
	* (Dakar) Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section.
	* Test if the plugin is correctly installed, by
		* editing [[Sandbox.NavbarPluginExample]] and saving it (once) to generate the index
		* viewing [[Sandbox.NavbarPluginExample]] and sub-pages
	* If you want to use it, modify your skin templates to include %<nop>NAVBAR% where you want
In the standard TWiki skin, you may want to edit =templates/view.tmpl=, to add two lines:
<pre>
	%<nop>NAVBAR{prefix="&lt;div align=right>" suffix="&lt;/div>"%
</pre>
one just before the %<nop>TEXT% line, one just before the %<nop>META{"attachments"}% line

---+++ Known Issues/Limitations
	* All pages referenced in the index must be in the same web as the index page.
	* There is a possible race condition if 2 people save at the same time an index topic in the  
	  same Web. Re-saving them should do the trick.
	* Moving / Renaming the index or the topics is not handled. If anything goes wrong, just
	  removing the .navbarcache and re-saving every index topic will fix thing.
	* Creating an entry for a non-existing topic in the index, then creating the topic will
	  not work (as the file do not exists yet as the time of index save).
	  Just edit/save the index once when all topics are defined to be sure.

---+++ Plugin Info

|  Plugin Author: | TWiki:Main.ColasNahaboo |
|  Plugin Version: | v1.2 |
|  Change History: | <!-- in reverse chronological order --> |
|| *v1.2*, 20 Sep 2002: Topics with numbers in their names were not indexed |
|| *v1.1*, 12 Sep 2002: *size* parameter, better examples |
|| *v1.0*, 11 Sep 2002: Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.0 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |



---+++ Files
	* lib/TWiki/Plugins/NavbarPlugin.pm
	* data/Plugins/NavbarPlugin.txt
	* data/Plugins/NavbarPluginExample.txt
	* data/Plugins/NavbarPluginExampleFirst.txt
	* data/Plugins/NavbarPluginExampleMiddle.txt
	* data/Plugins/NavbarPluginExampleLast.txt
	* pub/Plugins/NavbarPlugin/nav-next.gif
	* pub/Plugins/NavbarPlugin/nav-nexti.gif inactive (greyed out) version.
	* pub/Plugins/NavbarPlugin/nav-prev.gif
	* pub/Plugins/NavbarPlugin/nav-previ.gif inactive (greyed out) version.
	* pub/Plugins/NavbarPlugin/nav-up.gif
	* pub/Plugins/NavbarPlugin/nav-upi.gif inactive (greyed out) version.

-- TWiki:Main.ColasNahaboo - 11 Sep 2002

%META:FILEATTACHMENT{name="nav-next.gif" attr="" comment="next topic icon" date="1031736959" path="nav-next.gif" size="123" user="ColasNahaboo" version="1.1"}%
%META:FILEATTACHMENT{name="nav-nexti.gif" attr="" comment="next topic icon (inactive)" date="1031736977" path="nav-nexti.gif" size="90" user="ColasNahaboo" version="1.1"}%
%META:FILEATTACHMENT{name="nav-prev.gif" attr="" comment="previous topic icon" date="1031736998" path="nav-prev.gif" size="125" user="ColasNahaboo" version="1.1"}%
%META:FILEATTACHMENT{name="nav-previ.gif" attr="" comment="previous topic icon (inactive)" date="1031737013" path="nav-previ.gif" size="119" user="ColasNahaboo" version="1.1"}%
%META:FILEATTACHMENT{name="nav-up.gif" attr="" comment="up / index icon" date="1031737035" path="nav-up.gif" size="120" user="ColasNahaboo" version="1.1"}%
%META:FILEATTACHMENT{name="nav-upi.gif" attr="" comment="up / index icon (inactive" date="1031752692" path="nav-upi.gif" size="115" user="ColasNahaboo" version="1.1"}%
