======divalign plugin======

---- plugin ----
description: Align content left, right, center, or justify
author     : Jason Byrne
email      : jbyrne@floridascale.com
type       : syntax
lastupdate : 2008-03-29
compatible : 
depends    : 
conflicts  : 
similar    : 
tags       : align, div
----

As a DokuWiki newbie, I'm pretty proud to be contributing with my first plugin (I only started using DokuWiki two days ago!).  I think this makes a pretty nice, unintrusive, and intuitive way to align things without going against what I think is a core principle of not adding in html or html-like code to the native wiki format.

==== Updated ====

I've updated the source listing below to remove the security issue.  Any user of this plugin should upgrade to the new version.  To upgrade simply replace the contents of your lib/plugins/divalign/syntax.php file with the code shown below.

The update also includes other changes and improvements:
  * use getAllowedTypes() method rather the constructor to set allowed modes.
  * increase allowed modes to all sensible modes.  Plugin can now wrap around tables, lists, quotes, code and a host of other syntax modes.
  * use core "cdata" instruction to handle content between this plugin's open and closing tags.  This allows this plugin to behave sensibly with other renderers.

 --- //[[chris@jalakai.co.uk|Christopher Smith]] 2008/03/30 01:25//


====Syntax====

Align Left:  

  #;;
  This would be aligned left.
  #;;

Align Right:

  ;;#This is aligned right.;;#

Align Center:

  ;#;
  This is aligned center.
  ;#;

Align Justify:

  ###Justify me baby!###


=====Notes=====

  * The justify doesn't seem to work (at least in Firefox), but I think that's just because the browser doesn't support the style="text-align: justify" or maybe I'm doing it wrong--who knows.
  * The align left doesn't really do anything since everything's already aligned left.
    * No, that depends on the chosen style at design.css - maybe there are freaks centering their pages... ;) at least it helps to break from justify to left.  --- //[[freddyw@gmx.net|Freddy]] 2005-11-15 14:03//
    * By default, text is right aligned for right-to-left languages (arabic, ...) ---//[[viktro@bigfoot.com|Viktor]] 2006-10-14 18:32//
  * As shown in the syntax above, you can do it all in one line or you can break it up.  It just creates a big div around it so you could nest other things in it... whatever.

=====The Code=====

<code php>
<?php
/**
 * divalign: allows you to align right, left, center, or justify
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Jason Byrne <jbyrne@floridascale.com>
 */
 
// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();

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_divalign extends DokuWiki_Syntax_Plugin {
 
    function getInfo(){
        return array(
            'author' => 'Jason Byrne',
            'email'  => 'jbyrne@floridascale.com',
            'date'   => '2008-03-29',
            'name'   => 'divalign',
            'desc'   => 'Add alignment',
            'url'    => 'http://www.dokuwiki.org/plugin:divalign',
        );
    }
 
    function getSort() { return 157; }
    function getType() { return 'container'; }
    function getAllowedTypes() { return array('container','substition','protected','disabled','formatting','paragraphs'); }
    function getPType(){ return 'block';}
 
    function connectTo($mode) {
        $this->Lexer->addEntryPattern(';;#(?=.*;;#)',$mode,'plugin_divalign');
        $this->Lexer->addEntryPattern('#;;(?=.*#;;)',$mode,'plugin_divalign');
        $this->Lexer->addEntryPattern(';#;(?=.*;#;)',$mode,'plugin_divalign');
        $this->Lexer->addEntryPattern('###(?=.*###)',$mode,'plugin_divalign');
    }
    function postConnect() {
        $this->Lexer->addExitPattern(';;#','plugin_divalign');
        $this->Lexer->addExitPattern('#;;','plugin_divalign');
        $this->Lexer->addExitPattern(';#;','plugin_divalign');
        $this->Lexer->addExitPattern('###','plugin_divalign');
    }
 
    function handle($match, $state, $pos, &$handler){
        switch ( $state ) {
          case DOKU_LEXER_ENTER:
            switch ( $match ) {
              case '#;;' : $align = 'left'; break;
              case ';;#' : $align = 'right'; break;
              case ';#;' : $align = 'center'; break;
              case '###' : $align = 'justify'; break;
              default    : $align = '';
            }
            return array($align,$state,$pos);

          case DOKU_LEXER_UNMATCHED:
            $handler->_addCall('cdata', array($match), $pos);
            break;          
        }
        return array('',$state,'');
    }
 
    function render($mode, &$renderer, $data) {

        if ($mode == 'xhtml'){

          list($align,$state,$pos) = $data;
          switch ($state) {
            case DOKU_LEXER_ENTER:
              if ($align) { $renderer->doc .= '<div style="text-align: '.$align.';">'; }
              break;

            case DOKU_LEXER_EXIT : 
              $renderer->doc .= '</div>';
              break;
          }
          return true;
        } // end if ($mode == 'xhtml')
        
        return false;
    }
 
}
 
//Setup VIM: ex: et ts=4 enc=utf-8 :
?>
</code>


===== Discussion =====

Hi, and welcome to the Dokuwiki community :-) 

Some notes on your plugin:
  * multiple exit patterns are probably not a good idea. The first exit pattern encountered will generate a DOKU_LEXER_EXIT state irregardless of which pattern entered.  Admittedly if the syntax is followed there won't be any issues but in poorly formed pages the results could be unexpected.  You may want to consider one exit pattern or four separate component plugins, ''divalign/syntax/left.php'', ''divalign/syntax/right.php'', ''divalign/syntax/center.php'', ''divalign/syntax/justify.php''
  * in handle(), when the state is DOKU_LEXER_ENTER, the match can only be three characters.  You would be better off doing an equate than an ereg().
  * you may want to consider assigning each ''<div>'' a class name and using a ''style.css'' file rather than inline styles.
  * an alternative would be to use the [[plugin:div/span shorthand]] plugin and define four classes, left, right, center and justify in your style sheet.
  * its not good practice to setup ''%%$this->allowedModes%%'' values in the constructor.  Not all plugins are loaded at that time so you may miss including the syntax modes of other plugins.  The ideal method is via the ''getAllowedTypes()'' method.
 --- //[[chris@jalakai.co.uk|Christopher Smith]] 2005-09-24 02:20//
  * right on--it's taken along time for somebody to do something about text alignment. thanks --- //[[warren@literalsystems.com|Warren Smith]]// 
  * Nice Plugin! Thanks! However, I found a problem: when formatting a line with one or more wiki page links in it, a line break is inserted before every page link (so the line is split up). Any idea? --- //[[akr@mheg.org|Andreas Kraft]]//\\
  * Can anyone make this plugin downloadable?? Thank's --- //[[teto9001@gmail.com|Teto]]//\\
  * Bug: when formatting a line (i tried on center), the line breaks when there is a ' --- //[[teto9001@gmail.com|Teto]]//\\
  * This plugin isn't XHTML 1.0 compatible. W3 errors are:
    * document type does not allow element "div" here; missing one of "object", "applet", "map", "iframe", "button", "ins", "del" start-tag.
    * document type does not allow element "p" here; missing one of "object", "applet", "map", "iframe", "button", "ins", "del" start-tag.
    * end tag for "p" omitted, but OMITTAG NO was specified.
  * i have a warning when I save my page ("Warning: Cannot modify header information - headers already sent by (output started at /var/www/grim/lib/plugins/divalign/syntax.php:123"), any idea? --- //[[antoine.pigeau@univ-nantes.fr|Antoine Pigeau]] 2007-06-15 09:20//
    * hi Antoine, I've faced this problem with all plugins that have no installer, looks like it is a post-effect of copying the PHP code intoa file. I pretty much solved it by removing the closing ''?>'' tag in ''syntax.php''. Should work with any hand-coded plugin. Please let me know if this helps. --- this comment from [[http://informatica.temuco.udelmar.cl/~lmachuca/dokuwiki-lucho/|Luis Machuca B.]], a happy DW user (''2007-09-29'').
  * How about including the Syntax into Dokuwiki core? Would probably be nice to have for everyone, not only after cumbersomely installing this plugin via copy&paste...
--- //[[marg@rz.tu-clausthal.de|Christian Marg]] 2008-07-17 00:04//


**An xHTML validation 'fix':**

I agree about the xHTML complicate coding. So I 'fixed' it.

In the "render" method, look for this line...
<code>    if ($align) { $renderer->doc .= '<div style="text-align: '.$align.';">'; }</code>
Change it to...
<code>    if ($align) { $renderer->doc .= '<div class="divalign-' . $align . '">'; }</code>
Also, remove the ''?>'' at the end of the file, it causes trouble down stream.

Then create a ''style.css'' file in your ''divalign'' plugin folder and drop this code in there:
<code>
/* plugin:divalign */

div.divalign-left {
  text-align: left;
}

div.divalign-right {
  text-align: right;
}

div.divalign-center {
  text-align: center;
}

div.divalign-justify {
  text-align: justify;
}

/* end plugin:divalign */
</code>

The plugin is now xHTML complicate!

--- //[[walter@torres.ws|Walter Torres]] 2008-08-24 23:52//