```## 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 |Active 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 active 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//|
|[[#blockdefs|BlockDefs]]|client source code - PHP|Client software can register a blockdef handler, which can authorize any blocktag, and manipulate blockdef node data|
|[[#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:|=== 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 [[Local:module |Module]] for details).
Here are the active 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|
|: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// active class uses the //onafteremit// event to generate footnotes at the end of a document.

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

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