SimpleWiki Extensions

posted November 21, 2009; updated June 18, 2011

Overview

There are a number of ways to extend the SimpleWiki Markup Language. Indeed the SimpleWiki Module includes many native extensions.

Extension Method	Applies to	Description
Style Classes	decorators, declarations	any appropriate class (as made available through .css files) can be passed to the underlying object's class attribute
Style rules	decorators, declarations	any appropriate style rule can be passed to the underlying object's style attribute
Attributes	decorators, declarations	Any appropriate attribute can be passed to the underying object
Action Classes and Properties	decorators, declarations	Class names and property names trigger calls to registered client callback functions before emitting, which can then emit interesting html, or perform operations on the parsed document object model. The SimpleWiki module currently provides several of these, notably the span decorator action class footnote
Macros	client source code - PHP	Macros must be provided and registered by client source code - PHP. The SimpleWiki module currently provides the quicktoc macro
Symbolic Links	links, images	format: [[Symlink:selector | ... ]] or {{Symlink:selector | ... }}. Client software registers symlinks and their replacement paths, or provides a callback routine (handler) to look them up
Raw Links	links, images	format: [[rawlink | ... ]] or {{rawlink | ... }}. For links that aren't anchors, external links (with recognized protocols), or symlinks, client software can provide a callback routine (handler) to interpret the raw link. For example for classic single-term wiki links.
Events	client source code - PHP	The SimpleWiki module currently defines two events: onemit and onafteremit
Tag Defs	client source code - PHP	Client software can register a tag def handler (block or inline tags, or block or inline void - single - tags), which can authorize any block or inline tag, and manipulate tag def node data. Client source code can also change the set of tags allowed by the markup
Character filters	client source code - PHP	Client software can register a charfilter handler, when an alternate filter to htmlspecialchars(...) is desired.

Style Classes

A number of commonly used style classes are provided with the implementation module in SimpleWiki.css (Native Style Classes).

In addition websites can (and should) provide their own. For example we have framework.css and content.css files.

Style Rules

Any appropriate style rules in the format rulename:rulevalue can be added to any decorator or block declaration argument. Rule values can be delimited with single or double quotes if required. ^[1]

Attributes

Any appropriate attribute in the format atributename=attributevalue can be added to any decorator or block declaration argument. Single or double quote delimiters can be added to attributevalue in order to group values containing spaces. If no quotes are used then SimpleWiki adds them during html emitting.^[2]

Action Classes and Properties

Action classes and properties are software processes that modify the underlying HTML in some way. More can be added by client software (see Module for details). Here are the action classes defined natively for SimpleWiki:

Element	Classname	Effect
Span
%s subscript%	subscript	change span element to sub element
%s superscript%	superscript	change span element to sup element
%s footnote%	footnote	create a footnote, with on-page sequentially numbered links to and from the footnote
%s comment%	comment	create an in-line comment, which is stripped out when rendering
Link
%l newwin%	newwin	open the following link in a new window
Image
%i lframe%	lframe	wrap the image in a div and float left
%i rframe%	rframe	wrap the image in a div and float right
Paragraph
|:p nop:|	nop	(no paragraph) prevents generation of enclosing paragraph html tags
|:p div:|	div	creates an enclosing div element instead of paragraph element
Block Declaration
(:div frame:)	frame	create frame appearance
(:div lframe:)	lframe	create frame appearance and float left
(:div rframe:)	rframe	create frame appearance and float right
Preformatted
|:pre html:|{{{	html	contents of preformatted block treated as HTML
%c html%{{{	html	contents of inline preformatted text treated as HTML

Macros

Macros have to be written and registered by client software. Simplewiki provides one macro - quicktoc - which generates a page table of contents from page headings.

Macro syntax is

<<macroname arguments | parsed-inline-markup>>

The macroname is required, but arguements and parset-inline-markup are optional (depending on the requirements of the macro).

For quicktoc, there are no arguments. parsed-inline-markup, if provided, is used as the table of contents header (otherwise the caption "Table of contents" is used).

Symbolic Links

Symbolic links are one of the ways to referece links or images (see Symbolic Links in the language definition). The format is:

Symlink:selector

Two symlinks are predefined: Local and Anchor, and both, by default are empty. Local is provided for relative directory addressing. Anchor is provided for on-page links ([[#anchorname|anchor text]]). Either can be over-ridden by the client software.

Client software can register its own symbolic links, or indeed a callback function to lookup value for any symbolic link used by authors. See Module for details.

Raw Links

Raw links are links that have not been parsed as anchors, external links (with the recognized protocols http, https, mailto), or symlinks. Client software can intercept these and substitute valid html links. For example this would allow users to write classic one-term wiki links: [[WikiLink|some other wiki page]].

Events

There are currently two events defined by SimpleWiki: onemit and onafteremit. These are for specialized requirements. For example SimpleWiki provides for a method that can be registered with onemit to automatically generate quick tables of content for all pages (see Module for details). The footnote action class uses the onafteremit event to generate footnotes at the end of a document.

Tag Defs

Client software can register a tag def handler (block tags, block void - single - tags, inline tags, inline void - single - tags), which will receive the tag def node after parsing and before emission modifications. Thus any tag defs can be authorized, and arbitrary actions can be taken in response to tag def node handling.

To change the set of tags allowed by the markup, first get a copy of the emitter. Then get and change the set of allowed tags, and save them back to the emitter:

$wiki = new SimpleWiki();
$emitter = $wiki->emitter();
// get copies of the allowed extended tag sets:
$blocktags = $emitter->blocktags(); // block tags
$vblocktags = $emitter->vblocktags(); // void block tags
$itags = $emitter->itags(); // inline tags
$vtags = $emitter->vtags(); // void inline tags
... // change the arrays of allowed tags
// reset the tag sets
$emitter->blocktags($blocktags); // block tags
$emitter->vblocktags($vblocktags); // void block tags
$emitter->itags($itags); // inline tags
$emitter->vtags($vtags); // void inline tags

Character filters

The Simplewiki emitter returns strings filtered with htmlspecialchars(...) for literal text, by default. Client software can process these strings with alternate or custom character filteres as desired. For example, to support utf-8 entities for your authors (like ✓ (decimal) or ✓ (hex) = checkmark), do the following:

Configure your instance of simplewiki like this:

$simplewiki->register_charfilter_handler(array($this,'process_htmlentities'));

Then define the charfilter handler thus:

public function process_htmlentities($text,$node) // not using $node parameters
{
 return htmlentities(html_entity_decode($text,ENT_COMPAT | ENT_HTML401,'UTF-8'),
	ENT_COMPAT | ENT_HTML401,'UTF-8');// allow html entities
}

---