{{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)