Usage of WackoFormatter

Table Of Contents
1. Simple usage
2. Advanced usage
2.1. Default config class
2.2. Actions
2.3. Highlighters
2.4. Linking
2.5. Options of formatter
2.6. Example config class

1. Simple usage

Simple usage is really simple:

require_once("classes/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.

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:

  1. On save we format text, then store it to Database. Here we only PreLink 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.

2.5. Options of formatter

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

Current version of WackoFormatter includes these options:

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;
  }

}
(See example_adv.php)