====== ABB Syntax PlugIn ======

---- plugin ----
description: Full power IMG elements for DokuWiki
author     : Ferdinand Soethe
email      : ferdinand@apache.org
type       : syntax
lastupdate : 2007-11-12
compatible : 2007-06-26+
depends    :
conflicts  :
tags       : !obsolete, images, class, id
securityissue: XSS vulnerability allows arbitrary JavaScript insertion. Author informed on 2008-02-24.

downloadurl: #http://www.soethe.net/dokuwiki_plugins/syntax_plugin_abb.zip
bugtracker : 
sourcerepo : 
donationurl: 
----

This plugin brings the full power of the the IMG-element to DokuWiki without having to embed raw html.


===== Usage =====

The easiest use of ABB is just

  ~~ABB~src=wiki:dokuwiki-128.png~~

where //wiki:dokuwiki-128.png// is the name of an image file.
This will embed something like 

  <img src="/dokuwiki/lib/exe/fetch.php?media=wiki:dokuwiki-128.png">

into your page.

As you can see, ABB is followed by one ore more key=value pairs (called parameters) that configure the img-element.

  src=//image-location//

is the only required parameter providing the URL of the image file.

As you can see, the plugin will automatically resolve the image url the DokuWiki-way so you can simply use a reference like you would for adding images with DokuWiki.

==== Adding more Parameters ====

By adding more parameters, you can add further attributes to the image-element created. 
To create an image with a class attribute (which can be styled by a css-handle in a central stylesheet) simply add a class=//MyImageClass// parameter.

  ~~ABB~src=wiki:dokuwiki-128.png~class=MyImageClass~~

To create an image with a id attribute (to be styled individually by a css-handle in a central stylesheet) simply add a id=//MyImageID// parameter.

  ~~ABB~src=wiki:dokuwiki-128.png~class=MyImageID~~

To directly style you image the css-way, add a style attribute that contains your css:

  ~~ABB~src=wiki:dokuwiki-128.png~class=MyImageID~style=width: 30%;float: right;~~

This one sizes the image to 30% of the width of the text column and makes it float right. Please note that I kept the class-attribute so that central style-sheets can add their own css.


==== Limitations ====

The plugin basically translates parameters to html-attributes. The key becomes the attribute name, the value is surrounded by quotation marks and becomes the attribute value. As exceptions to the rule, some attributes get an extra treatment:

  * ''src'' -- the URL of the image is resolved as an internal DokuWiki image.
  * ''title'' -- title attributes are processed with DokuWiki's htmlspecialchars()-function
  * ''alt'' -- alt attributes are processed with DokuWiki's htmlspecialchars()-function

Due to the way the parameters are processed, '=' must ony occur once to separate key from value. A '=' in the value will create unpredictable results.

Also note that the plugin does not check the validity of the resulting HTML tag. So you are entirely responsible for the havoc you create by inventing new attributes for the IMG element. :-)


===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. 

Alternatively, refer to [[:Plugins]] on how to install plugins manually. It's quite easy to integrate this plugin with your DokuWiki:

  - Download the [[http://www.soethe.net/dokuwiki_plugins/syntax_plugin_abb.zip|source archive]] (~5KB) FIXME and un­pack it in your Doku­Wiki plug­in di­rec­to­ry ''{dokuwiki}/lib/plugins'' (make sure in­clu­ded sub­di­rec­to­ries are un­packed cor­rect­ly); this will create the directory\\ ''{dokuwiki}/lib/plugins/abb'' 
  - Make sure both the new direc­tory and the files therein are read­able by the web-server e.g.<code>chown apache:apache dokuwiki/lib/plugins/* -Rc</code>


===== Plugin Source =====

Here comes the [[http://www.apache.org/licenses/LICENSE-2.0|Apache License]] PHP source for those who'd like to scan it be­fore actu­ally in­stal­ling it:

<code php syntax.php>
<?php

/**
 * Plugin Abb: Full power IMG embedding
 * 
 * @license    Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
 * @author     Ferdinand Soethe <ferdinand@apache.org>
 */

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_abb extends DokuWiki_Syntax_Plugin {

	/**
	 * return some info
	 */
	function getInfo() {
		return array (
			'author' => 'Ferdinand Soethe',
			'email' => 'ferdinand@apache.org',
			'date' => '2007-11-11',
			'name' => 'abb - Enhanced Image Plugin',
			'desc' => 'Embed images with the full power of html img-tag',
			'url' => 'http://www.dokuwiki.org/wiki:abb',
		);
	}

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

	/**
	 * What about paragraphs? (optional)
	 */
	function getPType() {
		return 'block';
	}

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

	/**
	 * Connect pattern to lexer
	 */
	function connectTo($mode) {
		$this->Lexer->addSpecialPattern('~~ABB.*?~~', $mode, 'plugin_abb');
	}

	/**
	 * Handle the match
	 */
	function handle($match, $state, $pos, & $handler) {

		$resultStr = '';
		$paramsArr = explode('~', $match);
		for ($i = 0; $i < count($paramsArr); $i++) {
			$paramPairArr = explode('=', $paramsArr[$i]);
			switch ($paramPairArr[0]) {
				case 'ABB' :
					break;
				case '' :
					break;
				case 'src' :
					$resultStr .= ' src="' . ml($paramPairArr[1], '') . '"';
					break;
				
				case 'title' :
					$resultStr .= ' title="' . htmlspecialchars($paramPairArr[1], ENT_QUOTES, 'UTF-8') . '"';
					break;
				case 'alt' :
					$resultStr .= ' alt="' . htmlspecialchars($paramPairArr[1], ENT_QUOTES, 'UTF-8') . '"';
					break;
				default :
					$resultStr .= ' ' . $paramPairArr[0] . '="' . $paramPairArr[1] . '"';
					break;
			}
		}
		return '<img' . $resultStr . '>';
	}
	/**
	 * Create output
	 */
	function render($mode, & $renderer, $data) {
		if ($mode == 'xhtml') {
			$renderer->doc .= $data; // ptype = 'normal'
			
			return true;
		}
		return false;
	}
}
</code>


==== Changes ====

  * 2007-11-12
    * + initial release //[[ferdinand@apache.org|Ferdinand Soethe]] 2007-11-12//

===== Discussion =====

Hints, comments, suggestions...