====== Definition Side Note ======

---- plugin ----
description: Allow sidenotes including image caption
author     : Stephane Chamberland
email      : stephane.chamberland@ec.gc.ca
type       : syntax
lastupdate : 2005-07-04
compatible :
depends    :
conflicts  :
similar    : note, imagebox, imagereference
tags       : boxes, caption, !experimental
----


[[:experimental]]

===== Description =====

With this plugin the [[:wiki:syntax]] of [[:DokuWiki]] is extended to allow Side Notes. The syntax to use this plugin is:

  <side>This is my centered note </side>
  <side left>This is my left sided note </side>
  <side right>This is my right sided note </side>

Personally, I use it mainly to add a caption at the bottom of images:

  <side left>{{someimage.gif|image desc}}\\ Here is my Caption</side>


example:

<side right>This is test side note</side>

===== Style =====

To make it work you will need also to add some rules into your template's CSS file [for the default template this file would be ''/lib/tpl/default/design.css'']. You may modify the style of the side note to fit your needs.

<code css style.css>
  .sideboth, .sideleft, .sideright {
    border: 1px solid;
    float:left;
    clear: both;
    text-align: center;
  }

  .sideboth {
    display: block;
    width: 100%;
  }

  .sideright {
    float:right;
  }
</code>

===== Plugin =====

Put the following PHP file in ''/lib/plugins/sidenote/syntax.php''.

<code php syntax.php>
<?php
/**
 * Add SideNote capability to DokuWiki
 * <side>This is my centered note </side>
 * <side left>This is my left sided note </side>
 * <side right>This is my right sided note </side>
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Stephane Chamberland <stephane.chamberland@ec.gc.ca>
 */

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

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

    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Stephane Chamberland',
            'email'  => 'stephane.chamberland@ec.gc.ca',
            'date'   => '2005-07-04',
            'name'   => 'Side Note/Float Box Plugin',
            'desc'   => 'Add Side Note Capability (CSS Float box)',
            'url'    => 'http://www.dokuwiki.org/plugin:side_note',
        );
    }

    /**
     * Constructor - adds allowed modes
     */
    function syntax_plugin_sidenote(){
        global $PARSER_MODES;
        $this->allowedModes = array_merge(
            $PARSER_MODES['formatting'],
            $PARSER_MODES['substition'],
            $PARSER_MODES['disabled']
        );
    }

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

   /**
    * 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 'stack';
    }

    /**
     * Where to sort in?
     */
    function getSort(){
        return 155;
    }

    /**
     * Connect pattern to lexer
     */
    function connectTo($mode) {
        $this->Lexer->addEntryPattern('<side right>(?=.*</side>)',$mode,'plugin_sidenote');
        $this->Lexer->addEntryPattern('<side left>(?=.*</side>)',$mode,'plugin_sidenote');
        $this->Lexer->addEntryPattern('<side>(?=.*</side>)',$mode,'plugin_sidenote');
    }
    function postConnect() {
        $this->Lexer->addExitPattern('</side>','plugin_sidenote');
    }

    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        switch ( $state ) {
            case DOKU_LEXER_ENTER:
                if (preg_match('/left>/', $match)>0) {
                    return array('',$state,'left');
                } else if (preg_match('/right>/', $match)>0) {
                    return array('',$state,'right');
                } else {
                    return array('',$state,'');
                }
                break;
            case DOKU_LEXER_UNMATCHED:
                //$matches = preg_split('/>/u',$match,2);
                //$matches[0] = trim($matches[0]);
                //$matches[1] = trim(implode('>',array_slice($matches,1)));
                //return array($matches[1], $state,$matches[0]);
                return array($match,$state,'');
                break;
        }
        return array('',$state,'');
    }

    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            if ($data[1] == DOKU_LEXER_ENTER){
                if ($data[2] == 'right' ) {
                    $renderer->doc .= '<span class="sideright">';
                } else if ($data[2] == 'left') {
                    $renderer->doc .= '<span class="sideleft">';
                } else {
                    $renderer->doc .= '<span class="sideboth">';
                }
            } else if ($data[1] == DOKU_LEXER_UNMATCHED){
                $renderer->doc .= $data[0];
            } else if ($data[1] == DOKU_LEXER_EXIT){
                $renderer->doc .= '</span>';
            }
            return true;
        }
        return false;

        if($mode == 'xhtml' && strlen($data[0]) > 1) {
            return true;
        }
        return false;
    }

}

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


===== Comments =====
> For efficiency, I would think you can simplify the entry pattern, to a single <code><side.*?>(?=.*</side>)</code> on the basis that anyone using ''%%<side%%'' in their markup is trying to use this plugin.  In the handler you would then recognize ''right'' & ''left'' and treat anything else as ''%%<side>%%'' as you do now.  I don't know the cost in performance of each additional pattern, however, pattern searching is normally an expensive process and attempting to reduce the number of searches is normally good.  The side effect, grabbing all uses of ''%%<side.*?>%%'' doesn't seem to bad to me. \\ // [[chris@jalakai.co.uk|ChrisS]] 2005-Jul-14//

I disagree --- a better pattern would be ''%%<side(?:\s+[^\r\n>]+)?>(?=.*</side>)%%''.  This would allow the plugin to catch ''%%<note>%%'', ''%%<note left>%%'', or ''%%<note gobble-de-gook>%%'', but allow another plugin to catch, say, ''%%<sideways>%%''.

>> I always knew there was a way, but that it was beyond my regex expertise :-)  --- //[[chris@jalakai.co.uk|Christopher Smith]] 2006-04-22 16:53//

>This plugin slightly breaks the <nowiki>\\</nowiki> line breaker when entering sidenote text. If you use the doubleslashes it throws a full empty line between paragraphs. You are forced to use <br> if you don't want messy spacing between lines. Is it possible to change this plugin so you can set a fixed column width in the tag, and the sidenote will autowrap with you manually needing to enter line breaks? [[dhry@dhryland.com|Dean-Ryan Stone]] 20060807

>I've made a few changes in my copy.
>  - Type is now back to 'container' in the function getType(). This better suits the plugin.
>  - The PType is now 'normal'. I couldn't get the output to validate otherwise.
>  - The entry pattern is the one given in reply to ChrisS's regex.
>  - In the functions render() and handle I removed the //if{}else if{}else{}// statements and replaced them with switches. It's just neater that way.
>  - In the function handle() I replaced: <code php>
if (preg_match('/left/', $match)>0) {
    return array('',$state,'left');
} else if (preg_match('/right/', $match)>0) {
    return array('',$state,'right');
} else {
    return array('',$state,'');
}
</code> with <code php>
preg_match('/<side\s*([^\r\n>]+)>/',$match, $matches);
return array('',$state,$matches[1]);
</code> It's faster and cleaner.
> 
>  - Added 'protected' as an allowedmode so that I could include HTML within the side block.
>  - A few cosmetic changes to the CSS so that the background was a solid color and there was a bit of padding & margin.
> --- // [[adam@alphacomplex.org|adam]] 2006-08-16 11:42 //

> I just got an email asking for my changes to this plugin and I figured that if I was going to create a patch I may as well post it here. Feel free to download my [[http://alphacomplex.org/~adam/oss/dokuwiki/plugins/sidenote/sidenote.diff|sidenote.diff]], it's GPL2 of course. To apply the diff cd to the sidenote plugin directory (dokuwiki/lib/plugins/sidenote/) and run <code bash>patch -p1 < /path/to/sidenote.diff</code>
> --- // [[adam@alphacomplex.org|adam]] 2006-12-15 09:22 //

> This plugin has helped me out significantly, brilliant work!
> --- // [[sam@samuelmiller.biz|sam]] 2010-12-31 13:03 //