====== Index Menu Plugin ====== 

This plugin allows you to insert a customizable index or a list of pages starting from a specified namespace.  It should be useful in DokuWiki sites where pages are organized by namespaces.

====== Syntax ======

Arguments inside "[]" parenthesis are optional:

^Main ^Options |
|**%%{{%%indexmenu>ns[#n]** <sub>[ns1[#n] ns2[#n] ...]</sub> |**%%|%%** //<sub>[js[#theme]] [tsort] ...</sub> //**%%}}%%**|

Settings before the "|" separator:

^Main ^Action ^Note|
^ //''ns''//     | //**Main namespace**// name. Index starts from it. | "**.**" refers to the namespace of the indexmenu page (**not the current page displayed by a user who is navigating your site**); ".." or an empty value shows the root site namespace; ".:myns" is the myns namespace inside current namespace of the indexmenu page. |
^ //''n''//             | It's a number which specifies how many subnamespaces to display. With the //**js**// option it means at which level the tree has to be open| Optional; it can be used together with //**nons**//. If it's not defined then all namespaces are open, if ''0'' or ''1'' they are closed.|
^ //''ns1[#n] %%...%% nsn[#n]''// | A list of optional namespaces inside the //**main namespace**//. Every namespace will be opened or closed at the specified //**n**// level. | Optional. It can be used together with //**nons**//. If **n** is not defined then all namespaces are open, if ''0'' they are closed.|

Settings after the "|" separator:
^Option ^Action ^Note|
^ ''js''          | JavaScript render method: the index is an expandable tree menu. | Optional; without //**n**//, all nodes are open, with it, nodes are open till //**n**// level.|
^ ''navbar''          | The tree opens itself automatically at the current page namespace. Useful in a navigation sidebar.| It works with or without //**js**// option. Without //**js**// option, the indexmenu page is never cached (just like as the default DokuWiki index page) so the dokuwiki loading could be slower depending on the amount of child nodes displayed. |
^ ''tsort''  | Sort (only) pages by title. | Useful when [[config:useheading]] is on. See the ''nsort'' option for namespaces sorting. Optional.|
^ ''dsort''  | Sort (only) pages by date creation. | See the ''nsort'' option for namespaces sorting. Optional.|
^ ''msort[#meta]''  | Sort (only) pages by a custom [[:devel:metadata]] information. Without the optional **meta** parameter, it will use the custom sorting number specified with the %%{{indexmenu_n>N}}%% syntax (read below for more info). **meta** should refer to the [[:devel:metadata#data structure]] (Array values are managed through the ":" separator, for example: "msort#date:modified). |You can use the tsort/dsort option together with msort in order to sort pages without metadata tag in a different way from the default DokuWiki one (sorted by page name). See the ''nsort'' option for namespaces sorting. Optional.|
^ ''rsort''  | Reverse the sorting of pages. | Optional.|
^ ''nsort''  | Sort also namespaces according to the previous sort options. | Optional.|
^ ''nons''  | Exclude namespaces nodes from index. It shows only the pages. | Optional. |
^ ''nopg''  | Exclude pages nodes from index. It shows only the namespaces. | Optional. |
^ ''max#n//[#m]//''  | The node at //**n**// level will retrieve all its child nodes through the Ajax mechanism. Optionally, instead of retrieve them in one time, it can retrieve them with Ajax every //**m**// sublevels.| Optional. Cookie are automatically disabled, just like with //**noocookie**//. It affects the server loading and speeds up the loading of page in DokuWiki's with an high amount of pages. It works only in //**js**// |
^ //''theme''//          | Theme name for indexmenu icons | A theme is a set of icons inside ''images'' directory as described in [[.:indexmenu#Theme tutorial]]. Admins can download and share themes in admin panel. It works only in //**js**// |
^ ''id[#random|//n//]''      | Cookie id for a js indexmenu. By default is ''random'', but you can force it to be a //**n**// fixed number ( i.e ''id#20'' ).| Useful only when you need two or more navbar tree or when a page is uncached and you don't use the //**nocookie**// option. Read the [[.:indexmenu#Js does not remember its previous state]] section. **ATTENTION:** id must be unique for every indexmenu in your DokuWiki site or you'll get strange js behaviors. It works only in //**js**// |
^ ''maxjs#//n//''   | It sets how many js tree levels to render when page loads. Remaining nodes are rendered (slightly slower) only when they are open by users, by  //**optional namespaces**// option, by cookies or by //**navbar**// option. | Default //**n**// is 1 so that it will speed up the page loading, above all with an high amount of pages. It affects only the user-client CPU speed, not the webserver load. It works only in //**js**// |
^ ''nocookie'' | By default js indexmenu remember selected,open and closed nodes by user during navigation. With this option it doesn't remember them and the tree is blocked to its start status. | It works only in //**js**//|
^ ''noscroll''     | Disable the JavaScript scrolling feature. It could solve visualization problems. | It works only in //**js**//|
^ ''notoc''        | Disable the TOC-preview feature. | It works only in //**js**//|


===== Metadata tag syntax =====
By default nodes are sorted by page name (or by title/date if you use the tsort/dsort syntax), but you can also specify a custom sort number for every page inserting a metadata tag in the pages with this syntax:
<code>
{{indexmenu_n>N}}
</code>

Where N is a number.
Then you need to use the "msort" option in your indexmenu tree syntax.

For example you can change the order of this tree:

<file>
-Root
  |_Don
  |_Van
  |_Vliet
</file>

in this way:

<file>
-Root
  |_Vliet  {{indexmenu_n>1}}
  |_Van    {{indexmenu_n>2}}
  |_Don    {{indexmenu_n>3}}
</file>

Pages without metadata information are sorted by page name if you don't use the tsort or dsort option in this way:
<code>
{{indexmenu>..#1|tsort msort}}
</code>

===== Examples =====
A sample of an indexmenu that could be used inside a navigation sidebar. Its initial status is blocked by the nocookie option, so, when the page is reloaded, it doesn't remember the open and closed nodes by the user.:
<code>
{{indexmenu>..#1|js navbar nocookie}}
</code>

Sample navigation bar where nodes after the third level are retrieved with Ajax every 2 sublevels:
<code>
{{indexmenu>..#1|js navbar max#3#2}}
</code>

Standard DokuWiki index showing only pages inside wiki:plugins and lower namespaces (max two levels):
<code>
{{indexmenu>wiki:plugins#2|nons}}
</code>

For more details, please see [[http://www.dokuwiki.org/plugin:indexmenu|here]].  Please note:  customizable javascript themes are not available on our site.