But simple usage cannot provide actions and highlighters functionality, either request-time linking and custom linking features.
2. Advanced usage
If you want to use advanced features of WackoFormatter, you should create custom config-class.
2.1. Default config class
class WackoFormatterConfigDefault
{
function WackoFormatterConfigDefault() {}
//return unique identifier of this page
function GetPageId() { 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 PreLink($url, $text=false)
{
if (!$text) $text = htmlspecialchars($url);
return "<a href='".$url."'>".$text."</a>";
}
//preformat action
function WrapAction($action) { return "{{".$action."}}"; } //\xA1\xA1<!--/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 ""; }
}
2.2. 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 http://wackowiki.com/actions/newmanual.
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.
2.3. Highlighters
Highlighter is code that does text formatting. For example, some programming language highlighter or highlighter for ICQ 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.
2.4. 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: PreLink() and Link(). We need both because common usage looks in the wollowing way:
On save we format text, then store it to Database. Here we only PreLink text.
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.
2.5. 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.
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.
allow_rawhtml — if set to 1, enables <# #> syntax for including raw HTML.
disable_formatters — if set to 1, disables %%code%% syntax, used for highlighters.
2.6. Example config class
// define example customConfig class
class customConfig extends WackoFormatterConfigDefault
{
function customConfig() {}
//return unique identifier of this page
function GetPageId() { return $this->id; }
//preformat links
function PreLink($url, $text=false)
{
if (!$text) $text = $url;
return "\xa2\xa2".$url." == ".$text."\xaf\xaf";
}
//preformat action
function WrapAction($action)
{
return "\xA1\xA1".$action."\xA1\xA1";
}
//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)$/", $tag))
{// external image
return "<img src=\"".$tag."\" ".($text?"alt=\"".$text."\" title=\"".$text."\"":"")." />";
}
else if ($this->GetConfigValue("disable_tikilinks")!=1 && preg_match("/^(".UPPER.LOWER.ALPHANUM."*)\.(".ALPHA.ALPHANUM."+)$/s", $tag, $matches))
{// it`s a Tiki link!
if (!$text) $text = $tag;
$tag = "/".$matches[1]."/".$matches[2];
return $this->Link( $tag, $options, $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;
}