====== 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 to define a class named ''renderer_plugin_example'' which extends ''Doku_Renderer''((defined in [[xref>inc/parser/renderer.php]])) or one of it's subclasses. The class needs to be stored in a file called ''lib/plugins/example/renderer.php''. 

You need to implement all methods of the ''Doku_Renderer'' class to implement full output of all DokuWiki's markup.

===== 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. Eg. ''%%http://www.mywiki.com/doku.php?id=somepage&do=export_s5%%'' or with [[:rewrite|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 [[devel:Syntax Plugins|syntax]] plugin or [[devel:Action Plugins|action]] plugin. To create the correct link you should use the [[xref>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 [[xref>document_start]] method of your renderer. Here is an example from the [[plugin:ODT]] plugin:

<code php>
    $headers = array(
        'Content-Type' => 'application/vnd.oasis.opendocument.text',
        'Content-Disposition' => 'attachment; filename="'.noNS($ID).'.odt";'
    );
    p_set_metadata($ID,array('format' => array('odt' => $headers) ));
</code>

Typical examples of export renderer plugins are

  * [[plugin:S5]]
  * [[plugin:ODT]]
  * [[plugin:slideshow]]
==== Replacement Default Renderer ====

The [[config: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 [[plugin:noblankcells]] and [[plugin:purplenumbers]]. 

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

<code php>
    function canRender($format) {
      return ($format=='xhtml');
    }
</code>

This method allows DokuWiki to list the plugin in the options for renderer_xhtml setting on its configuration page.

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

A typical example of a replacement renderer plugin is

  * [[plugin:XBR]]
  * [[plugin:noblankcells]]
  * [[plugin:purplenumbers]]
  * [[plugin:nodetailsxhtml]]