====== Term Highlighter Plugin ======

---- plugin ----
description: Register term and then highlight it across whole page with <acronym> tag
author     : Pavel Vitis
email      : pavel.vitis@seznam.cz
type       : syntax
lastupdate : 2005-08-17
compatible :
depends    :
conflicts  :
similar    :
tags       : definitions, annotations
----

This plugin allows definition of term which is then highlighted using ''<acronym>'' tag throughout the page.


===== Syntax =====

DokuWiki Syntax:
  <term Title>Text description</term>

Example:
  <term Apple>Sort of fruit</term>

will highlight all occurrences of word Apple as acronym with 'Sort of fruit' description. 
\\
This is useful whenever you write a big article and you wish to have some term highlighted across the document and you either don't have access to dokuwiki configuration files or simply don't want to clutter the config with terms used only locally.
\\
----
You can see a working example on <del>[[http://blackdaemon.no-ip.org/wiki/dokuwiki:plugin:term|my site]]</del>.
\\
[[pavel.vitis@seznam.cz|Pavel Vitis]]

===== Notes =====
  * Title parameter is not case sensitive. 'tItlE' is the same as 'title'. This can be changed inside code, removing ''strtoupper()'' commands will make title case sensitive.
  * Acronym tags defined inside ''acronyms.conf'' or ''acronyms.local.conf'' file cannot be overridden with term definition. 
  * This plugin needs support for subfolders inside plugin folder. It was introduced in DokuWiki on august 2, 2005. So it will not work in older releases. It is possible to make it working in older version by splitting plugin into two plugins.

===== Plugin =====

==== Step 1: Check requirements ===

This plugin needs DokuWiki 2005-08-02 or later. You can check this by viewing the source of one of your DokuWiki pages: it contains a header with the DokuWiki version. Example:
<code>
<meta name="generator" content="DokuWiki Release 2005-08-02" />
</code>

If you have an older version, you can either upgrade DokuWiki or split this plugin into two parts. To split this plugin in two parts, please replace these file locations in the following steps:\\
''/lib/plugins/term/syntax/add.php'' -> ''/lib/plugins/term_add/syntax.php''\\
''/lib/plugins/term/syntax/show.php'' -> ''/lib/plugins/term_show/syntax.php''\\
''/lib/plugins/term/style.css'' -> ''/lib/plugins/term_show/style.css''\\

==== Step 2: The dokuwiki plugin Termadd ====

This is the term registering plugin, which parses ''<term ></term>'' definition and pushes term into internal list.\\
To install, put the following PHP file into ''/lib/plugins/term/syntax/add.php''.

<code php>
<?php
/**
 * Allows definition of term which is then highlighted using <acronym> tag throughout the page:
 * Example:
 * <term Title>description</term>
 * All occurrences of 'title' will be rendered as acronym with 'description' popup.
 * Title parameter is not case sensitive.
 * TODO: Acronym tags defined inside acronyms.conf or acronyms.local.conf cannot be overridden.
 * Termadd is term registering plugin, Termshow is needed to display terms
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Pavel Vitis <pavel [dot] vitis [at] seznam [dot] cz>
 */

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');

global $terms;
if (!isset($terms)) {
  $terms = array();
}

/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_term_add extends DokuWiki_Syntax_Plugin {

    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Pavel Vitis',
            'email'  => 'pavel.vitis@seznam.cz',
            'date'   => '2005-08-17',
            'name'   => 'Terms registering plugin',
            'desc'   => 'Definition of term which is then highlighted using <acronym> tag throughout the page',
            'url'    => 'http://www.dokuwiki.org/plugin:term',
        );
    }

    /**
     * What kind of syntax are we?
     */
    function getType(){
      return 'substition';
    }

   /**
    * Paragraph Type
    *
    * Defines how this syntax is handled regarding paragraphs. This is important
    * for correct XHTML nesting. Should return one of the following:
    *
    * 'normal' - The plugin can be used inside paragraphs
    * 'block'  - Open paragraphs need to be closed before plugin output
    * 'stack'  - Special case. Plugin wraps other paragraphs.
    *
    * @see Doku_Handler_Block
    */
    function getPType() {
      return 'normal';
    }

    /**
     * Where to sort in?
     */
    function getSort() {
      // Somewhere on the beginning
      return 09;
    }

    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
      $this->Lexer->addEntryPattern('<term\s{1,}(?=.*</term>)',$mode,'plugin_term_add');
    }

    function postConnect() {
      $this->Lexer->addExitPattern('</term>','plugin_term_add');
    }

    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
      switch ($state) {
        case DOKU_LEXER_UNMATCHED:
          $parts = explode('>', $match);
          $this->_replaceTerm(trim($parts[0]), trim($parts[1]));
          return array($match, $state);
          break;
        default:
          return array($match, $state);
      }
    }

    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
      return false;
    }

    function _replaceTerm($def, $desc) {
      global $terms;
      $terms[strtoupper($def)] = $desc;
    }
}

//Setup VIM: ex: et ts=4 enc=utf-8 :
?>
</code>


==== Step 3: The DokuWiki plugin Termshow ====

This is the term rendering plugin that will recognize words and highlight them if found in list of terms.
To install, put the following PHP file into ''/lib/plugins/term/syntax/show.php''.

<code php>
<?php
/**
 * Allows definition of term which is then highlighted using <acronym> tag throughout the page:
 * Example:
 * <term Title>description</term>
 * All occurrences of 'title' will be rendered as acronym with 'description' popup.
 * Title parameter is not case sensitive.
 * TODO: Acronym tags defined inside acronyms.conf or acronyms.local.conf cannot be overridden.
 * Termshow is term displaying plugin, Termadd is needed to register term first
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Pavel Vitis <pavel [dot] vitis [at] seznam [dot] cz>
 */

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');

global $terms;
if (!isset($terms)) {
  $terms = array();
}

/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_term_show extends DokuWiki_Syntax_Plugin {

    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Pavel Vitis',
            'email'  => 'pavel.vitis@seznam.cz',
            'date'   => '2005-08-17',
            'name'   => 'Terms highlight plugin',
            'desc'   => 'Definition of term which is then highlighted using <acronym> tag throughout the page',
            'url'    => 'http://www.dokuwiki.org/plugin:term',
        );
    }

    /**
     * What kind of syntax are we?
     */
    function getType(){
      return 'substition';
    }

   /**
    * Paragraph Type
    *
    * Defines how this syntax is handled regarding paragraphs. This is important
    * for correct XHTML nesting. Should return one of the following:
    *
    * 'normal' - The plugin can be used inside paragraphs
    * 'block'  - Open paragraphs need to be closed before plugin output
    * 'stack'  - Special case. Plugin wraps other paragraphs.
    *
    * @see Doku_Handler_Block
    */
    function getPType() {
      return 'normal';
    }

    /**
     * Where to sort in?
     */
    function getSort() {
      // This should be larger than acronym sort, otherwise it conflicts with it
      return 500;
    }

    function connectTo($mode) {
       $this->Lexer->addSpecialPattern('(?<=\b)[a-zA-Z\-_]+(?=__\b)|(?<=\b)[a-zA-Z\-_]+(?=\b)',$mode,'plugin_term_show'); // a lookahead to avoid breaking underline
    }
    
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
       global $terms;
       // save some useless processing
       if (count($terms) > 0) {
           $word = $match;
           // save some useless processing, do not allow words shorter than 2 characters
           if ($word != '' && strlen($word) > 2) {
               $word = strtoupper($word);
               if (array_key_exists($word, $terms)) {
                   return array($match, $state, $terms[$word]);
               }
           }
       }
       return array($match, $state);
    }

    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        global $terms;
        if($mode == 'xhtml'){
          if (!empty($data[2])) {
            $renderer->doc .= $this->_renderTerm($renderer, $data[0], $data[2]);
          }
          else {
            $renderer->doc .= ''.$data[0].'';
          }
          return true;
        }
        return false;
    }
    
    function _renderTerm(&$renderer, $term, $descr) {
      return '<acronym class="term" title="'.$renderer->_xmlEntities($descr).'">'.$term.'</acronym>';
    }
}

//Setup VIM: ex: et ts=4 enc=utf-8 :
?>
</code>

==== Step 4: Stylesheet ====

To install stylesheet, put the following CSS text into ''/lib/plugins/term/style.css'' file.

<code css>
acronym.term {
  border-bottom: 1px dashed;
}
</code>

You can customize this to totally differentiate terms from acronyms, for example using yellow background etc.

===== Bugs =====

Don't work with Russian language, please, make it
===== Todo =====

  * Solve conflict with internal acronym parsing, so we can override configured acronym with our own term.
  * Make some optimization so not every word in page gets passed to ''termshow''.



===== Discussion =====

> Why don't you combine those two plugins in one folder, like:
> <code>
 /lib/plugins/term/
                  syntax/
                        add.php
                        show.php
                  style.css
 </code>
> The functions would then have to be called ''syntax_plugin_term_add()'' and ''syntax_plugin_term_show()''. --- //[[esther@kaffeehaus.ch|Esther Brunner]] 2005-08-17//
> 
>> Well, good idea. Updated. --- //[[pavel.vitis@seznam.cz|Pavel Vitis]] 2005-08-17//
>>> It took me some time to find that this was the reason why it didn't work on my 2005-07-13 version. So I added a chapter ''Step 1: Check requirements''. --- //Onno Zweers 2005-10-05//

----

I'm trying the plugin with the latest dev sources, but it appears that termshow breaks underlines...?
> I confirm, with the latest 2007-06-26b DokuWiki release, the underline is broken.
> If you replace, in the connectTo() function of show.php, the regexp '%%(?<=\b)[a-zA-Z_\-]+(?=\b)%%' by '%%(?<=\b)[a-zA-Z\-_]+(?=__\b)|(?<=\b)[a-zA-Z\-_]+(?=\b)%%', the underline will work again. 
> I took the liberty to update the show.php listing, located above this section. --- [[daniel.chaffiol@sgcib.com|dc]] 2007/08/22

----
Hi, on DokuWiki Release 2006-03-09 i have problem with installation, I have created all three files, plugin comes up in plugin manager, but unfortunately there is no HTML output produced after i put even your examples in the wiki code :(, anyone experienced such a behaviour before?
>same here with me. I tried <term lol>laughing out loud</term>, but i didn't see anything, not even lol.
>>some thing similar. Some thing in the source maybe wrong. However for my it works by using the source from [[http://blackdaemon.no-ip.org/wiki/dokuwiki:plugin:term|Blackdeamon]]-page.