Home of
info@simplewiki.org
- comments
- suggestions
join the forum

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
Active 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 active 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
BlockDefs client source code - PHP Client software can register a blockdef handler, which can authorize any blocktag, and manipulate blockdef node data
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]

Active Classes and Properties

Active 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 active 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
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 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 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 active class uses the onafteremit event to generate footnotes at the end of a document.

BlockDefs

Client software can register a blockdef handler, which will receive the blockdef node after parsing and before emission modifications. Thus any blockdefs can be authorized, and arbitrary actions can be taken in response to blockdef node handling.

Character filters

The Simplewiki emitter returns strings filtered with htmlspecialchars(...) in many cases (for literal text). Client software can process these strings with alternate or custom character filteres as desired.

Footnotes: