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 [2023-08-17 19:28] – [Common plugin functions] Klap-in | devel:syntax_plugins [2023-09-01 23:53] (current) – Klap-in | ||
---|---|---|---|
Line 7: | Line 7: | ||
A Syntax Plugin //Example// needs: | A Syntax Plugin //Example// needs: | ||
* class name '' | * class name '' | ||
- | * which extends [[xref>DokuWiki_Syntax_Plugin]]((alias of '' | + | * 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 17: | Line 17: | ||
* **'' | * **'' | ||
* **'' | * **'' | ||
- | * **'' | + | * **'' |
\\ | \\ | ||
Line 78: | 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 225: | 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 243: | 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 249: | 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 264: | Line 264: | ||
return true; | return true; | ||
} | } | ||
- | if($mode == ' | + | if($format |
/** @var Doku_Renderer_metadata $renderer */ | /** @var Doku_Renderer_metadata $renderer */ | ||
$renderer-> | $renderer-> | ||
Line 274: | 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 310: | 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 323: | 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: | ||
Line 360: | Line 365: | ||
===== Read also===== | ===== Read also===== | ||
- | * The [[http:// | + | * The [[http:// |
* [[Plugin file structure]] | * [[Plugin file structure]] | ||
* [[Common plugin functions]] | * [[Common plugin functions]] | ||
Line 408: | 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 496: | 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 550: | Line 555: | ||
<code php> | <code php> | ||
public function test_superscript() { | public function test_superscript() { | ||
- | $info = array(); | + | $info = []; |
$expected = " | $expected = " | ||
Line 560: | Line 565: | ||
</ | </ | ||
- | Here we strongly benefit from DokuWiki' | + | Here we strongly benefit from DokuWiki' |
devel/syntax_plugins.1692293321.txt.gz · Last modified: 2023-08-17 19:28 by Klap-in