devel:syntax_plugins
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
devel:syntax_plugins [2016-05-10 13:37] – [Table] sample | devel:syntax_plugins [2023-09-01 23:53] (current) – Klap-in | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Syntax Plugins ====== | ====== Syntax Plugins ====== | ||
- | [[plugintype> | + | [[plugintype> |
===== Synopsis ===== | ===== Synopsis ===== | ||
A Syntax Plugin //Example// needs: | A Syntax Plugin //Example// needs: | ||
* class name '' | * class name '' | ||
- | * which extends [[xref>DokuWiki_Syntax_Plugin]]((defined in '' | + | * which extends [[xref>SyntaxPlugin]]((defined in '' |
* to be stored in a file '' | * to be stored in a file '' | ||
Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more syntax components refer to [[plugin file structure]]. | Moreover, a [[plugin_info|plugin.info.txt]] file is needed. For full details of plugins and their files and how to create more syntax components refer to [[plugin file structure]]. | ||
Line 14: | Line 15: | ||
* **'' | * **'' | ||
* **'' | * **'' | ||
- | * **'' | + | * **'' |
* **'' | * **'' | ||
- | * **'' | + | * **'' |
\\ | \\ | ||
Line 28: | Line 29: | ||
* **'' | * **'' | ||
- | 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. | + | Additional functions can be defined as needed. |
\\ | \\ | ||
Inherited Properties | Inherited Properties | ||
- | * **'' | + | * **'' |
Inherited Functions | Inherited Functions | ||
Line 77: | Line 78: | ||
* The '' | * The '' | ||
* add content to the output document with '' | * add content to the output document with '' | ||
- | * access the return value of handle() using the //$data// parameter of render($mode, Doku_Renderer $renderer, $data). | + | * access the return value of handle() using the //$data// parameter of render($format, Doku_Renderer $renderer, $data). |
* ensure any content output by the plugin is **safe** - run raw wiki data through an entity conversion function. | * ensure any content output by the plugin is **safe** - run raw wiki data through an entity conversion function. | ||
* do the minimum possible processing and decision making here, it should all have been done in the '' | * do the minimum possible processing and decision making here, it should all have been done in the '' | ||
Line 158: | Line 159: | ||
==== Sort Number ==== | ==== Sort Number ==== | ||
- | This number is used by the lexer((the part of the parser which analyses the raw wiki page)) to control the order it tests the syntax mode patterns against raw wiki data. It is only important if the patterns belonging two or more modes match the same raw data - where the pattern belonging to the mode with the lowest sort number will win out. | + | This number is used by the lexer((the part of the parser which analyses the raw wiki page)) to control the order it tests the syntax mode patterns against raw wiki data. It is only important if the patterns belonging |
You can make use of this behaviour to write a plugin which will replace or extend a native DokuWiki handler for the same syntax. | You can make use of this behaviour to write a plugin which will replace or extend a native DokuWiki handler for the same syntax. | ||
Line 199: | Line 200: | ||
This is the part of your plugin which should do all the work. Before DokuWiki renders the wiki page it creates a list of instructions for the renderer. | This is the part of your plugin which should do all the work. Before DokuWiki renders the wiki page it creates a list of instructions for the renderer. | ||
- | The complete signature is: '' | + | The complete signature is: '' |
**$match** parameter --- The text matched by the patterns, or in the case of **'' | **$match** parameter --- The text matched by the patterns, or in the case of **'' | ||
Line 224: | Line 225: | ||
</ | </ | ||
- | :!: Any raw wiki data that passes through '' | + | :!: Any raw wiki data that passes through '' |
- | The complete signature is: '' | + | The complete signature is: '' |
- | **$mode** parameter --- Name for the format mode of the final output produced by the renderer. | + | **$format** parameter --- Name for the format mode of the final output produced by the renderer. |
<code php> | <code php> | ||
- | if ($mode == ' | + | if ($format |
// code to generate XHTML output from instruction $data | // code to generate XHTML output from instruction $data | ||
} | } | ||
</ | </ | ||
- | **$renderer** parameter --- Give access to the object [[xref> | + | **$renderer** parameter --- Give access to the object [[xref>inc:: |
**$data** parameter --- An array containing the instructions previously prepared and returned by the plugin' | **$data** parameter --- An array containing the instructions previously prepared and returned by the plugin' | ||
Line 242: | Line 243: | ||
When your plugin needs to extend the content of a wiki page, you need the output format mode '' | When your plugin needs to extend the content of a wiki page, you need the output format mode '' | ||
<code php> | <code php> | ||
- | if ($mode == ' | + | if ($format |
/** @var Doku_Renderer_xhtml $renderer */ | /** @var Doku_Renderer_xhtml $renderer */ | ||
// code to generate XHTML output from instruction $data | // code to generate XHTML output from instruction $data | ||
Line 248: | Line 249: | ||
} | } | ||
</ | </ | ||
- | Detail: the variable '' | + | Detail: the variable '' |
=== Metadata renderer === | === Metadata renderer === | ||
- | A special render | + | A special render |
- | In the metadata rendering | + | In the metadata rendering |
<code php> | <code php> | ||
- | public function render($mode, Doku_Renderer $renderer, $data) { | + | public function render($format, Doku_Renderer $renderer, $data) { |
- | if($mode == ' | + | if($format |
/** @var Doku_Renderer_xhtml $renderer */ | /** @var Doku_Renderer_xhtml $renderer */ | ||
// this is where you put all the rendering that will be displayed in the | // this is where you put all the rendering that will be displayed in the | ||
Line 263: | Line 264: | ||
return true; | return true; | ||
} | } | ||
- | if($mode == ' | + | if($format |
/** @var Doku_Renderer_metadata $renderer */ | /** @var Doku_Renderer_metadata $renderer */ | ||
$renderer-> | $renderer-> | ||
Line 273: | Line 274: | ||
} | } | ||
</ | </ | ||
- | This example uses the [[xref> | + | This example uses the [[xref> |
<code php> | <code php> | ||
- | public function render($mode, Doku_Renderer $renderer, $data) { | + | public function render($format, Doku_Renderer $renderer, $data) { |
if ($data === false) return false; | if ($data === false) return false; | ||
// XHTML output | // XHTML output | ||
- | if ($mode == ' | + | if ($format |
/** @var Doku_Renderer_xhtml $renderer */ | /** @var Doku_Renderer_xhtml $renderer */ | ||
... | ... | ||
| | ||
// for metadata renderer | // for metadata renderer | ||
- | } elseif ($mode == ' | + | } elseif ($format |
/** @var Doku_Renderer_metadata $renderer */ | /** @var Doku_Renderer_metadata $renderer */ | ||
// erase tags on persistent metadata no more used | // erase tags on persistent metadata no more used | ||
if (isset($renderer-> | if (isset($renderer-> | ||
unset($renderer-> | unset($renderer-> | ||
- | $renderer-> | + | $renderer-> |
} | } | ||
| | ||
// merge with previous tags and make the values unique | // merge with previous tags and make the values unique | ||
- | if (!isset($renderer-> | + | if (!isset($renderer-> |
+ | | ||
+ | } | ||
$renderer-> | $renderer-> | ||
| | ||
// create raw text summary for the page abstract | // create raw text summary for the page abstract | ||
- | if ($renderer-> | + | if ($renderer-> |
+ | | ||
+ | } | ||
+ | | ||
... | ... | ||
return true; | return true; | ||
Line 309: | Line 314: | ||
When handling persistent data in the metadata renderer, take care you update also the current metadata, when you update persistent metadata. | When handling persistent data in the metadata renderer, take care you update also the current metadata, when you update persistent metadata. | ||
- | The tag plugin stores here ' | + | The tag plugin stores here ' |
When some raw text from your syntax should be included in the abstract you can append it to '' | When some raw text from your syntax should be included in the abstract you can append it to '' | ||
- | The xhtml mode is called when DokuWiki is in need of a new xhtml version of the wikipage. The metadata is a bit different. In general, the metadata of the page is rendered on demand when '' | + | The xhtml mode is called when DokuWiki is in need of a new xhtml version of the wikipage. The metadata is a bit different. In general, the metadata of the page is rendered on demand when [[xref>p_get_metadata()]] is called somewhere. |
When someone edit a page and use the preview function, the metadata renderer is not called. So the metadata is not yet updated! This is done when the page is saved. | When someone edit a page and use the preview function, the metadata renderer is not called. So the metadata is not yet updated! This is done when the page is saved. | ||
Line 322: | Line 327: | ||
===== Common plugin functions ===== | ===== Common plugin functions ===== | ||
+ | |||
Some function are shared between the plugins, refer to next sections for info: | Some function are shared between the plugins, refer to next sections for info: | ||
* [[devel: | * [[devel: | ||
- | * [[devel: | + | * [[devel: |
* [[devel: | * [[devel: | ||
Line 359: | Line 365: | ||
===== Read also===== | ===== Read also===== | ||
- | * The [[http:// | + | * The [[http:// |
* [[Plugin file structure]] | * [[Plugin file structure]] | ||
* [[Common plugin functions]] | * [[Common plugin functions]] | ||
Line 407: | Line 413: | ||
} | } | ||
- | public function render($mode, Doku_Renderer $renderer, $data) { | + | public function render($format, Doku_Renderer $renderer, $data) { |
// $data is what the function handle return' | // $data is what the function handle return' | ||
- | if($mode == ' | + | if($format |
/** @var Doku_Renderer_xhtml $renderer */ | /** @var Doku_Renderer_xhtml $renderer */ | ||
$renderer-> | $renderer-> | ||
Line 427: | Line 433: | ||
name Now Plugin | name Now Plugin | ||
desc Include the current date and time | desc Include the current date and time | ||
- | url http:// | + | url https:// |
</ | </ | ||
Line 495: | Line 501: | ||
* Create output | * Create output | ||
*/ | */ | ||
- | public function render($mode, Doku_Renderer $renderer, $data) { | + | public function render($format, Doku_Renderer $renderer, $data) { |
// $data is what the function handle() return' | // $data is what the function handle() return' | ||
- | if($mode == ' | + | if($format |
/** @var Doku_Renderer_xhtml $renderer */ | /** @var Doku_Renderer_xhtml $renderer */ | ||
list($state, | list($state, | ||
Line 549: | Line 555: | ||
<code php> | <code php> | ||
public function test_superscript() { | public function test_superscript() { | ||
- | $info = array(); | + | $info = []; |
$expected = " | $expected = " | ||
Line 559: | Line 565: | ||
</ | </ | ||
- | Here we strongly benefit from DokuWiki' | + | Here we strongly benefit from DokuWiki' |
devel/syntax_plugins.1462880221.txt.gz · Last modified: 2016-05-10 13:37 by sample