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)$/u"$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)