```## tabid=extensions titletext='SimpleWiki extensions' subjecttext='SimpleWiki Extensions'
<<quicktoc>>

== SimpleWiki Extensions ==
|:p div float:right:|%s smaller%//[[Local:display/article/extensions|view source markup]]//

|:p posting:|posted November 21, 2009; updated June 18, 2011

|:h id=overview:|=== Overview ===

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

|:table standard width:100%:|
``|:th width:20%:||=Extension Method
``|:th width:20%:||=Applies to
``|=Description |
|[[#styleclasses|Style Classes]]|[[Local:language#decorators|decorators]], [[Local:language#declarations |declarations]]|any appropriate class (as made available through .css files) can be passed to the underlying object's //class attribute//|
|[[#stylerules|Style rules]]|[[Local:language#decorators|decorators]], [[Local:language#declarations |declarations]]|any appropriate style rule can be passed to the underlying object's //style attribute//|
|[[#attributes|Attributes]]|[[Local:language#decorators|decorators]], [[Local:language#declarations |declarations]]|Any appropriate attribute can be passed to the underying object|
|[[#methodclasses |Action Classes and Properties]]|[[Local:language#decorators|decorators]], [[Local:language#declarations |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|Macros]]|client source code - PHP|Macros must be provided and registered by client source code - PHP. The SimpleWiki module currently provides the //quicktoc// macro|
|[[#symlinks|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|
|[[#rawlinks|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|Events]]|client source code - PHP| The SimpleWiki module currently defines two events: //onemit// and //onafteremit//|
|[[#tagdefs|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|
|[[#charfilter|Character filters]]|client source code - PHP|Client software can register a charfilter handler, when an alternate filter to {{{htmlspecialchars(...)}}} is desired. |

|:h id=styleclasses:|=== Style Classes ===

A number of commonly used style classes are provided with the implementation module in [[Local:display/public/SimpleWiki.css |SimpleWiki.css]] (Native Style Classes).

In addition websites can (and should) provide their own. For example we have [[Local:display/public/framework.css|framework.css]] and [[Local:display/public/content.css|content.css]] files.

|:h id=stylerules:|=== 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. %s footnote%See for example %l newwin%[[http://www.w3schools.com/CSS/CSS_reference.asp|w3schools css reference]]. For color names see the %l newwin%[[http://www.w3schools.com/html/html_colornames.asp|w3schools color reference]]

|:h id=attributes:|=== 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.%s footnote%See for example %l newwin%[[http://www.w3schools.com/HTML/html_attributes.asp | w3 schools about attributes]] and %l newwin%[[http://www.w3schools.com/tags/default.asp | w3 schools html reference]]

|:h id=methodclasses:|=== 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 [[Local:module |Module]] for details).
Here are the action classes defined natively for SimpleWiki:

|:table standard width:100%:|
``|:th width:20%:||=Element|=Classname|=Effect|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**Link**|
|~%l newwin%|newwin|open the following link in a new window|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**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 |
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 center:|
``|=**Preformatted**|
|~|:pre html:~|~{~{~{|html|contents of preformatted block treated as HTML|
|~%c html%~{~{~{|html|contents of inline preformatted text treated as HTML|

|:h id=macros:|=== 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).

|:h id=symlinks:|=== Symbolic Links ===

Symbolic links are one of the ways to referece links or images (see [[http://simplewiki.org/language#links | Symbolic Links]] in the language definition). The format is:

%s mono%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 [[Local:module | Module]] for details.

|:h id=rawlinks:|=== 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]]}}}.

|:h id=events:|=== 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 [[Local:module | Module]] for details). The //footnote// action class uses the //onafteremit// event to generate footnotes at the end of a document.

|:h id=tagdefs:|=== 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
}}} 

|:h id=charfilter:|=== 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 &#10003; (decimal) or &#x2713; (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
}
}}}