====== Index Menu ======

[[doku>plugin:indexmenu|Index Menu Plugin]]

====Examples:====  

|Root namespace. Expands all |''%%{{indexmenu>:}}%%'' |
|Current namespace. Show only current level, don't expand any nodes. |''%%{{indexmenu>.#1}}%%'' |
|Parent namespace. Show parent namespace ("uplink") and current level, don't expand any nodes. |''%%{{indexmenu>..:#1}}%%'' |
|''wiki'' namespace, expand containing namespaces, not subnamespaces.\\ Using the themed Javascript indexmenu. |''%%{{indexmenu>:wiki#1|js}}%%'' |


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

**Minimum syntax:**

  * ''**%%{{indexmenu>.}}%%**''
  * ''**%%{{indexmenu>:}}%%**''
  * ''**%%{{indexmenu>|}}%%**''

That means this ''**%%{{indexmenu}}%%**'' and this ''**%%{{indexmenu>}}%%**'' do not work.

**Basic syntax usage:**

^ Main                                                         ^ Options                                                       ^
| **%%{{%%indexmenu>ns[#n]** <sub>[ns1[#n] ns2[#n] ...]</sub>  | **%%|%%** //<sub>[js[#theme]] [tsort] ...</sub> //**%%}}%%**  |
Arguments inside ''[]'' parenthesis are optional. The ''#'' char is always required with related options.

:!: All the syntax options can be easily accessed with the indexmenu picker in the [[:edit window]] [[:toolbar]].


===== Full syntax =====

Settings **before the "|"** separator:
^Main ^Action ^Note|
^ //''ns''//     | //**Main namespace**// name. Index starts from here. Syntax complies with DokuWiki [[:namespaces#creating namespaces|namespaces]] paths.| "**.**" refers to the namespace of the page containing the indexmenu syntax and **not** to the current DokuWiki namespace context ((the namespace of the page displayed by a user who is navigating your site)) (see the **//context//** option for this feature). "**..**" or an empty value shows the root site namespace.|
^ //''#n''//             | **n** is a number that specifies how many namespace levels to display open under the //**main namespace**//.| If it's not defined then the whole tree, till the deeper node, will be open. If ''//0//'' or ''//1//'' it'll display only nodes under the main namespace. For example: "#2" will display "root:myns1:myns2" but will keep myns2 closed thus hiding "root:myns1:myns2:myns3". Optional.|
^ //''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. Syntax complies with DokuWiki [[:namespaces#creating namespaces|namespaces]].| If **n** is not defined then all namespaces are open, if ''//0//'' they are closed. "**.**" refers to the namespace of the page containing the indexmenu syntax and **not** to the current DokuWiki namespace context ((the namespace of the page displayed by a user who is navigating your site)) (see the **//context//** option for this feature). "**..**" or an empty value shows the root site namespace. Optional.|

Optional settings **after the "|"** separator (separated by spaces):
^Option ^Action ^Note|
^ ''js'' \\ undo: ''nojs''          | JavaScript render method: the index is an expandable tree menu. Without the ''js'' option DokuWikis index renderer is used | Without //**n**//, all nodes are open, with it, nodes are open till //**n**// level.|
^ //''#theme''// \\ undo: ''#default''          | 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**// e.g. //**js#tango**// |
| Next options are available with or without //**js**// option. |||
^ ''navbar'' \\ undo: ''nonavbar''         | The tree opens itself automatically at the current page namespace. Useful in a navigation sidebar.| Without //**js**// option, the indexmenu page is never cached (just like the default DokuWiki index page) and the DokuWiki loading could be slower depending on the amount of child nodes displayed. |
^ ''context''  \\ undo: ''nocontext''   | [[:namespaces#creating namespaces|Relative]] //**main namespace**// and //**optional namespaces**// will refer to the current DokuWiki namespace context ((the namespace of the page displayed by a user who is navigating your site)) instead of to the namespace of the page containing the indexmenu syntax. Useful in a navigation sidebar.| The indexmenu page is now never cached so the DokuWiki loading could be slower depending on the amount of child nodes displayed (In //**js**// mode, when a lot of nodes are usually displayed, the //''max''// option is recommended). It automatically enable the //**nocookie**// option.|
^ ''tsort''   \\ undo: ''notsort'' | Sort (only) pages by title. | Useful when [[config:useheading]] is on. By default namespaces are **not** sorted, you need the **//nsort//** option for this.|
^ ''dsort''   \\ undo: ''nodsort''  | Sort (only) pages by date creation (first the oldest). | By default namespaces are **not** sorted, you need the **//nsort//** option for this.|
^ ''msort[#meta]''   \\ undo: ''nomsort''  | Sort (only) pages by a custom [[:devel:metadata]] information. Without the ''#meta'' parameter, i.e. ''msort'', it looks for the custom sorting number specified with the ''%%{{indexmenu_n>N}}%%'' syntax  (see the below [[.indexmenu#metadata tag syntax]]).\\ With ''#meta'' parameter you can refer to the [[:devel:metadata#data structure|meta data structure]] (Array values are managed through the ":" separator, for example: ''msort#date:modified''). |By default, pages without metadata tag are sorted by page name (the default DokuWiki way), but you can override this behaviour adding also the tsort or dsort option in the indexmenu syntax. By default namespaces are **not** sorted, you need the **//nsort//** option for this.|
^ ''hsort''   \\ undo: ''nohsort'' | Sort the headpages as defined by config setting [[config:startpage]] to the top |msort overrules hsort |
^ ''rsort''   \\ undo: ''norsort'' | Reverse the sorting of pages (change between ascending and descending). |By default namespaces are **not** sorted, you need the **//nsort//** option for this. |
^ ''nsort''   \\ undo: ''nonsort'' | Also sort namespaces according to page sort options but grouped separately. | To use in //addition// to the above sort options. tsort, dsort, msort, hsort apply only for namespaces when using [[#namespaces_title_and_link_headpages|headpages]]. rsort is applicable always together with nsort.  |
^ ''nons''   \\ undo: ''ns''  | Exclude namespaces nodes from index. It shows only the pages. | Without **//js//**, the closing **//n//** namespace option prevents to display nodes below the **//n//** namespace level.|
^ ''nopg''  \\ undo: ''pg''  | Exclude pages nodes from index. It shows only the namespaces. | All namespace nodes will link to the start pages (as defined by [[config:startpage]] setting) |
^ ''skipfile[+|=]/regexp/'' | Skip files matching the regexp. | ''skipfile**+**/../'' skips files defined with this regexp additional to [[#skip_files_in_index|global skip]] config. ''skipfile**=**/../'' replace the global skip config with regexp from this syntax. See the global config explanation for some regexp [[#skip_namespaces_in_index|examples]].|
^ ''skipns[+|=]/regexp/'' | Skip namespaces matching the regexp. | Just like skipfile, but [[#skip_namespaces_in_index|namespaces]].|
| Next options are //only// available with //**js**// option. |||
^ ''max#n//[#m]//'' \\ undo: ''nomax''  | If initially closed, the node at //**n**// level will retrieve all its child nodes through the AJAX mechanism when opened for the first time. Optionally, the nodes after the //**n**// level can be retrieved with AJAX every //**m**// sublevels instead of in one go.| It affects the server loading and speeds up the loading of pages in DokuWiki with an high amount of pages. It works only in //**js**//. Cookie are automatically disabled, just like with //**nocookie**//. |
^ ''maxjs#//n//''  \\ undo: ''nomaxjs''   | 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**// |
^ ''id#[random|ns|//number//]''   \\ undo: ''id#random''     | [[wp>HTTP_cookie|Cookie]] Identifier for a js indexmenu where the previously opened/closed nodes by a user are stored. | Useful when a page is uncached and you like the tree state is stored in cookie. (See //**nocookie**// for disabling cookies.)  Default the option ''//id#random//'' is active, also when the option is not specified in the syntax. You can apply self a number as unique identifier for your indexmenu  ( e.g. ''//id#20//'' ) or let generate a number unique for requested namespace with ''//id#ns//''. 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. Tree state storage with cookie only in //**js**// |
^ ''nocookie''  \\ undo: ''cookie'' | Disable [[wp>HTTP_cookie|cookies]]. 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. | Tree state storage with cookie only in //**js**//|
^ ''noscroll''   \\ undo: ''scroll''    | Disable the JavaScript scrolling feature when it doesn't fit the container width. It could solve visualization problems. | It works only in //**js**//|
^ ''notoc''  \\ undo: ''toc''        | Disable the TOC-preview feature. | ToC preview only available in //**js**//|
^ ''nomenu''  \\ undo: ''menu''       | Disable the contextmenu feature. | Context menu only available in //**js**//|




====== Configuration options======

Indexmenu is fully configurable from [[plugin:config|Configuration Manager]]. Options are explained in the below sections.

==== Default options=====
Default options let you define settings that are applied to all the indexmenu indexes included in pages. To undo any syntax option, use the inverse version of the option. Normally that option is the same but with or without ''no..''. See the table above for all undo options.

==== Only admins ====

It prevents no-admin users from inserting indexmenu trees, removing every indexmenu syntax in the page. It affects only the edit mode, so that standard users are still able to view indexmenu tree in a page edited by admins.

This is useful to deny to insert indexmenu trees to your users, but pay attention that if you let them to edit a page containing an indexmenu tree inserted by the admin, this tree will be removed as soon as a standard user saves the page.


==== ACL Cache ====

Optimize the cache of indexmenu according to ACLs and prevents to display unauthorized nodes.

The choice of the method affects only the visualization of nodes on the indexmenu tree, not the page authorizations. The **Groups** option is the default setting.
  * **None**: Standard. It is the faster method and it does not create further cache files, but the nodes with denied permission could be showed to unauthorized users or vice versa. Recommended when you don't deny pages access by ACL or you don't care how the tree is displayed or you use the %%~~NOCACHE~~%% syntax in the indexmenu page.
  * **User**: Per-User login. Slower method and it creates a lot of cache files (depending on the amount of your DokuWiki site users, so for sites with few users it's not a problem), but it always hides correctly denied pages. Recommended when you have page ACLs that depend on users login.
  * **Groups**: Per-groups membership. Good compromise between the previous methods, but in case that you deny pages read ACL to a single user login, he could anyway displays that nodes in the tree. Recommended when your whole site ACLs depend on groups membership.

If wrongly set, this option could display to a group of users (ie. the anonymous user) the cached tree of another group (ie: the admin user), thus displaying randomly different trees containing less or more (un)authorized nodes.

There are also important issues in [[.:indexmenu#about ACLs]] and [[.:indexmenu#about_empty_namespaces]] that affects trees limited by ACLs.


==== Namespaces title and link (headpages) ====

== Titles for page headings ==

First of all, if you want that the whole tree displays the heading title of pages instead of their name, you need to set the config setting [[config:useheading]] on in the general configuration of the wiki. Indexmenu will show page titles when useheading is 'always' or 'navigation'.

== Title for namespaces headings ==

Next, if you want that the namespace nodes display a heading title instead of the namespace name, you need to select the page from which these are retrieved with the config option ''headpage''.

Every namespace will retrieve its title from the heading title of that page, called headpage, and will be linked directly to it. No longer you can open the node by clicking the header (in the js version you can still use the plus before namespace).

You can choose a name for the page from which retrieve the title or use a self defined value:

^Value  ^Page  ^Example ^
|**any value** | The page inside the namespace | public(ns):myvalue(page) |
|**:inside:** | a page with the same name of namespace, beneath the namespace | public(ns):public(page) |                                                                               
|**:same:** | a page with the same name of namespace, at the same level of the namespace | public(page) <=> public(ns) |
|**:start:** | the global [[config:startpage|start]] page name inside the namespace| public(ns):start(page) |

You can specify more than one option using "," as separator. For every namespace, every value will be checked till the first existent headpage is found.

== Hide headpages in tree ==

To get a better visualization you could use the ''hide_headpage'' option, that hides headpages, such as defined by config ''headpage'', in the rendered indexmenu tree.


==== Page index ====

When this option is not empty, the DokuWiki default [[:index]] page is replaced with a custom page, which you can fill yourself. For example you can add the indexmenu tree of your site.

Set this option with a DokuWiki page ID (i.e: ''tools:index''), then create the page (i.e: ''tools:index'') and put inside it an indexmenu syntax like this:
<code>
{{indexmenu>..|navbar}}
</code>
or
<code>
{{indexmenu>..|js navbar nocookie}}
</code>
You may also want to hide this page in any indexmenu trees with the [[.:indexmenu#skip files in index]] option.


==== Empty message ====

You can show a custom message in place of the menu tree if it can not be rendered (i.e namespace doesn't exist)

The alias **%%{{ns}}%%** is a shortcut for the requested namespace.

Message supports the wiki syntax, so it's fully customizable. Don't use HTML code.


==== Skip Namespaces in Index ====

The configuration setting ''skip_index'' let you globally hide namespaces (and their pages) in your indexmenu trees.

Just fill this option with the ids of namespaces to skip using [[http://www.php.net/manual/en/reference.pcre.pattern.syntax.php|Regular Expression]].\\ 
:!: Till V4.5, a namespaces full path has to be declared as a file system path (i.e.: "mydir/mysubdir") instead of DokuWiki IDs.

There are also some issues [[.:indexmenu#About empty namespaces]] that should be read. 

**Simple examples:**\\
Skip any namespace whose ID contains the word ''copyright'' or ''privatens:users''. Attention: ''allprivatens:usersmich'' will be also matched
<code>
/(copyright|privatens:users)/
</code>
Skip the namespace whose ID is exactly ''myusers:spaces''. Here the characters ''^'' and ''$'' marks the start and the end of the matched string.
<code>
/^myusers:spaces$/
</code>


==== Skip Files in index====

This configuration option ''skip_file'' let you to globally hide one or more pages in your indexmenu trees.
Just fill this option with the ids of pages to skip using [[http://www.php.net/manual/en/reference.pcre.pattern.syntax.php|Regular Expression]].\\ 
:!: Till v4.5, pages are checked as DokuWiki text files (i.e.: start.txt). A page full path have to be declared as a file system path (i.e.: "mydir/start.txt") instead of DokuWiki IDs.

There are also some issues [[.:indexmenu#About empty namespaces]] that should be read.

<WRAP center round info>
The following pages are excluded from appearing in index menus:
  * topheader : content to include above the navbar
  * header : content include below the navbar but above the page content
  * contentheader : content to include above the page content
  * contentfooter : content to include below the page content
  * sidebarheader : content to include above the left sidebar content
  * sidebar : content to include in the left sidebar
  * sidebarfooter : content to include below the left sidebar content
  * rightsidebarheader : content to include above the right sidebar content
  * rightsidebar : content to include in the right sidebar
  * rightsidebarfooter : content to include below the right sidebar content
  * footer : content to include in the footer
  * bottomfooter : content to include below the footer

</WRAP>




==== Show sort ====

If you sorted a page with the [[.:indexmenu#metadata tag syntax]], a short blob message at the top of page will display its sort number.

The message is displayed **only** to wiki admins when they view the page.