(actual text copied from wiki:syntax_plugins)

experimental

Syntax Plugins are plugins to extend DokuWikis syntax. To be able to understand what is needed to register new Syntax within DokuWiki you should read how the Parser works.

Amazing ¹⁾

A Syntax Plugin example needs to define a class named syntax_plugin_example which extends DokuWiki_Syntax_Plugin²⁾. The class needs to be stored in a file called lib/plugins/example/syntax.php. The class needs to implement at least the following functions:

• getInfo() Return a Hash with plugin info [author, email, date, name, dest, url]
• getType() Should return the type of syntax this plugin defines (see below)
• getSort() Returns a number used to determine in which order modes are added, also see parser, order of adding modes.
• connectTo($mode) This function is inherited from Doku_Parser_Mode ³⁾. Here is the place to register the regular expressions needed to match your syntax.
• handle($match, $state, $pos, &$handler) (invoked statically⁴⁾) for prepare the matched syntax for use in the renderer
• render($mode, &$renderer, $data) (invoked statically⁵⁾) to render the content

The following additional methods can be overridden when required:

• getPType() Defines how this syntax is handled regarding paragraphs⁶⁾. Return:
  • normal — (default value, will be used if the method is not overridden) The plugin can be used inside paragraphs,
  • block — Open paragraphs need to be closed before plugin output or
  • stack — Special case. Plugin wraps other paragraphs
• accepts($mode) This function is inherited from Doku_Parser_Mode ⁷⁾. It is used to tell the parser if the plugin accepts syntax mode $mode within its own markup. The default behaviour is to test $mode against the array of modes held by the inherited property allowedModes. For more information refer using allowedModes below.

Additional functions can be defined as needed. It is recommended to prepend an underscore to self defined functions to avoid possible nameclashes with future plugin specification enhancements.

Inherited Properties

• allowedModes — default value, empty array. inherited from Doku_Parser_Mode ⁸⁾. Contains a list of other syntax modes which are allowed to occur within the plugin's own syntax mode (ie. the modes which belong to any other dokuwiki markup that can be nested inside the plugin's own markup). Refer using allowedModes below.

DokuWiki uses different syntax types to determine which syntax may be nested. Eg. you can have text formatting inside of tables. To integrate your Plugin into this system it needs to specify which of type it is. The following types are currently available:

For a description what each type means and which other formatting classes are registered in them read the comments in inc/parser/parser.php.

The following only applies to plugins which allow other Dokuwiki markup to be nested inside the plugin's own markup. If no markup is allowed, as with all substitution (type = 'substition') plugins, then allowedModes and accepts() can be ignored - the inherited property and method will suffice.

The classes defined in inc/parser/parser.php to handle Dokiwiki's own syntax modes define their allowedModes within the class constructor method. They can do this as the list of all available syntax modes is complete when they are instantiated. Plugins shouldn't do the same, the list may not be complete. There maybe modes associated with other plugins still to be added. The correct method is to fill the plugin's allowedModes array during the first call to the accepts() method, as shown below.

function accepts($mode) {
 
  if (!count($this->allowedModes)) {
    global $PARSER_MODES;
 
    $this->allowedModes = array_merge (
        // include only the $PARSER_MODES arrays for the syntax mode types allowed to occur within our own mode.
        $PARSER_MODES['container'],
        $PARSER_MODES['substition'],
        $PARSER_MODES['protected'],
        $PARSER_MODES['disabled'],
        $PARSER_MODES['formatting']
     );
 
    // ensure the plugin's own mode isn't included!
    unset($this->allowedModes[array_search(substr(get_class($this), 7), $this->allowedModes)]);
  }
 
  return parent::accepts($mode);	
}