====== Indexmenu plugin ======
---- plugin ----
description: Show a customizable and sortable index for a namespace.
author : Samuele Tognini
email : samuele@samuele.netsons.org
type : syntax,action
lastupdate : 2009-08-29
compatible : 2003-09-03, 2008-05-05, 2009-12-25
depends :
conflicts : indexmenu2
similar : indexmenu2, alphaindex
tags : navigation, menu, listing, namespace, ajax
sourcerepo: http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu#source_code
downloadurl: http://samuele.netsons.org/dokuwiki/media/indexmenu.zip
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=102873
----
This [[plugin]] allows you to insert a fully 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]].
Main features are:
* Fully customizable with a lot of [[.:indexmenu#syntax|flexible options]], but easy to use and configure for standard needs.
* Built-in support of Navigation features like highlighting the current location or dynamically displaying the tree of the current namespace.
* Easily themeable with prebuilt [[.:indexmenu#JavaScript themes]].
* Assign [[.:indexmenu#Namespaces title and link (headpages)]] to namespaces.
* Sortable by date,title and custom metadata information.
* AJAX support to speed up sites with many pages.
* Customizable [[.:indexmenu#The context menu|context mouse menu]] for usual namespace/page actions.
* TOC pages preview.
* [[.:indexmenu#replace_index|Replace]] the DokuWiki index.
* Hide namespaces/pages according to [[ACLs]] and plugin [[.indexmenu#skip_index|settings]].
{{http://samuele.netsons.org/dokuwiki/media/indexmenu1.jpg}} {{http://samuele.netsons.org/dokuwiki/media/indexmenu2.jpg}}
* You can test it at the playground page of the [[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu|indexmenu web site]].
* Thanks to Geir Landrö and his JavaScript [[http://www.destroydrop.com/javascripts/tree/|dTree]] menu.
* Thanks also to Roland Hellebart and his [[.:tree]] plugin for the dTree idea.
* **MANY MANY thanks to indexmenu users**, the most useful work is done by them (look at the [[.:indexmenu:discussion]] page).
* Feel free to [[.:indexmenu#development|improve]] it.
====== Donation ======
The indexmenu plugin is not sponsored by anyone but I develop and support it for free during my spare time.
If want to offer me a friendly beer (({{http://www.enjoytoz.it/images/uploads/Auld_Dubliner/tennents.jpg?60}})), you can consider to make a [[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu#donation|donation]].
====== Syntax ======
|:!: All the syntax options can be easily accessed with the indexmenu picker in the [[:edit window]] [[:toolbar]].|
^Main ^Options |
|**%%{{%%indexmenu>ns[#n]** [ns1[#n] ns2[#n] ...] |**%%|%%** //[js[#theme]] [tsort] ... //**%%}}%%**|
//Arguments inside "[]" parenthesis are optional. The "#" char is always required with related options.//
===== 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:
^Option ^Action ^Note|
^ ''js'' | JavaScript render method: the index is an expandable tree menu. | 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 the default DokuWiki index page) and the DokuWiki loading could be slower depending on the amount of child nodes displayed. |
^ ''context'' | [[: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.| It works with or without //**js**// option. In both cases, the indexmenu page is 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'' | 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'' | Sort (only) pages by date creation (first the oldest). | By default namespaces are **not** sorted, you need the **//nsort//** option for this.|
^ ''msort[#meta]'' | Sort (only) pages by a custom [[:devel:metadata]] information. Without the **meta** parameter, it looks for the custom sorting number specified with the %%{{indexmenu_n>N}}%% syntax (see the below [[.indexmenu#metadata tag syntax]]). **meta** should refer to the [[:devel:metadata#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.|
^ ''rsort'' | Reverse the sorting of pages. |By default namespaces are **not** sorted, you need the **//nsort//** option for this. |
^ ''nsort'' | Sort also namespaces according to page sort options. | To use in addition to the above sort options. tsort option will apply to headpages.|
^ ''nons'' | 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'' | Exclude pages nodes from index. It shows only the namespaces. | |
^ ''max#n//[#m]//'' | 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 //**noocookie**//. |
^ //''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//]'' | [[wp>HTTP_cookie|Cookie]] id for a js indexmenu where the previously opened/closed nodes by a user are stored. | Useful when a page is uncached and you don't use the //**nocookie**// option because it forces the same cookie preventing un-useful cookies created every time a page is viewed by the user. By default is always ''//random//'' even when this option is not specified, but you can force it to be a //**n**// fixed number ( i.e ''//id#20//'' ). 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'' | 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. | 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**//|
===== Examples =====
A sample of an indexmenu JS index 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.:
{{indexmenu>..#1|js navbar nocookie}}
JS navigation index with "thread" theme where nodes after the third level are retrieved with Ajax every 2 sublevels. Pages are sorted by title and [[.indexmenu#Metadata tag syntax|custom sort]] number:
{{indexmenu>..#1|js#thread navbar max#3#2 tsort msort}}
Standard DokuWiki index showing only pages inside wiki:plugins and lower namespaces (max two levels):
{{indexmenu>:wiki:plugins#2|nons}}
Js tree showing pages and namespaces both sorted by reverse title. For example,if "archive" contains stuff ("news","oldnews",etc) that you need to quickly organize by time, you could create numbered [[.:indexmenu#Namespaces title and link (headpages)|headpages]] for every namespace (i.e renaming "oldnews" in "news 2006", "news" in "news 2010" and so on) and sort them from new to older:
{{indexmenu>:archive#1|js tsort nsort rsort}}
Standard index showing the tree of the current context ((the namespace of the page displayed by a user who is navigating your site)) opened at the second level .
{{indexmenu>playground#2|context}}
JS tree showing all (and only) the namespaces of the "private" namespace sorted by date creation. "private" is relative and refers to the private namespace under the page containing the indexmenu syntax.
{{indexmenu>private|js nopg dsort}}
===== Metadata tag syntax =====
By default nodes on the same tree level are sorted by 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:
{{indexmenu_n>N}}
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 containig a mix of standard and [[config:useheading]] pages:
-Root
|_don
|_Mirror sessions (headline title of the ":mirror" page)
|_pachuco
|_At the radar station (headline title of the ":radar" page)
|_van
|_vliet
in this way:
{{indexmenu>..#1|msort}}
-Root
|_vliet {{indexmenu_n>1}}
|_van {{indexmenu_n>2}}
|_don {{indexmenu_n>3}}
|_Mirror sessions (headline title of the ":mirror" page)
|_pachuco
|_At the radar station (headline title of the ":radar" page)
Pages without sort number, like the last three pages, are sorted by page name as default, but you can force a different sort:
{{indexmenu>..#1|tsort msort}}
-Root
|_vliet {{indexmenu_n>1}}
|_van {{indexmenu_n>2}}
|_don {{indexmenu_n>3}}
|_At the radar station (headline title of the ":radar" page)
|_Mirror sessions (headline title of the ":mirror" page)
|_pachuco
====== How to install ======
|Download the [[http://samuele.netsons.org/dokuwiki/media/indexmenu.zip|zip]] file and unpack it into ''lib/plugins'' folder or use the [[plugin:plugin]] manager.|
|Mirror link: http://Xxoomer.alice.it/satogni/misc/indexmenu.zip (Remove the first X).|
[[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu#old_releases|Old releases]]
===== Changelog =====
|:!: You could need to purge your browser and server cache after upgrading it, following these [[.:indexmenu#The tree is not displayed|instructions]]. The full changelog can be viewed at my [[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu#changelog|indexmenu]] page. |
* **2009-08-29 Version 4.6**:
* :!: //New Feature//: Namespace declaration complies with DokuWiki [[:namespaces#creating namespaces|namespaces]]. **Important before upgrading from previous versions**: according to the new DokuWiki syntax, a simple //main namespace// without relative declaration prefix (i.e: "playground") doesn't refer anymore to the subnamespace in the root namespace but in the **current** namespace. To refer to the root namespace, you need to prepend the ":" declaration to it.
* //New Feature//: Added the //context// option. It resolves relative requested namespaces starting from the current user location instead of the page containing the indexmenu syntax.
* :!: //New Feature//: Changed skip_file and skip_index syntax to use DokuWiki id instead of system paths. Thanks to Dmitry Katsubo.
* //New Feature//: Metatada titles are not rendered when recursively building the indexmenu tree. This will speed up the page loading when cache expires, but could not display the heading title for nodes without metadata information.
* //New Feature//: Added the nojs button in the edit toolbar and toolbar CSS classes.
* //New Feature//: The right JS context menu is closed by any document click. Thanks to Urban.
* //Bug//: Fixed a bug which prevents page caching when it contains only indexmenu syntax.
* //Bug//: Disable JS indexmenu cookies in preview mode.
* //Bug//: Fixed an ACL issue.
* //Bug//: Fixed UTF8 TOC preview bug.
* **2009-01-04 Version 4.5**:
* //Bug//: Fixed a stupid bug with toolbar.
* **2008-12-02 Version 4.4**:
* //New Feature//: Added AJAX for the nojs index view.
* //New Feature//: Added navbar support also in nojs mode, but unlike js mode, its page does not use cache.
* //New Feature//: Added nopg option. Thanks to Sebastian E.
* //New Feature//: TOC preview displays rendered instructions instead of raw text when TOC is empty.
* //New Feature//: German translation by Fabian Pfannes.
* //Bug//: Fixed ACL bugs that prevents js mode to work correctly.
* //Bug//: Fixed a bug with [[plugin:indexmenu#only_admins|Only Admins]] option.
* //Bug//: Fixed a bug that prevents to disable the context menu.
* //Bug & Features//: id for navbar trees is now random by default + Minor bug fixes and improvements.
* //Others//: [[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu#donation|Donation]] button added.
* **2008-04-12 Version 4.3**:
* New Feature: Different js [[plugin:indexmenu#the_context_menu|context menus]] for anonymous, authenticated and admin user.
* Bug: DokuWiki RC2008-04-11 compatible.
* Bug: Context menu should now support all userewrite and useslash DokuWiki config options.
* Bug: Fixed msort to work with nsort when in non-js mode.
===== Development =====
Development release contains features and bug fixes that will be in next public release and it should be used for [[:development]] purposes. Unlike the stable release, included JavaScript files are not compacted so the network load is a little bit higher. Even it should work concerning indexmenu main features, use it only on a test environment or after a backup of your site data.
My [[http://samuele.netsons.org/dokuwiki|site]] is always based on this release.
The version returned by the development release is always the same of the stable one so upgrading from stable to development with plugin manager does not work.
Before installing the development release be sure to have first manually deleted the old indexmenu directory. Also be sure that, as last step, server/client cache is purged following 4 and 5 of the [[.:indexmenu#the_tree_is_not_displayed]] section.
[[http://samuele.netsons.org/darcs/indexmenu/indexmenu.tar.gz]]
==== Darcs ====
If you're interested, there's also an indexmenu [[devel:darcs]] repository.
darcs get --partial http://samuele.netsons.org/darcs/indexmenu
To create a patch, go in your downloaded indexmenu directory and:
#Check for new patches and install them:
darcs pull
#Modify source files creating your own patch and record it with:
darcs record
#Send the patch to me via mail:
darcs send
===== Translations =====
At this moment very few languages are supported , but I'll be glad if you want translate indexmenu in your own language or correct my poor english.
Strings to translate are in ''indexmenu/lang/en/lang.php'' and ''indexmenu/lang/en/settings.php''.\\
You can send me translations with [[.:indexmenu#how_to_install|darcs]] or simply via [[samuele@samuele.netsons.org|email]].
===== DokuWiki 2003-09-03 =====
|:!: This version will not be upgraded anymore.|
Indexmenu v2.7 compatible with old 2003-09-03 DokuWiki version.
Download the [[http://samuele.netsons.org/dokuwiki/media/indexmenu-2.7-2003-09-03.zip|2003-09-03 zip]] file and unpack it into ''lib/plugins'' folder or use the [[plugin:plugin]] manager.
====== Configuration ======
Indexmenu is fully configurable from [[plugin:config|Configuration Manager]]. Options are explained in the below sections.
===== Namespaces title and link (headpages) =====
First of all, if you want that the tree displays the heading title of pages instead of their name, you need to set the [[config:useheading]] on.
Then, with the ''headpage'' global option, you'll be able to set from which pages retrieve titles.
Every namespace will retrieve its title from the heading title of a page, called headpage, and will be linked directly to it.
You can choose a name for the page from which retrieve the title or use a special 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 founded.
To get a better visualization you could use the ''hide_headpage'' option, that hides headpages in the rendered indexmenu tree.
===== ACL Cache =====
Optimize the cache of indexmenu according to ACLs. \\
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.
There are also important issues in [[.:indexmenu#about ACLs]] and [[.:indexmenu#about_empty_namespaces]] that affects trees limited by ACLs.
===== Replace index =====
When this option is not empty, the DokuWiki default [[:index]] is replaced with a custom page, which for example contains 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:
{{indexmenu>..|js navbar nocookie}}
You may also want to hide this page in any indexmenu trees with the [[.:indexmenu#skip files]] option.
===== Skip Index =====
This option let you to 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/pcre.pattern.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
/(copyright|privatens:users)/
Skip the namespace whose id is exactly ''myusers:spaces''
/^myusers:spaces$/
===== Skip Files =====
This option 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/pcre.pattern.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.
===== Empty message =====
:!: From 3.1 release, message supports the wiki syntax, so it's fully customizable. Don't use HTML code.
You can show a custom message in place of the menu tree if it can not be rendered (i.e namespace doesn't exist):
**//%%{{ns}}%%//** is an alias for the requested namespace.
>One useful empty message is $conf['plugin_indexmenu']['empty_msg']="
" This makes the empty indexmenu look like a list (and therefore look closer in style to non-empty indexmenus).
===== Only admins =====
It prevents no-admin users to insert 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.
===== 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.
====== JavaScript themes ======
The JavaScript tree menu is based on [[http://www.destroydrop.com/javascripts/tree/|dTree]] code and is called with the //**js**// option.\\
Without //**theme**// option, JavaScript indexmenu will use the default theme.
Inside the Admin panel there is the option to download js themes to share your owns directly from my site.
To download themes directly into your DokuWiki server, you need that indexmenu images directory is writable by the web user.\\
You can also simply download a theme into your PC with the ''download'' link, and then manually install it.
===== Theme tutorial =====
You can create custom themes for every index rendered with the [[http://www.destroydrop.com/javascripts/tree/|dTree]] menu.
Simply create a subdirectory, for example ''mytheme'', inside ''indexmenu/images'' and put inside it your icons following the ''default'' theme scheme:
^Icon ^Type ^
|base.gif|Root Folder |
|folderopen.gif|Open folder without URL link|
|folder.gif|Closed folder without URL link|
|folderhopen.gif|Open folder with URL link (headpage)|
|folderh.gif|Closed folder with URL link (headpage)|
|page.gif|Page|
|plus.gif| |
|minus.gif| |
|nolines_plus.gif| |
|nolines_minus.gif| |
|minusbottom.gif| |
|plusbottom.gif| |
|join.gif| |
|joinbottom.gif| |
|line.gif| |
|empty.gif| |
Use your theme with //**js#mytheme**// syntax.
You can also customize a theme style by creating its [[.:indexmenu#Custom theme CSS style|own style]].
The default icons file format is GIF, but PNG and JPG are also recognized. To use them in place of GIF, you have to name your theme directory with the appropriate image extension. For example: Mytheme.png/base.png.
===== The context menu =====
An action menu is displayed when using the context mouse menu click (the right one in many cases). On Opera you can use the CTRL+left click to display it.
When in editing mode, by default an "Insert as DWlink" item menu is added to the menu in order to insert the node DokuWiki link in your editing box.
A different context menu is loaded depending on anonymous, authenticated or admin users.
You can fully customize those menus by editing these files in the 'the indexmenu/jsmenu' directory:
^File ^Loaded by^
|"menu.js" |anonymous user|
|"usrmenu.js" |authenticated user|
|"admmenu.js" |admin user((see [[config:superuser]]))|
To prevent to load the context menu, simply remove the indexmenu_contextmenu variable declared in the above menu files.
**How to write utf8 chars, like èåäö, in the context menu file?**
A solution is to encode them yourself: Find your char at http://unicode.coeurlumiere.com, replace the last zero of the left code by the character in the upper row and prepend the result with \u : i.e. \u00E3 for 'ã'
====== CSS Style ======
You can edit the [[http://samuele.netsons.org/dokuwiki/doku.php?id=dokuwiki:plugins:indexmenu:source:style|style.css]] in order to globally customizing the tree menus style.
Some styles are:
^Tag ^Comment ^Mode ^
|a.nodeFdUrl|Namespace with URL link (headpage)|js|
|a.node |Namespace without URL link|js|
|a.nodeUrl|Page|js|
|a.nodeSel |Previuos selected page or headpage highlight|js|
|a.navSel |Current page highlight|js|
|a.indexmenu_idx_head|link style of a namespace with URL (headpage)|nojs|
|a.indexmenu_idx|link style of a namespace without URL|nojs|
|.indexmenu_arrow| The scrolling arrow area|js|
|.indexmenu_toc| The toc-preview area|js|
===== Custom theme CSS style =====
If you want to apply a different style from the global one to a js theme, you need to create a style.css file like this inside the theme directory you want customize and use its name as subclass.
/*Custom style for the thread theme*/
.dtree .thread{
font-family: Comic Sans MS;
}
.dtree .thread a.navSel {
background-color: #000;
color: #fff
}
====== FAQ and Notes ======
===== The tree is not working as expected =====
* If you installed for the first time the indexmenu plugin or upgraded it from a previous release, it could be merely a cache issue. Example of symptoms are: tree is not displayed (or a static dokuwiki index is displayed in its place), context menu is not working, any new release feature reported in the [[.indexmenu#changelog]] is working.\\ Try to follow istructions to purge cache described in the [[.indexmenu#The tree is not displayed]] section and retry to display it.
* If you think that indexmenu are still not fitting your needs, be sure to using a correct [[.indexmenu#syntax]], and read carefully the [[plugin:indexmenu#configuration]] instructions. There are a lot of options for this plugin, maybe you missed the good one.
* You are sure that the syntax is correct. Pheraps you missed something in this [[.indexmenu#FAQ and Notes]] section.
* Still no solution? Check if someone reported your issue as a [[.indexmenu#bug]] or opened a [[.:indexmenu:discussion]] for it.
* Ok, now i belive that indexmenu is really not working as needed. Report a detailed [[.indexmenu#bug]] or open a [[.:indexmenu:discussion]] for support or new feature requests and i'll try to find a solution in my spare time. Consider also to contact me via [[.:indexmenu:discussion|email]] for long discussions to keep these dokuwiki pages smaller and readable by users.
===== The tree is not displayed =====
Follows these instructions:
-To have installed an indexmenu release compatible with your DokuWiki version as described in [[indexmenu#how to install]].
-To have the last indexmenu version installed. For example check that its date is the same of [[.:indexmenu#changelog]] last release through the info button in plugin manager.
-To have used a correct [[.:indexmenu#syntax]].
-To have purged your browser cache. With Firefox should be sufficient a reload of the indexmenu page by holding down the SHIFT key. :!: This is an important step.
-To have purged server cache by a [[:devel:caching#purging_the_cache|purge=true]] request.:!: This is an important step.
-To have purged CSS and JavaScript server cache by temporary disabling the DokuWiki whole cache. Set to 0 the [[config:cachetime]] config and reload indexmenu page. Then you can set it to its previous value.
If problem still persists, please, report the bug with details of your configuration in [[.:indexmenu#bugs]] section.
**Note: Make sure to save the page. The JS tree will not if you only preview the page (at least for me)**
I can't reproduce this bug, for me indexmenu works on preview too. One reason could be the Firefox bug that I wrote about in the [[.:indexmenu#bugs]] section. Could you check the JavaScript console for errors? --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2007-03-09 16:46//
===== DokuWiki is getting slow =====
If your site contains a large amount of pages, and you're using indexmenu as a navigation sidebar, you could notice random slowdowns in the page loading.
This happens when cache is purged and the whole indexmenu tree has to be rebuild.
To avoid this problem you may use the [[plugin:indexmenu#syntax|max]] option, which rebuilds only a single tree portion (sublevel) and enable AJAX for further user-requested sublevels.
===== Way to Set Different Defaults for Common Parameters =====
These new sort options (tsort, msort, nsort) are fantastic! Just wondering if there is a way to change the defaults, so that if nothing else is specified, a certain set of sort parameters are used automatically. For example, we have a wiki where we will **always** use the msort tsort nsort options together (in every instance of indexmenu). So instead of defining something like:
{{indexmenu>.|msort tsort nsort}}
100 times, we could just say:
{{indexmenu>.}}
This would make things easier for rookie editors, and ensure consistency. Just curious if it's feasible in some way.
Cheers! ---//[[ryan.jake@gmail.com|Ryan Jacobs]] 2008-03-01//
> Currently there is no way to set these defaults. To force them (but then there will be no way to unset them), you should hack the 'syntax/indexmenu.php' handle function:
$match = substr($match,12,-2);
+ $match .= ' msort tsort nsort';
--- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2008-03-03 23:44//
>>Thanks, that's exactly the kind of detail I was looking for. I know it's a "hack", but in some circumstances consistency will be more important than heaps of options for every instance of indexmenu.
>>
>>Thanks! ---//[[ryan.jake@gmail.com|Ryan Jacobs]] 2008-03-04//
===== Indexmenu id conflict =====
I have in my sidebar the following code
{{indexmenu>..#1| js navbar id#random }}
and I get after saving this message: Indexmenu id conflict
What's wrong????
The IE also doesn't remember tree state after open a page
With Firefox it works
> A conflict happens when there are two indexmenu tree with the same id in a web page. If you're using only one indexmenu with the below syntax then it could be a cache issue. Have you tried with the [[.:indexmenu#The tree is not displayed]] steps? Let's continue this discussion here but, please, next time report bugs in the appropriate [[.:indexmenu#bug]] section. --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2008-02-20 17:33//
> I forgot to say that this obviously happens when you are editing your site sidebar page, too. In this case you get the same indexmenu object in both page and sidebar and the conflict is detected. --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2008-02-25 13:05//
>> Thanks. I have tried it with [[.:indexmenu#The tree is not displayed]], but with IE indexmenu doesn't remember the tree state after open a page. The theme shows a open directory with the minus but all the tree's are still closed ---//[[w.stoiber@lenzing.com|Werner Stoiber]] 2008-03-07 14:20//
>>> Could you try the [[.:indexmenu#development]] release (after installed, purge the cache following [[.:indexmenu#The tree is not displayed]] steps)? If nothing change, could you send me you site URL so I can test it? If it's not public accessible, a screenshot could help. --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2008-03-07 18:34//
>>>> I've tried the [[.:indexmenu#development]] release. with the same result. I've sent you the screenshot with mail. Thanks Werner ---//[[w.stoiber@lenzing.com|Werner Stoiber]] 2008-03-19 12:45//
It took me some extra explanations from Samuele to get that : id conflict will always occur as long as sidebar AND index are the same page. To avoid it, make a page for index, and **another one** for sidebar (even if they have exactly the same content ^_^ ) --- //[[hugoborrell@gmail.com|NewMorning]] 2009/02/11 22:45//
===== Can I sort the tree nodes (filename or page heading or creation time)? =====
Yes, You can sort pages with the tsort, dsort or msort [[.:indexmenu#syntax]] options. To sort namespaces you need to add the nsort option to previouses.
===== How can I activate the indexmenu as sidebar for every page? =====
If you want to replace the default navigation with sidebar, please note that you\\
a) need a [[:template]] that actually has some sort of "sidebar"\\
b) probably need to set the "page that's used as navigation" in the template config and put inside that page the indexmenu syntax , for example for 'dokubook' this is:
$conf['sb_pagename'] = 'wiki:navigation';
>I would like to have the indexmenu on the left side (similar to the default "table of contents" on the right). On [[http://samuele.netsons.org/dokuwiki/doku.php?id=playground:playground|Samuel's Playground-Page]] is a very fine example of what I mean. I mean the box on the left-side with the title "DokuWiki". When I view the source-code it is
)!s','',$desc
===== I'm using "useheading" but the tree displays namespace and page names rather than headings =====
The text used for the nodes in the tree is retrieved from DokuWiki's [[:metadata]] store. DokuWiki uses a background process triggered by a web-bug to updating this metadata.((See [[:indexer]].)) If you added wiki pages/namespaces via the filesystem (rather than creating them in DokuWiki,) and that page/namespace has never been viewed, the metadata will not have been generated.
====== Bugs ======
|:!: Before to report a bug, please check if it persists also in the [[.:indexmenu#development]] release (cause it could already contain the fix) and that it's not a trivial issue solvable reading [[.:indexmenu#the tree is not working as expected]].|
| For general usage questions and support request not covered in the [[.:indexmenu#faq and notes]] section, go in the [[plugin:indexmenu:discussion]] page. |
| Solved Bugs are moved in [[.:indexmenu:oldbugs]] discussion page.|
===== Firefox JS Cache Bug =====
It seems that a severe [[https://bugzilla.mozilla.org/show_bug.cgi?id=355567|bug]] of Firefox, under some circumstances, corrupts cached JavaScript files so that a no-js tree is displayed in place of tree one. Purging browser cache solves it. Other browsers are not affected by this bug. Latest indexmenu releases seems not to be affected by this bug.
===== Namespace Separator =====
indexmenu uses a colon as a namespace separator, but on my Windows-Server DokuWiki only works correctly with a slash as a separator. Is it possible anyway, to change the namespace separator in indexmenu? --Thomas
>Do you mean the URL namespace separator? Last version should work with it, but you need first to activate the URL rewriting in the DokuWiki configuration. The variables are [[config:userewrite]] and [[config:useslash]].
>> Yes, I mean the URL namespace separator ;-) rewriting is activated and also useslash. But I handled the rewriting by ".htaccess". If I set it to "DokuWiki" also indexmenu handles the URL. But I want to use htaccess, cause of nicer URLs. Is this possible anyway? --Thomas
>>>DokuWiki userewrite option has also the "htaccess" value. Does not it work (don't forget to set the sepchar)? A workaround is to change these settings in the indexmenu syntax.php as you need:
$out .= "$js_name.config.urlbase='".wl()."';\n";
$out .= "$js_name.config.sepchar='".idfilter(':')."';\n";
>>>Feel free to email me to get support.
===== identical name sub-elements not displayed =====
using version 2008-01-04 (as indicated in VERSION.txt) and headings as titles.
if a page inside namespace has the same pagename (but not title) as the namespace, this page does not appear in the indexmenu tree. for example, if I have two pages, test/test and test/a, test/test is not visible in the indexmenu tree. --- //[[richlv@nakts.net|rich]] 2009/08/17 10:19//
> If test/test is an headpage and the indexmenu ''hide_headpage'' setting is on than it's not a bug. To display it you need to disable the ''hide_headpage'' option or to change the ''headpage'' option. Read the [[.:indexmenu#Namespaces title and link (headpages)]] section for info. Otherwise please report if the bug persists in the [[.:indexmenu#development]] release. --- //Samuele//
===== Buttons disappear in the toolbar menu =====
Working on Linux RedHat 4, the two buttons in the menu never appear (But I can still click on the button, even though they're just one pixel large). I tried to change the path to the pictures, but nothing did the trick. Do you have any idea about the cause?
>Maybe a css problem. Could you post a screenshot of the bug?
>> {{http://img517.imageshack.us/img517/1892/snapshot1ky.png| }}Sure. Here you go. Is there a way to put some text to replace/complete the picture buttons?
>>> This is not the current indexmenu stable release, could you updgrade it and check if bug persists? If it persists, adding this code in the style.css inside indexmenu directory overrides your theme css and forces indexmenu buttons to be large enough (works only in the current indexmenu stable release):
.indexmenu_extratoolbar button, .indexmenu_jstoolbar button {
width:20px !important;
height:20px !important;
}
>>> or ,if the problem is the button images size:
.indexmenu_extratoolbar img, .indexmenu_jstoolbar img {
width:16px !important;
height:16px !important;
}
>>> and don't forget to purge browser cache. --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2009/10/12 15:26//
>>>> Hmm, now it's worse. I upgraded and there is nothing appearing when clicking on the toolbar button. :S
>>>> If it's possible to add just a little text next to the picture to click on it, it would be nice. I don't know enough about JavaScript myself, but I guess it is not so hard. I just need something to click on, and I guess there would be less problems with just text.
>>>>> Uhm, did you purged your browser cache as i reccomended? Adding text could not be a solution. If the problem is your theme css that disables indexmenu button display or sets a small size for them, the text will also not appear or will be truncated. The better way to check this on your own is to use a web developer tool like the firefox extension [[http://getfirebug.com|firebug]].
>>>>>> No, the problem isn't the CSS. I modified the dimensions of the buttons, so I can click on them easily, but they still don't appear. I guess JavaScript fails to load them at some point, but I don't know why. Can you just tell me how I can add text next to the picture, so I'll try it and tell you what it do. I'm pretty sure the text will appear correctly. See this picture: {{http://img123.imageshack.us/img123/4782/snapshot2g.png|}} I'm able to 'see' the button when I give it some dimensions, but the picture can't be loaded.
>>>>>>> Override edit.js with edit-full.js, then add the code below comment at line 63:
btn = createToolButton(theme_url + adata[key]+'/base.'+indexmenu_findExt(adata[key]),adata[key]);
btn.className = 'pickerbutton';
//Add this line
btn.innerHTML += "YOURTEXT";
>>>>>>> Please, if you don't find a solution, continue this discussion via email that is more approriate way to solve bugs --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2009/10/12 17:18//.
>>>>>>>> Further inspection brought to conclusion that it was a bug already fixed in current stable release, that persisted because of unpurged cache. Following steps in [[.:indexmenu#the_tree_is_not_displayed]] is sufficent to solve this issues. --- //[[samuele@samuele.netsons.org|Samuele Tognini]] 2009/10/13 18:43//
====== Discussion ======
Please, use the [[.:indexmenu:discussion]] page for feature requests and general discussion. \\ Old discussions are archived in the [[.:indexmenu:olddiscussion]] page.