Plugin Alphaindex

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 indexmenu plugin by Samuele Tognini samuele [at] cli [dot] di [dot] unipi [dot] it.

• Thanks to Samuele Tognini samuele [at] cli [dot] di [dot] unipi [dot] it, you can try the plugin here.
• Tested with 2006-03-09 dokuwiki version.
• acl works, only authorized pages will be shown.
• 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 [at] cli [dot] di [dot] unipi [dot] it for his plugin.
• Feel free to improve it.
• Feel free to correct my poor English

{{alphaindex>[namespace][#n][|nons]}}

Example that displays only pages inside wiki:plugins and lower namespaces (max two levels):

{{alphaindex>wiki:plugins#2|nons}}

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 :

<h3><a name="a" id="a">{{letter}}</a></h3>

and you can create the following css rule (for example) :

#alphaindex h3{
    display: block;
    background-color: #dee7ec;
    padding: 2px 0 2px 10px;
    margin: 20px 0 5px 0;
  }

Optional config option in conf/local.php:

$conf['plugin']['alphaindex']['numerical_index']   = '0-9';
$conf['plugin']['alphaindex']['articles_deletion'] = '^the +|^a +|^an +';
$conf['plugin']['alphaindex']['articles_moving']   = 1;
$conf['plugin']['alphaindex']['empty_msg']         = 'No pages';
$conf['plugin']['alphaindex']['title_tpl']         = '===== Alphabetical index =====';
$conf['plugin']['alphaindex']['begin_letter_tpl']  = '**{{letter}}**';
$conf['plugin']['alphaindex']['entry_tpl']         = '  * [[{{link}}|{{name}}]]';
$conf['plugin']['alphaindex']['end_letter_tpl']    = '';
$conf['plugin']['alphaindex']['hidepages']         = 'start|sidebar';

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

Optional
Default : '0-9'
Example : 'Numerical'

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.

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'

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

Optionnal
Default : 'No index for <b>{{ns}}</b>'

Template (in dokuwiki syntax) for the index title.

Optionnal
Default : '===== Index ====='

Template (in dokuwiki syntax) at the beginning of each letter's blok.

Note : the {{letter}} pattern is mandatory. It's an alias for the current letter.

Optionnal
Default : '==== {{letter}} ===='

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.

Optionnal
Default : ' * [[{{link}}|{{name}}]]'

Template (in dokuwiki syntax) at the end of each letter's block.

Optionnal
Default : (empty)

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

Optionnal
Default : (empty)
Example : 'start|sidebar'

Download the zip file (3k) and unpack it into lib/plugins folder or use the plugin_manager.

Create the folder alphaindex in dokuwiki /lib/plugins directory. Then create the file syntax.php in this folder ¹⁾ and paste in it this code:

/**
 * Info Alphaindex: Displays the alphabetical index of a specified namespace. 
 *
 * Version: 1.2
 * last modified: 2006-06-14 12:00:00
 * @license     GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author      Hubert Molière  <hubert.moliere@alternet.fr>
 */
 
/**
 * Configuration additionnelle spécifique au plugin
 *
 * - $conf['plugin']['alphaindex']['numerical_index']
 * - $conf['plugin']['alphaindex']['articles_deletion']
 * - $conf['plugin']['alphaindex']['articles_moving'] 
 * - $conf['plugin']['alphaindex']['empty_msg']
 * - $conf['plugin']['alphaindex']['title_tpl'] 
 * - $conf['plugin']['alphaindex']['begin_letter_tpl']
 * - $conf['plugin']['alphaindex']['entry_tpl']
 * - $conf['plugin']['alphaindex']['end_letter_tpl']
 * - $conf['plugin']['alphaindex']['hidepages']
 *
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
require_once(DOKU_INC.'inc/search.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_alphaindex extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Hubert Moliere',
            'email'  => 'takashi@natural-design.net',
            'date'   => '2006-06-14',
            'name'   => 'Alphaindex',
            'desc'   => 'Insert the alphabetical index of a specified namespace.',
            'url'    => 'http://www.dokuwiki.org/plugin:alphaindex'
            );
    }
 
    function getType(){ return 'substition';}
    function getAllowedTypes() { return array('baseonly', 'substition', 'formatting', 'paragraphs', 'protected'); }
 
    /**
     * Where to sort in?
     */
    function getSort(){
        return 139;
    }
 
    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
        $this->Lexer->addSpecialPattern('{{alphaindex>.+?}}',$mode,'plugin_alphaindex');
    }
 
  /**
   * Handle the match
   */
    function handle($match, $state, $pos, &$handler){
        $level = 0;
        $nons = true;
        $match = substr($match,12,-2);
        //split namespaces
        $match = preg_split('/\|/u', $match, 2);
        //split level
        $ns_opt = preg_split('/\#/u', $match[0], 2);
        //namespace name
        $ns = $ns_opt[0];
        //level;
        if (is_numeric($ns_opt[1])) {
            $level=$ns_opt[1];
        }
        $match = explode(" ", $match[1]);
        // namespaces option 
        $nons = in_array('nons', $match);
        // multi-columns option
        $incol = in_array('incol', $match);
        return array($ns,array('level' => $level,'nons' => $nons,'incol' => $incol));
    }
 
    /**
     * Render output
     */
    function render($mode, &$renderer, $data) {
        global $conf;
        if($mode == 'xhtml'){ 
            $alpha_data = $this->_alpha_index($data, $renderer);
            if ((!@$n)) {
                if (isset ($conf['plugin']['alphaindex']['empty_msg'])) {
                    $n = $conf['plugin_alphaindex']['empty_msg'];
                } else {
                    $n = 'No index for <b>{{ns}}</b>';
                }
            }
            $alpha_data = str_replace('{{ns}}',cleanID($data[0]),$alpha_data);
 
            $alpha_data = p_render('xhtml', p_get_instructions($alpha_data), $info); 
 
            // remove toc, section edit buttons and category tags
            $patterns = array('!<div class="toc">.*?(</div>\n</div>)!s',
                            '#<!-- SECTION \[(\d*-\d*)\] -->#e',
                            '!<div class="category">.*?</div>!s');
            $replace  = array('','','');
            $alpha_data = preg_replace($patterns, $replace, $alpha_data);      
            $renderer->doc .= '<div id="alphaindex">' ;
            $renderer->doc .= $ns_data;
            $renderer->doc .= '<hr />';
            $renderer->doc .= $alpha_data;
            $renderer->doc .= '</div>' ;
            return true;
        }
        return false;
    }
 
    /**
     * Return the alphabetical index 
     * @author Hubert MOLIERE <hubert.moliere@alternet.fr>
     *
     * This function is a hack of Indexmenu _tree_menu($ns)
     * @author Samuele Tognini <samuele@cli.di.unipi.it>
     * 
     * This function is a simple hack of Dokuwiki html_index($ns)
     * @author Andreas Gohr <andi@splitbrain.org>
     */
    function _alpha_index($myns, &$renderer) {
        global $conf;
        global $ID;
 
        $ns = $myns[0];                                                
        $opts = $myns[1];
 
        // Articles deletion configuration
        $articlesDeletionPatterns = array();
        if(isset($conf['plugin']['alphaindex']['articles_deletion'])) {
            $articlesDeletionPatterns = explode('|', $conf['plugin']['alphaindex']['articles_deletion']);
            $articlesDeletion = true;
        } else {
            $articlesDeletion = false;
        }
 
        // Hide pages configuration
        $hidepages = array();
        if(isset($conf['plugin']['alphaindex']['hidepages'])) {
            $hidepages = explode('|', $conf['plugin']['alphaindex']['hidepages']);
        }
 
        // template configuration
        if(isset($conf['plugin']['alphaindex']['title_tpl'])) {
            $titleTpl = $conf['plugin']['alphaindex']['title_tpl'];
        } else {
            $titleTpl = '===== Index =====';
        }
        if(isset($conf['plugin']['alphaindex']['begin_letter_tpl'])) {
            $beginLetterTpl = $conf['plugin']['alphaindex']['begin_letter_tpl'];
        } else {
            $beginLetterTpl = '==== {{letter}} ====';
        }
        if(isset($conf['plugin']['alphaindex']['entry_tpl'])) {
            $entryTpl = $conf['plugin']['alphaindex']['entry_tpl'];
        } else {
            $entryTpl = '  * [[{{link}}|{{name}}]]';
        }
        if(isset($conf['plugin']['alphaindex']['end_letter_tpl'])) {
            $endLetterTpl = $conf['plugin']['alphaindex']['end_letter_tpl'];
        } else {
            $endLetterTpl = '';
        }
 
        if($ns == '.') {
          $ns = dirname(str_replace(':','/',$ID));
          if ($ns == '.') $ns = '';
        } else {
          $ns = cleanID($ns);
        }
 
        $ns  = utf8_encodeFN(str_replace(':','/',$ns));
        $data = array();
        search($data,$conf['datadir'],'alphaindex_search_index',$opts,"/".$ns);
 
        $nb_data = count($data);
        $alpha_data = array();
 
        // alphabetical ordering
        for($cpt=0; $cpt<$nb_data; $cpt++) {
            $tmpData = $data[$cpt]['id'];
 
            $pos = strrpos(utf8_decode($tmpData), ':');
            if($conf['useheading']) {
                $pageName = p_get_first_heading($tmpData);
                if($pageName == NULL) {
                    if($pos != FALSE) {
                        $pageName = utf8_substr($tmpData, $pos+1, utf8_strlen($tmpData));
                    } else {
                        $pageName = $tmpData;
                    }
                    $pageName = utf8_str_replace('_', ' ', $pageName);
                }
            } else {
                if($pos != FALSE) {
                    $pageName = utf8_substr($tmpData, $pos+1, utf8_strlen($tmpData));
                } else {
                    $pageName = $tmpData;
                }
                $pageName = utf8_str_replace('_', ' ', $pageName);
            }
            $pageNameArticle = '';
 
            // if the current page is not a page to hide 
            if(!in_array($pageName, $hidepages)) { 
                // Articles deletion
                if($articlesDeletion) { 
                    foreach($articlesDeletionPatterns as $pattern) {
                        if(eregi($pattern, $pageName, $result)) {
                            $pageName = eregi_replace($pattern, '', $pageName);
                            $pageNameArticle = ucfirst(trim($result[0]));
                        }
                    }
                }
                // Récupération de la première lettre du mot et classement 
                $firstLetter = utf8_deaccent(utf8_strtolower(utf8_substr($pageName, 0, 1)));
                if(is_numeric($firstLetter)) {
                    if(isset($conf['plugin']['alphaindex']['numerical_index'])) {
                        $firstLetter = $conf['plugin']['alphaindex']['numerical_index'];
                    } else {
                        $firstLetter = '0-9';
                    }
                }
 
                if(isset($conf['plugin']['alphaindex']['article_moving'])) {
                    $articleMoving = $conf['plugin']['alphaindex']['article_moving'];
                } else {
                    $articleMoving = 1;
                }
                if($articleMoving == 0) {
                    $pageName = $pageNameArticle.' '.$pageName;
                } else if (($articleMoving == 1)&&($pageNameArticle != '')) {
                    $pageName = $pageName.' ('.$pageNameArticle.')';
                }
 
                $data[$cpt]['id2'] = ucfirst($pageName);
                $alpha_data[$firstLetter][] = $data[$cpt];
            }
        }
 
        // array sorting by key
        ksort($alpha_data);
 
        // Display of results
 
        // alphabetical index
        $alphaOutput .= $titleTpl."\n";
        $nb_data = count($alpha_data);
        foreach($alpha_data as $key => $currentLetter) {
            // Sorting of $currentLetter array
            usort($currentLetter, create_function('$a, $b', "return strnatcasecmp(\$a['id2'], \$b['id2']);"));
 
            $begin = utf8_str_replace("{{letter}}" ,utf8_strtoupper($key), $beginLetterTpl);
            $alphaOutput .= $begin."\n";
            foreach($currentLetter as $currentLetterEntry) {
                $link = utf8_str_replace("{{link}}" ,$currentLetterEntry['id'], $entryTpl);
                $alphaOutput .= utf8_str_replace("{{name}}" ,$currentLetterEntry['id2'], $link);
                $alphaOutput .= "\n";
            }
            $end = utf8_str_replace("{{letter}}" ,utf8_strtoupper($key), $endLetterTpl); 
            $alphaOutput .= $end."\n";
        }
 
        return $alphaOutput;
    }
 
} //Alphaindex class end
 
  /**
   * Build the browsable index of pages
   *
   * $opts['ns'] is the current namespace
   *
   * @author  Andreas Gohr <andi@splitbrain.org>
   * modified by Samuele Tognini <samuele@cli.di.unipi.it>
   */
function alphaindex_search_index(&$data,$base,$file,$type,$lvl,$opts){
  $return = true;
 
  $item = array();
 
  if($type == 'd'){
    if ($opts['level'] == $lvl) $return=false;
    if ($opts['nons']) return $return;
  }elseif($type == 'f' && !preg_match('#\.txt$#',$file)){
    //don't add
    return false;
  }
 
  $id = pathID($file);
 
  //check hidden
  if($type=='f' && isHiddenPage($id)){
    return false;
  }
 
  //check ACL
  if($type=='f' && auth_quickaclcheck($id) < AUTH_READ){
    return false;
  }
 
  //Set all pages at first level
  if ($opts['nons']) {
    $lvl=1;    
  }
 
  $data[]=array( 'id'    => $id,
		 'type'  => $type,
		 'level' => $lvl,
		 'open'  => $return );
  return $return;
}

• 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

* To use the UTF8 functions instead of classic php ones for characters and strings management.

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

* And what's about a RegEx for hidepages?

• Some random title indexes are displayed incorrectly, they lacks the first letter (i.e: okuwiki instead of dokuwiki).

— Samuele Tognini 2006-05-25 03:08

Corrected in 1.2 version — Takashi 2006-06-14 10:16

• It's need to replace all ucfirst calls to UTF8-safe code. For example, utf8_strtoupper(utf8_substr($string, 0, 1)).utf8_substr($string, 1). Otherwise non-latin page titles (cyrillic in my case) displays corrupted. Sorry for my bad english.

— David Mzareulyan 2007-03-08 18:30

• Line:

       $match = substr($match,12,-2);

of alphaindex/syntax.php should be:

       $match = substr($match,13,-2);

— Thanos Massias 2007-06-21 11:10

• Off-by-one error:

          $match = substr($match,12,-2);

  should be

          $match = substr($match,13,-2);

  — Ben Slusky 2007-11-11 02:40

Odd error

I just installed the plugin, and I'm getting this error:
Fatal error: Call to undefined function utf8_str_replace() in /var/www/wiki/lib/plugins/alphaindex/syntax.php on line 216
Juice 2008/06/02

• as per http://www.freelists.org/archives/dokuwiki/05-2008/msg00048.html , I replaced all instances of utf8_str_replace with str_replace and now the plugin works just fine. Juice 2008/06/02
  

It doesn't seem to update when new pages are created. I assume it's a caching problem, but I don't know enough about Doku's caching to edit my maintenance script and fix it. Can anyone suggest a fix? Thanks! — Matt Cooper 2007-05-06 18:00

Yes, it is. Better solution is to implement the caching fix into alphaindex code (you should take look at developer_note for info and to some plugins examples, like indexmenu action plugin).
Or use the dokuwiki internal core, this is from indexmenu page:
To purge cache either wait for the automatic purge cache time expiration or force it through a purge=true request on the page that contains the indexmenu tree.

You also might try the ~~NOCACHE~~ instruction to completly disable a specified page cache, so that you have no more to worry about purging cache. But pay attention that it could slow down the overall loading process of the page depending on the number of tree nodes.

I've installed it in my site, so that, if the author doesn't find a better way, you can test this useful plugin here. — Samuele Tognini 2006-05-25 03:58

I needed listing of namespaces with index pages only, so I make a new option indexes (goes instead of nons) which causes the plugin to generate listing from starting pages only (those are conf['start'] and page with same name as namespace). I'm attaching very simple patch. Not fully tested, just a quick hack. — Tomáš Valenta 2006-11-18 18:35

73a74
>       $indexes = false;
90c91,93
<         return array($ns,array('level' => $level,'nons' => $nons,'incol' => $incol));
---
>       // indexes option
>       $indexes = in_array('indexes', $match);
>         return array($ns,array('level' => $level,'nons' => $nons,'incol' => $incol,'indexes' => $indexes));
293a297,298
>   global $conf;
> 
307c312,317
<  
---
>   // show just index files
>   if ($opts['indexes']) {
>     $myns = explode(":",getNS($id));
>     if (end($myns)!=noNS($id) and noNS($id)!=$conf['start']) return true;
>   }
>

Somehow the plugin list lots of red links in my installation, might this be because it supposes that there is always a file ns1:ns2 present if there is content in the namespage ns1:ns2 (e.g. ns1:ns2:home)? If that is the case, this plugin does not support wikis that make use of default namespace linking, which is a pity. – regards, bernhard

I would like to suggest a feature that prints the namespace beside the page if there are several pages with the same name, e.g.

> Files, (foo/)
> Files (The), (bar/)
> Files, (foobar/)

or with : too, of course

Edit: maybe even an argument to print each namespace (alphabetically sorted) own its own above the root namespace:

> ====== /Files ======
> ====== /Wiki ======
> (Root)

Hello, I use the alphaindex on http://jurtenrunde.de/lieder/doku.php?id=uebersicht:uebersicht/. I've a Namespace struktur wich looks like this:

liedtexte:t:testlied , liedtexte:b:test2 and so on. I ged the index of this way:

{{alphaindex>[liedtexte#10][#n][|nons]}}

. You can see on http://jurtenrunde.de/lieder/doku.php?id=uebersicht:uebersicht/ that it post pages wehre not exis - I like that it show only exis pages. How can I solve this problem?

You can extend the plugin so that it understands the @NS@ option, as in

{{alphaindex>@NS@}}

or the 'empty' namespace option, as in

{{alphaindex>}}

by adding the line:

       global $ID;

just after:

    function handle($match, $state, $pos, &$handler){

and the lines:

       if(empty($ns) || $ns == '@NS@') {
         $pos = strrpos($ID,':');
         if($pos!==false){
           $ns = substr($ID,0,$pos);
         }else{
            $ns = '.';
         }
       }

just after the line:

        $ns = $ns_opt[0];

in alphaindex/syntax.php.

— Thanos Massias 2007-06-21 11:18

Is there a way to override global 'title_tpl' for some particular index? — Stoyan 2008-01-06