!!! Namespace Plugins

%%tabbedSection
%%tab-Introduction

!! Introduction

Due to the absence of a hierarchical folder concept in JSPWiki, I am using extensively a dot syntax to group related pages together. (similar to the java package concept) 

{{{
   Zoo
   Zoo.Birds
   Zoo.Birds.Flamingo
   Zoo.Birds.Stork
}}}

! Namespace

If you quickly want to move up in the hierarchy of pages you can use the [[{Namespace}] plugin.
It breaks up a wiki page-name in pieces, and generates a set of corresponding JSPWiki links.

Thus, adding this to page {{Zoo.Birds.Flamingo}}
{{{
   [{Namespace }]
}}}
generates following markup
{{{
   [Zoo] . [Birds|Zoo.Birds] . [Flamingo|Zoo.Birds.Flamingo]
}}}   

! Namespace index

To create an alphabetical index of a namespace, use the [[{NamespaceIndexPlugin }].
It would list all pages matching a certain Namespace, or page prefix, in alphabetical order. 
Each ''branch'' in the namespace ( such as {{Zoo}} or {{Zoo.Birds}} ) will be listed with all its
''sub-pages''. The links are displayed relative to the namespace base.

Thus, adding this to page {{Zoo.Birds.Flamingo}}
{{{
   [{NamespaceIndexPlugin }]
}}}
generates following markup
{{{
  ;[Zoo]       : [Birds|Zoo.Birds]
  ;[Zoo.Birds] : [Flamingo|Zoo.Birds.Flamingo], [Stork|Zoo.Birds.Stork]
}}}   


Related plugin: [IndexPlugin]

! Namespace Taglib

To use the NamespacePlugin (and NamespaceIndexPlugin) on every page follow the instructions in the [NamespaceTags.txt] attatchment. This allows some kind of breadcrumbs on the top and some kind of children at the bottom of each page.
See examples to get an impression what I mean.

%%
%%tab-Usage

!! Usage 

! Namespace plugin

{{{
   [{Namespace }]
   [{Namespace page='Zoo.Birds.Flamingo' delimiter='.'  concat=' . ' style='background:#ccccc;'}]
   [{brushed.jspwiki.namespaceplugin.Namespace }]
}}}

* __page__ : Optional name of the page. Default is the name of the current page.
* __delimiter__ : Optional delimiting character(s) used to break up the namespace. Default is a dot (.)
* __concat__ : Optional concatenation string inserted between each namespace link.
   Default is space + delimiter + space.
* __style__ :  Optional ccs style definition.
  Default is the "namespace" css class which you can define in your jspwiki.css.

! Namespace Index plugin

{{{
 [{NamespaceIndexPlugin }]
 [{NamespaceIndexPlugin namespace='UC'  }]
 [{NamespaceIndexPlugin namespace='UC' exclude='Sandbox' itemsPerLine='1' }]
 [{brushed.jspwiki.namespaceplugin.NamespaceIndexPlugin }]
}}}

* __namespace__ : Optional root page of the namespace. Default is the name of the current page. 
  All pages displayed in the index will share the same namespace prefix.
* __delimiter__ : Optional delimiting character(s) used to break up the namespace. Default is a dot (.)
* __itemsPerLine__ : n.  Optional. Break every 'n' items on line. Default value is zero so no breaks are add.
* __include__ : Optional regular expression which specifies the pages to include. Optional.
   If needed, this parameter allows you to specify additional include rules.
* __exclude__ : Optional regular expression which specifies the pages to exclude.

%%
%%tab-Examples

!! Examples 
! Namespace

Following markup
{{{
[{brushed.jspwiki.namespaceplugin.Namespace page='Zoo.Birds.Flamingo' delimiter='.' }]
}}}
generates following output:

[{brushed.jspwiki.namespaceplugin.Namespace page='Zoo.Birds.Flamingo' delimiter='.' }]


Following markup
{{{
[{brushed.jspwiki.namespaceplugin.Namespace page='Zoo.Birds.Flamingo' delimiter='.' 
  concat=' >> ' style='background:yellow; border:1px solid silver; padding:2px;' }]
}}}
generates following output:

[{brushed.jspwiki.namespaceplugin.Namespace page='Zoo.Birds.Flamingo' delimiter='.' 
  concat=' >> ' style='background:yellow; border:1px solid silver; padding:2px;' }]

! Namespace Index Plugin

Following markup
{{{
[{brushed.jspwiki.namespaceplugin.NamespaceIndexPlugin namespace='Zoo.' }]
}}}
generates following output:

[{brushed.jspwiki.namespaceplugin.NamespaceIndexPlugin namespace='Zoo.' }]

Following markup
{{{
[{brushed.jspwiki.namespaceplugin.NamespaceIndexPlugin namespace='MySandbox' }]
}}}
generates following output:
[{brushed.jspwiki.namespaceplugin.NamespaceIndexPlugin namespace='MySandbox' }]

! Namespace Taglibs
Two screenshots as example views:
* Being on to level:
[{Image src='BreadCrumbsAndChildren.png'}]
* Being on a 'child' page:
[{Image src='BreadCrumbsAndChildren.Child2.png'}]

%%
%%tab-InstallationNotes

!! Installation notes

1) Add following entry to your {{WEB-INF/jspwiki.properties}} file when you want to use the short plugin name. 
Make sure you don't leave any spaces at the end of the property definition.
{{{
jspwiki.plugin.searchPath = brushed.jspwiki.namespaceplugin,<other class paths>
}}}
2) Copy the {{Namespace.jar}} to the {{WEB-INF/lib}} directory.
This jar contains 2 plugins: ~NamespaceIndexPlugin and Namespace.

3) Finally, restart (or reload) your web-server.

%%
%%tab-ChangeHistory

!! Change History
* v1, July 2005, [DF|DirkFrederickx] \\
* v2, with improved formatting - ref suggestion by Adler, Sep 2006, [DF|DirkFrederickx]

%%
%%tab-Discussion

!! Discussion

! Q&A -- Suggestions on v1 of plugin

- instead of creating a very formalized index (list of letters, etc), there could be an option to just do a simple list. For instance if the name space is Zoo, we would get a list with a title Zoo and then the animals:
__Zoo__

* Birds
** Flamingo
** Pelican
* Mamals
** Cow
** Cat

--[Adler]

;: That's an excellent suggestion. Indeed, it make sense for hierarchical namespaces to be able to generate this tree like structure.  Would you see this as a mixture then, of an alphabetic tree  and a hierarchical tree ? (this is not clear from your example where I would expect ''cow'' and ''cat'' in the opposite order)  --[DF|DirkFrederickx]

;: indeed, sure! IMO, it should be alphabetic order. In my example I was just concerned with the organization and forgot about the order, I'm sorry. (the other items were just luckly in order :) --[Adler]

- or, especially when you have a quite small number of pages, this could be enough (and saves a lot of space in your page)
* Birds: Flamingo, Pelican,...
* Mamals: Cat, Cow,...

;:See update of Sep 06 for an improved formatting of the output.


!!Problems

I don't understand what does this plugin do. Can you give a clearer example?

--Adler, 27-Apr-2006
;: Hmm, well, the plugin assumes the name of your pages follows a kind of namespace format; i.e. a name consisting of different parts, separated by a delimiter. The plugin interpretes the page name, and generates wiki-links to each part of the namespace. Hope this helps a bit--[DF|DirkFrederickx]

thank you for the reply, but I need an example :) Does this mean that is I call a page Zoo.Birds.page1 then somehow I'll be able to generate a list of all pages that belong to Zoo.Birds?--[Adler]

I just tried to install the plugin, but I couldn't figure out how to use it.
I create a page with a name like "Zoo.Birds"? Should I then write {{{ [{Namespace }] }}}
on this new page?
what is the link to that page? {{{[Zoo.Birds]}}}
--[Adler]

Create the page [[Zoo], [[Zoo.Birds] and [[Zoo.Birds.Flamingo]. Start each page with a call to the [Namespace Plugin], no parameters needed. You will see now on the top of each page a set of links walking you back to the higher level pages of the ''namespace''. When you want to generate a list of pages belonging the e.g. [[Zoo.Birds], use the [Index Plugin] with the include parameter. Thus, on the same page you can use the [Index Plugin] and the [Namespace Plugin] generating links backwards and forwards in the namespace tree.  Does this makes sense for you? --[DF|DirkFrederickx]

Q: I get this message: "Plugin insertion failed: Plugin failed"

A:
;:Make sure there are no blanks at the end of the properties line! Or try this:
{{{
  [{brushed.jspwiki.namespaceplugin.Namespace }]
}}}
--[DF|DirkFrederickx]

The plugin throws an NPE with the latest JSPWiki versions. I uploaded a fix so plse tryout the latest jar attachment --[DF|DirkFrederickx]

Thanks DirkFrederickx!!! It works now :) what a nice way to start the morning! --[Adler]

Q: It looks like the parameter itemsPerLine='5' in "NamespacePlugin" is not working as expected. What do I need to to?
\\
Q: How can I get rid of the bold font for the index?
\\
Q: How can I add the output of {{{ [{Namespace }] }}} to a different part of the page, than the content. I would like to have the Namespace navigation similar to the 'last visited' section.
Thanks for your effort.
\\
\\

--totalz,20080604\\
It seems like a nice plugin to try.  But it would be great if the taglib classes are included in Namespace.jar.

--alexxismachine, 20080909\\
The moving to apache (and less time than projects :-)) stopped me developing for jsp-wiki. As the first incubator release is at hand, I'm thinking about joining again. For the 2.4 version I developed the namespaces allowing to rename a namespace (as I am used to at work in confluence). 

%%
%%