View source for Usage of WackoFormatter

{{toc numerate=1}}

===Simple usage===

Simple usage is really simple:
%%(php)
<?php
require_once 'class/WackoFormatter.php';

$parser = new WackoFormatter();
$formatted = $parser->format($text); 
?>
%%
(See example.php)

But simple usage cannot provide **actions** and **highlighters** functionality, either **request-time linking** and **custom linking** features.

===Advanced usage===

If you want to use advanced features of WackoFormatter, you should create custom config-class.

====Default config class====

%%(php)
<?php
class WackoFormatterConfigDefault
{
	function __construct() {}

	// return unique identifier of this page
	function get_page_id() { return 0; }

	// return value of some configuration option
	function GetConfigValue($option) { return false; }

	// format piece of text with some formatter
	function format($text, $formatter = false) {return $text;}

	// preformat links
	function pre_link($url, $text = false)
	{
		if (!$text) $text = htmlspecialchars($url);

		return '<a href="' . $url . '">' . $text . '</a>';
	}

	// preformat action
	function wrap_action($action)
	{
		return '{{' . $action . '}}';  // <!--action:end--><!--/notypo-->
	}

	// format link
	function link ($url, $options, $text)
	{
		if (!$text) $text = htmlspecialchars($url);

		return '<a href="' . $url . '">' . $text . '</a>';
	}

	// run some action
	function action($action, $params)
	{ 
		return ''; 
	}
}

%%

====Actions====

Action is dynamic substance. Bluntly speaking, it's a PHP code snippet that provide some dynamic information. You can see manual about WackoWiki's actions at ((/Doc/English/Actions)).

Right now, WackoFormatter (rather WackoFormatterConfigDefault) doesn't provide functions for action calling — you need to redefine ##action()## method and implement it by yourself. I'm not inconceivable that we'll provide advanced WackoFormatterConfig in future.

====Highlighters====

Highlighter is code that does text formatting. For example, some programming language highlighter or highlighter for Jabber logs.

Right now, WackoFormatter (rather WackoFormatterConfigDefault) doesn't provide functions for highlighter calling — you need to redefine Format() method and implement it by yourself. I'm not excepting that we'll provide advanced WackoFormatterConfig in future.

====Linking====

WackoFormatter doesn't process links by himself. It just call ##link()## method, where should be all "fuzzy logic".

Right now, WackoFormatterConfigDefault provides basical linking procedures, but if you want to upgrade them, you need to redefine ##link()## method and implement it by yourself. I'm not excepting that we'll provide advanced WackoFormatterConfig in future.

There's two methods for linking: ##pre_link()## and ##link()##. We need both because common usage looks in the following way:

  1. On save we format text, then store it to Database. Here we only ##pre_link## text.
  2. On request we get text from Database, do actual linking, then send HTML to User-Agent. 

Why we don't do actual linking before storing into Database? Due to dynamic nature of any Wiki, we don't know today what wiki-link will refer to existing or non-existing page tomorrow. So we need do actual linking strictly when we get page request.

====Options of formatter====

Options stored in associative array ##$this->config## of WackoFormatterConfig class.

Current version of WackoFormatter includes these options:

  * ##disable_wikilinks## — if set to 1, disables linking for ##CamelCaseWords##.
  * --##disable_tikilinks## — if set to 1, disables linking for ##~Double.CamelCaseWords##.-- REMOVED
  * ##disable_bracketslinks## — if set to 1, disables ##~[[link]]## and ##~((link))## syntax.
  * --##disable_npjlinks## — if set to 1, disables linking for ##See::Example## and ##user@node:address## links, used in NPJ software.-- REMOVED
  * ##allow_rawhtml## — if set to 1, enables ##""<# #>""## syntax for including raw HTML.
  * ##disable_formatters## — if set to 1, disables ##~%%code%%## syntax, used for highlighters.

You want to use these formatting options? Put them into your config.inc.php script: 

For example: Disable WikiLinks 

%%(php)
'disable_wikilinks' => 1,
%%
and your CamelCase Words will no longer be linked directly to a new page. 

====Example config class====
%%(php)
<?php
// define example customConfig class
class customConfig extends WackoFormatterConfigDefault
{
	function customConfig() {}
	
	// return unique identifier of this page
	function get_page_id() { return $this->id; }

	// preformat links
	function pre_link($url, $text = false)
	{
		if (!$text) $text = $url;

		return '<!--link:begin-->' . $url . ' == ' . $text . '<!--link:end-->';
	}

	// preformat action
	function wrap_action($action)
	{
		return '<!--action:begin-->' . $action . '<!--action:end-->';
	}

	// format link
	function link ($tag, $options, $text)
	{
		$text = htmlspecialchars($text, ENT_NOQUOTES);

		if (preg_match("/^(mailto[:])?[^\\s\"<>&\:]+\@[^\\s\"<>&\:]+\.[^\\s\"<>&\:]+$/", $tag, $matches))
		{
			// this is a valid Email
			return '<a href="' . ($matches[1] == "mailto:" ? $tag : "mailto:" . $tag) . '">' . $text . '</a>';
		}
		else if (preg_match("/^#/", $tag))
		{
			// html-anchor
			return '<a href="' . $tag . '">' . $text . '</a>';
		}
		else if (preg_match("/^(http|https|ftp|file):\/\/([^\\s\"<>]+)\.(gif|jpg|jpe|jpeg|png)$/u", $tag))
		{
			// external image
			return '<img src="' . $tag . '" ' . ($text? 'alt="' . $text . '" title="' . $text . '"' : '') . ' />';
		}
		else if (preg_match("/^(http|https|ftp|file|nntp|telnet):\/\/([^\\s\"<>]+)$/", $tag))
		{
			// this is a valid external URL
			return '<a href="' . $tag . '">' . $text . '</a>';
		}
		else if (preg_match("/^([\!\.".ALPHANUM_P."]+)(\#[".ALPHANUM_P."\_\-]+)?$/", $tag, $matches))
		{
			// it's a Wiki link!
			$tag = $matches[1];
			if (!$text) $text = htmlspecialchars($tag, ENT_NOQUOTES);

			return '<a href="' . $tag . '">' . $text . '</a>';
		}

		return $text;
	}
}
%%

(See example_adv.php)