DokuWiki Template Development

You can customize the design of DokuWiki by creating a new template. Templates are some PHP and CSS files stored in a directory beyond the <dokuwiki>/lib/tpl/ directory. (actually, the template is made of HTML, the PHP in it is used to insert the content.)

The easiest way to create a new template is by taking an already existing one as starting point. It's a good idea to use the default template because it is clean and follows the DokuWiki template standards. Template names (directories) have to be lowercase, ”.” or “_” are not allowed.

1. Copy the lib/tpl/default directory to lib/tpl/yourname
2. Select the new template in the configuration manager
3. Then have a look at the template files (see Directory Layout)
4. Have a look on how DokuWiki handles CSS using its CSS dispatcher.
5. Handling of configuration settings is analogous to plugins. Use tpl_getConf(<setting>) to retrieve custom template settings.

The templates should follow the following directory structure (all paths are relative to the template directory). The CSS files are specified in the style.ini file but you should try to at least provide one CSS file for the screen presentation and one for printing.

• <dokuwiki>/lib/tpl/<template>/
  • <filename>.css
  • main.php – general layout of DokuWiki
  • detail.php – the image detail page
  • mediamanager.php – the media-selection popup
  • images/ – all images used in the template
  • conf/
    • default.php – default settings (see tpl_getConf)
    • metadata.php – configuration metadata (see tpl_getConf())
  • lang/ – language files
    • <lang code>/lang.php – localization strings used in the template
    • <lang code>/settings.php – localization strings used in the configuration manager
  • style.ini – see Style.ini

A list of available functions can be found in API documentation. Some specialties are listed here.

This function outputs the page body, or in other words the content of your wiki page, including the TOC. You can prevent it from outputting the TOC by passing false while calling it:

tpl_content(false);

This can be used to separate the TOC from the content and place it somewhere else on the screen. See tpl_toc() for further details.

By default, the tpl_content() function will take care of displaying a Table of Contents it self, prepending it to the actual page content. If your template uses a sidebar or other more complex layout you may want to place the TOC independently from the page content. This can be done with the tpl_toc() function. When using it, it is important to disable automatic TOC placement by passing the argument false to the tpl_content() function.

Example:

<div id="content">
    <?php tpl_content(false)?>
</div>
 
<div id="sidebar">
    <?php tpl_toc()?>
</div>

The tpl_toc() function renders the TOC from three different sources: a global $TOC variable, the page metadata or the getTOC() method of admin plugins. Because there is no metadata available for old revisions or preview tpl_toc() can only use the global $TOC variable for these cases. Because the $TOC variable is filled by the page renderer this will only work when tpl_toc() is called after tpl_content(). If this is not possible in your template layout you may use output buffering to circumvent the problem.

Example:

<?php
    // render the content into buffer for later use
    ob_start();
    tpl_content(false);
    $buffer = ob_get_clean();
?>
 
<div id="sidebar">
    <?php tpl_toc()?>
</div>
 
<div id="content">
    <?php echo $buffer?>
</div>

This function is used to access configuration settings from within the template.

For a complete list of useful global variables and constants please refer to the environment page.

Almost at the bottom of the default template's main.php file you'll see a function call to tpl_indexerWebBug(). The function generates an HTML <img> tag which results in a request to lib/exe/indexer.php. This vital part of DokuWiki provides important housekeeping work to keep the wiki running smoothly. All templates should include this function, without it the wiki may not function correctly (for example the search index wont be built).

Include Hooks are a simple way to add some static content to your DokuWiki installation without writing your own Template. You can use them for adding a standard header or company logo to each page or add an disclaimer at the bottom of each page.

DokuWiki's default template looks for files with special names in the lib/tpl/default/ directory and simply includes them at the correct places when displaying the page. You can add whatever HTML you like into these files. Of course this only works if you are using the default template.

Hint for PHP developers: You may be happy to hear that you can even include PHP in these files.

All these files are searched for in the lib/tpl/default/ directory.

DokuWiki comes with an example footer.html containing some buttons and a CC license RDF description.