====== Alphaindex Plugin ======

---- plugin ----
description: Allows you to insert the alphabetical index of a namespace in a page
author     : Hubert Molière, Matthias Schulte
email      : takashi@natural-design.net
type       : syntax
lastupdate : 2016-02-02
compatible :
depends    :
conflicts  :
similar    : indexmenu, indexmenu2
tags       : navigation, menu, listing, namespace

downloadurl: https://github.com/lupo49/plugin-alphaindex/tarball/master
bugtracker : https://github.com/lupo49/plugin-alphaindex/issues
sourcerepo : https://github.com/lupo49/plugin-alphaindex/
donationurl: 
----

===== Description =====

This simple plugin allows you to insert an alphabetical index of a specified namespace in your pages. It should be useful in DokuWiki sites where pages are organized by namespaces.

It is fully inspired and based on the [[plugin:indexmenu|indexmenu]] plugin by Samuele Tognini <samuele@samuele.netsons.org>.


===== Notes =====
  * Thanks to Samuele Tognini <samuele@samuele.netsons.org>, you can try the plugin [[http://samuele.netsons.org/dokuwiki/doku.php?id=playground:playground2|here]].
  * Tested with [[http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2006-03-09.tgz?id=projects%3Adokuwiki&cache=cache|2006-03-09]] DokuWiki version.
  * [[ACL]] works, only authorized pages will be shown.
  * [[config:useheading]] option works.
  * Tested with some languages based on other characters than roman ones (Japanese, Chinese, Korean, Arabic, Russian, Thai).
  * A big thanks to Samuele Tognini <samuele@samuele.netsons.org> for his plugin.
  * Feel free to improve it.
  * Feel free to correct my poor English


===== Syntax =====

<code>
{{alphaindex>[namespace][#n][|nons]}}
</code>

^ ''[namespace]''     | Namespace name from which the index starts. | optional with //**[n]**// or //**nons**//; "**.**" is the currIREent namespace; "**..**" or an empty value shows the top level namespace. |
^ ''[n]''             | Number that specifies the max level of the tree index nodes. | optional; it can be used together with //**nons**//. |
^ ''nons''          | Exclude namespaces nodes from index. It shows only the pages | optional. |

Example that displays only pages inside wiki:plugins and lower namespaces (max two levels):
<code>
{{alphaindex>wiki:plugins#2|nons}}
</code>

__example__: %%{{alphaindex>.#2|nons}}%% shows all files with the depth of 2; the namespaces are not shown


===== CSS Style =====

All the data displayed by the alphaindex plugin are inside a div (called "alphaindex").

>You can customize each part of the generated code.

For example if you have defined the //begin_letter_tpl// as this :
  ==== {{letter}} ====
the plugin will generate the following HTML code :
<code html><h3><a name="a" id="a">{{letter}}</a></h3></code>
and you can create the following CSS rule (for example) :
<code css>#alphaindex h3{
    display: block;
    background-color: #dee7ec;
    padding: 2px 0 2px 10px;
    margin: 20px 0 5px 0;
  }</code>

===== Configuration =====

|:!: The updated version in the [[alphaindex#how_to_install]] section is fully configurable with the [[config]] manager. |


==== numerical_index ====

Text display in block letter title for the page title beginning with a numerical value.

__Optional__ \\
__Default__ : '0-9' \\
__Example__ : 'Numerical'

==== articles_deletion ====

List of article treated by the plugin. Each article is separated with a '|'.

__Optional__ \\
__Default__ : (empty) \\
__Example__ : **^the +|^a +|^an +** or **^le +|^la +|^les +|^l\' *** (in french)

With the example above, the page 'The Rolling Stones' will be treated as 'Rolling Stones' instead of its real name.

==== articles_moving ====

Management of the articles when the //article_deletion// option is active.

__Optional__ \\
__Default__ : 1 \\
__Authorized values__ :
  * 0 : No change
  * 1 : The article is move to the end of the page name inside brackets
  * 2 or more : The article is deleted
__Example__: with the pagename 'The Rolling Stones'
  * 0 : 'The Rolling Stones'
  * 1 : 'Rolling Stones (The)'
  * 2 : 'Rolling Stones'


==== empty_msg ====

Message shown in your page when the index is empty. \\ 
Note : **%%{{ns}}%%** is an alias for the requested namespace.

__Optional__ \\
__Default__ : 'No index for <b>%%{{ns}}%%</b>'

==== title_tpl ====

Template (//in DokuWiki syntax//) for the index title.

__Optional__ \\
__Default__ : '===== Index ====='

==== begin_letter_tpl ====

>Template (//in DokuWiki syntax//) at the beginning of each letter's block. \\ 
>Note : the %%{{letter}}%% pattern is mandatory. It's an alias for the current letter.

__Optional__ \\
__Default__ : '==== %%{{letter}}%% ===='

==== entry_tpl ====

Template (//in DokuWiki syntax//) for each letter's entry. \\
Note : the %%{{link}}%% and %%{{name}}%% patterns are mandatory.They are aliases for the page link and the page name.

__Optional__ \\
__Default__ : '%%  * [[{{link}}|{{name}}]]%%'

==== end_letter_tpl ====

>Template (//in DokuWiki syntax//) at the end of each letter's block.

__Optional__ \\
__Default__ : (empty)


==== hidepages ====

Name of pages not displayed in the index. Each page name is separated with a '|'.

__Optional__ \\
__Default__ : (empty) \\ 
__Example__ : 'start|sidebar'

===== How to install =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

|:!: There is also a [[http://samuele.netsons.org/dokuwiki/lib/plugins/alphaindex/alphaindex.tar.gz|zip]] updated version with [[alphaindex#patches]] by community users. |

===== Changelog =====

{{rss>https://github.com/lupo49/plugin-alphaindex/commits/master.atom date}}

  * **2006-06-14 - //version 1.2//**
    * Fixed bug in namespaces display (lack of first letter for some namespaces).
    * Use of utf8 functions instead of PHP ones

  * **2006-05-22 - //version 1.1//**
    * Deletion of a dependence to indexmenu plugin

  * **2006-05-19 - //version 1.0//**
    * First release

===== Todo =====

 * <del>To use the UTF8 functions instead of classic PHP ones for characters and strings management.</del>

 * //What's about an update to do Configuration via the Admin-panel?//

 * //And what's about a RegEx for ''hidepages''?  Hem, RegEx is for experts and Dokuwikers are not experts!//

===== Bugs / Feature Requests =====

Please report bugs or feature requests at the [[https://github.com/lupo49/plugin-alphaindex/issues|Github.com - Bug tracker]].


===== Discussion =====

[[.:alphaindex:discussion|Placed on separate page]]