DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:renderer_plugins

Renderer Plugins

Renderer plugins aka. pluggable renderers, allow to implement different rendering mechanisms for DokuWiki. DokuWiki parses Wiki syntax into an instruction array which then is “rendered” to the desired output format. This output format is usually the XHTML to display a nicely formatted Wiki page. Pluggable renderers allow plugin authors to write their own renderer to output any format they want.

Synopsis

A Renderer Plugin Example needs:

  • class name renderer_plugin_example
  • which extends Doku_Renderer1) or one of it's subclasses.
  • to be stored in a file lib/plugins/example/renderer.php.

Moreover, a plugin.info.txt file is needed. For full details of plugins and their files and how to create more renderer components refer to plugin file structure.

Required implementation

  • You need to implement all methods of the Doku_Renderer class to implement full output of all DokuWiki's markup.
  • getFormat() Returns format of the renderer

Optional implementation

  • canRender($format) Needs to return true for $format = 'xhtml'. This function is needed for a replacement renderer, so DokuWiki knows that it should be displayed in its configuration manager as a xhtml replacement.

Inherited methods

  • nocache() Switches off the caching
  • notoc() Switches off the Table of Contents
  • isSingleton() Returns default false, so the plugin has to be instantiated every use.
  • _simpleTitle($name) Removes any namespace from $name but keeps casing and special chars.
  • _resolveInterWiki(&$shortcut, $reference) Resolves an interwikilink
  • See common plugin functions for inherited function available to all plugins. e.g. localisation, configuration and introspection.

Calling a Renderer Plugin

There are two mechanisms for calling a renderer plugin.

Export

All renderers can be accessed through the export command. This is primarily used to export wiki pages to usually non-xhtml formats.

The output of the plugin is accessed by appending do=export_<plugin name> to the page URL.
e.g. http://www.mywiki.com/doku.php?id=somepage&do=export_s5
or with URL rewriting http://www.mywiki.com/somepage?do=export_s5.

To make the plugin's export mode accessible to the wiki user, add a button or link somewhere using a syntax plugin or action plugin. To create the correct link you should use the exportlink() function.

When your plugin creates a different output format than text/html, you need to set all needed HTTP headers in the metadata of the page. This is best done in the document_start() method of your renderer. Here is an example from the ODT plugin (odt/renderer/page.php):

public function document_start() {
    ...
    ...
    $filename = noNS($ID) . '.odt';
    $headers = [
        'Content-Type' => 'application/vnd.oasis.opendocument.text',
        'Content-Disposition' => 'attachment; filename="' . $filename . '";'
    [;
    p_set_metadata($ID, ['format' => ['odt' => $headers]]);
}

Typical examples of export renderer plugins are:

Replacement Default Renderer

The renderer_xhtml configuration setting allows you to replace DokuWiki's default renderer with your own. Only xhtml renderer plugins should be used for this. Also it's only possible to have one render at a time with this method. For example you have to choose between noblankcells and purplenumbers.

Plugins which wish to use this method should also implement the canRender() method:

public function canRender($format) {
    return ($format == 'xhtml');
}

This method allows DokuWiki to list the plugin in the options for renderer_xhtml setting in its Configuration Manager.

:!: Don't forget to mention the renderer_xhtml setting on the plugin page.

Typical examples of a replacement renderer plugin are:

When a renderer plugin is disabled or uninstalled, it falls back to the default bundled renderer of the requested output format.

Further reading

devel/renderer_plugins.txt · Last modified: 2023-09-01 22:02 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki