Learn about DokuWiki
Learn about DokuWiki
You can customize the design of DokuWiki by creating a new template. A template is determined by 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 starter template because it is clean and follows the DokuWiki template standards.
tpl_getConf(<setting>)to retrieve custom template settings.
A valid template name (directory):
_are not allowed as:
Templates should follow the following directory structure (all paths are relative to the template directory).
CSS files are specified in the
style.ini file. Use as many files you'd like, but you should at least provide one CSS file for the screen presentation and one for printing.
<filename>.css– template's stylesheets
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
metadata.php– configuration metadata describe properties of the settings as used by the Configuration Manager
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
favicon.ico– will be used if none exists in the media-directory (see tpl_favicon())
template.info.txt– A text file with template information required!
A list of available functions can be found in API documentation. Some specialties are listed here.
falsewhile calling it:
This can be used to separate the TOC from the content and place it somewhere else on the screen. See
tpl_toc() below for further details.
tpl_content()function will take care of displaying a Table of Contents itself, 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
<div id="content"> <?php tpl_content(false)?> </div> <div id="sidebar"> <?php tpl_toc()?> </div>
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.
<?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>
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 a 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).
A class named
dokuwiki should be added to some content surrounding element (either around everything or at least around
tpl_content()) in each template's main.php, detail.php and mediamanager.php. This is to make sure that DokuWiki's styles don't interfere with other styles if it gets integrated into an existing site with potentially conflicting CSS.
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 a disclaimer at the bottom of each page.
The DokuWiki's default template looks for files with special names in the template 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 or a template supporting the same include hooks (like the starter 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 template directory e.g.
|Filename||Position of included HTML|
| ||Inside the HTML <head>, use this to add additional styles or metaheaders|
| ||At the very top of the page right after the <body> tag|
| ||Above the upper blue bar, below the pagename and wiki title|
| ||Below the breadcrumbs, above the actual content|
| ||Above the lower blue bar, below the last changed Date|
| ||At the very end of the page just before the </body> tag|
See also include hooks for the user explanation.