Usage of WackoFormatter

1. Simple usage


Simple usage is really simple:


<?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.

2. Advanced usage


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

2.1. Default config class



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

//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 "}}"; } //\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 /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.

2.3. 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.

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: 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.

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.

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


For example: Disable WikiLinks



'disable_wikilinks' => 1,

and your CamelCase Words will no longer be linked directly to a new page.

2.6. Example config class


<?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 
"\xa2\xa2" $url " == " $text "\xaf\xaf";
  }

  
//preformat action
  
function wrap_action($action)
  {
   return 
"\xA1\xA1" $action "\xA1\xA1";
  }

  
//format link
  
function link ($tag$options$text)
  {

   
$text htmlspecialchars($textENT_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') != && 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($tagENT_NOQUOTES);
     return 
'<a href="' $tag '">' $text '</a>';
   }
   return 
$text;
  }


?>


(See example_adv.php)