WackoWiki: Usage of WackoFormatter

https://wackowiki.org/doc     Version: 13 (28.06.2022 06:50)

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

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[link1].

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:


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 '<!--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)