print page  |  view normal version 

Parser and tag sanitizer

One of the most common types of plugins is a parser extension, a plugin that allows new language elements to be used in wikitext.

The Enano wikitext parser allows you to insert new parser rules at any point along the text rendering process. The exact sequence is as follows:

  1. Text surrounded by <nowiki> tags is stripped and replaced with tokens.
  2. The render_wikiformat_veryearly hook is called.
  3. PHP code embedded within a page is stripped and replaced with tokens.
  4. The Carpenter class is initialized.
  5. One of the following three hooks is called, depending on the flags passed to the renderer. This is where you should add your hooks into the Carpenter instance ($carpenter). The Carpenter framework is the core wikitext parser. It allows you to add any hook at the beginning of the render pipeline, before any given stage, after any given stage, and at the end of the pipeline.
    1. render_block_only
    2. render_inline_only
    3. render_full
  6. The render_wikiformat_pre hook is called.
  7. The text is rendered.
    1. After templates are included (and thus the wikitext is done with all preprocessing), the render_wikiformat_posttemplates hook is called.
  8. The render_wikiformat_post hook is called.
  9. nowiki'd text is unstripped.
  10. PHP is unstripped.

All renderer hooks work by modifying the variable $text. All Carpenter hook callbacks must return a non-empty string.

Basic parser hook example, in Carpenter instance

$plugins->attachHook('render_full', 'my_renderer_hook($carpenter);');
 
function my_renderer_hook(&$carpenter)
{
    $carpenter->add_hook('my_callback', PO_AFTER, 'templates');
}
 
function my_callback($text)
{
    return str_replace('Alice', 'Bob', $text);
}

Basic parser hook example, in renderer

$plugins->attachHook('render_wikiformat_pre', 'my_parser_hook($text);');
 
function my_parser_hook(&$text)
{
    $text = str_replace('Alice', 'Bob', $text);
}

It is recommended that you use Carpenter hooks. They give you more control, and can be called at more critical points in the rendering process.

Carpenter API documentation

Carpenter is the wikitext rendering engine. It includes the following built-in rules:

  • lang: Handles the <lang> tag which allows conditional display of text depending on the current language
  • templates: Inclusion of template pages.
  • blockquote: Quoted paragraphs.
  • code: preformatted text
  • tables
  • heading
  • hr: horizontal rule
  • multilist: bulleted and numbered lists. (It can't be just "list", due to that word being a PHP language reserved word)
  • bold
  • italic
  • underline
  • image: Image embedding from the File namespace
  • externalwithtext: External links that have alternate text
  • externalnotext: External links without alternate text
  • mailtowithtext: E-mail links with alternate text
  • mailtonotext: E-mail links with no alternate text
  • internallink: Links to other pages on the site
  • paragraph: Separates text into paragraphs
  • blockquotepost: Post-processing for block quotes.

There are several other methods you can call on the Carpenter instance.

$carpenter->disable_rule(string $rule)

Disables one particular rule and the hooks related to it.

$carpenter->enable_rule(string $rule)

Enables one particular rule and the hooks related to it.

$carpenter->hook(callback $callback, int $when, string $rule)

Adds a callback to be run at the specified point in time. $when should be as follows:

  • PO_FIRST: First in the parse order, before all other rules are run.
  • PO_LAST: Last in the parse order, after all other rules.
  • PO_BEFORE: Run immediately before the rule $rule.
  • PO_AFTER: Run immediately after the rule $rule.

Don't specify $rule unless you use PO_BEFORE or PO_AFTER.

Your callback is passed one parameter, the text. It should return a string. If an empty string, or a datatype other than string, is returned, Carpenter will throw a warning and set the text to an empty string.

$carpenter->exclusive_rule(string $rule)

Solo a rule out (make it the only one called).

$carpenter->disable_all_rules()

Exactly what it says on the tin.

HTML tags

If you don't whitelist HTML tags, Enano will strip them out unless someone has html_in_pages rights.

Whitelisting tags

$plugins->attachHook('html_attribute_whitelist', 'whitelist_my_tag($whitelist);');
 
function whitelist_my_tag(&$whitelist)
{
  // Specify allowed attributes in the array.
  $whitelist["mytag"] = array("myattribute");
  // A tag allowed with no attributes.
  $whitelist["anothertag"] = array();
  // Include a slash in your array if you want the tag to be self closing.
  $whitelist["allowselfclosing"] = array("/");
}

(show page tags)
Categories: (Uncategorized)
© 2007 Contributors. All content is under the GNU Free Documentation License.
Powered by Enano | Valid XHTML 1.1 | Valid CSS | Time: 0.17s