main.php template file

main.php encompasses most pages you will see when browsing a DokuWiki installation; this includes all of the “DokuWiki actions” listed in the configuration manager.

A lot of the functionality described here also applies for detail.php and mediamanager.php, i.e. anything until the first div plus html_msgarea() should be shared among all template files.

At a minimum...

Here the bare minimum requirements to get a page to display and interact properly for your template.

Functionality

It's generally a good idea to start your template pages off with doctype and an <html> tag that tells the browser what language and text direction the wiki pages uses.

<!DOCTYPE html>
<html
  xmlns="http://www.w3.org/1999/xhtml"
  xml:lang="<?php echo $conf['lang']?>"
  lang="<?php echo $conf['lang']?>"
  dir="<?php echo $lang['direction']?>">

The first actual php call is to tpl_metaheaders(), which encompasses CSS and JavaScript required and provided by DokuWiki, as well as anything gathered from style.ini.

  <head>
    <?php tpl_metaheaders()?>

Next is tpl_pagetitle(), which uses the page id (or optionally the first heading) to use as the page title alongside the title of your wiki¹⁾. It makes sense to declare the character set just before that:

    <meta charset="UTF-8" />
    <title><?php tpl_pagetitle()?> - <?php echo hsc($conf['title'])?></title>

To add a favicon you can use tpl_favicon() which by default will use the favicon.ico in the template's images directory. But this can be overwritten by uploading that file to your wiki's wiki or root namespace via the media manager.

    <?php echo tpl_favicon(array('favicon')) ?>
  </head>

Once you're ready to display, you'll need to add the tpl_classes() (which also includes the dokuwiki class) somewhere at the top so that your page works correctly with plugins that use stylesheets. The dokuwiki__top ID is needed for the “Back to top” utility.

  <body>
    <div class="<?php echo tpl_classes() ?>" id="dokuwiki__top">

Your template should have some consistent header, displaying the wiki's title and tagline:

      <h1><?php tpl_link(wl(),$conf['title'],'accesskey="h" title="[H]"') ?></h1>
      <?php if ($conf['tagline']): ?>
        <p><?php echo $conf['tagline'] ?></p>
      <?php endif ?>

You'll need all of the utility buttons/links with tpl_action() to really make your wiki functional. Here are all of the buttons provided by the default template.

      <div class="actions">
        <?php tpl_searchform()?>
        <?php tpl_action('admin')?>
        <?php tpl_action('profile')?>
        <?php tpl_action('register')?>
        <?php tpl_action('login')?>
        <?php tpl_action('edit')?>
        <?php tpl_action('revisions')?>
        <?php tpl_action('backlink')?>
        <?php tpl_action('subscribe')?>
        <?php tpl_action('revert')?>
        <?php tpl_action('recent')?>
        <?php tpl_action('media')?>
        <?php tpl_action('index')?>
        <?php tpl_action('top')?>
      </div>

Now consider yourself in the content area of your page. First you will need a call to the error display function, html_msgarea(). This is what allows you to see e.g. configuration errors in DokuWiki whenever you have one, or plugin rendering errors, or lets you see the results of do=check whenever you add that to the end of a URL on your site.

      <?php html_msgarea()?>

Some odds and ends are “bread crumbs” and “you are here” links. You can add them anywhere in the content area, in any order with tpl_breadcrumbs() and tpl_youarehere(), and they are totally optional and up to your discretion. If you're developing a template for general use, you'll want to support both so your end users can choose.

      <?php if ($conf['breadcrumbs']): ?>
        <p><?php tpl_breadcrumbs() ?></p>
      <?php endif ?>
      <?php if ($conf['youarehere']): ?>
        <p><?php tpl_youarehere() ?></p>
      <?php endif ?>

The climax of the whole process is displaying the content of the page; it's just one call tpl_content(), and it's used for all actions — viewing, editing, index navigation, searching, and any page with a form.

      <?php tpl_content(); ?>

Nearing the end of the content section, you can add information about when the page was last modified and who did it and as whom you are currently logged in and what the license of the wiki is:

      <p>
        <?php tpl_pageinfo()?><br />
        <?php tpl_userinfo()?><br />
        <?php tpl_license()?>
      </p>

Many templates display a sidebar when the sidebar config option is set. This will display the content of a page called “sidebar”:

      <?php tpl_include_page($conf['sidebar'], 1, 1) ?>

And finally, you need this function to ensure that the search is functioning properly and is finding your pages:

      <?php tpl_indexerWebBug(); ?>
    </div>
  </body>
</html>

Altogether now...

We have a small sample, workable main.php for a template, and it looks like this:

<!DOCTYPE html>
<html
  xmlns="http://www.w3.org/1999/xhtml"
  xml:lang="<?php echo $conf['lang']?>"
  lang="<?php echo $conf['lang']?>"
  dir="<?php echo $lang['direction']?>">
  <head>
    <?php tpl_metaheaders()?>
    <title><?php tpl_pagetitle()?> - <?php echo hsc($conf['title'])?></title>
    <?php echo tpl_favicon(array('favicon')) ?>
  </head>
  <body>
    <div class="<?php echo tpl_classes(); ?>" id="dokuwiki__top">
      <h1><?php tpl_link(wl(),$conf['title'],'accesskey="h" title="[H]"') ?></h1>
      <?php if ($conf['tagline']): ?>
        <p><?php echo $conf['tagline'] ?></p>
      <?php endif ?>
      <div class="actions">
        <?php tpl_searchform()?>
        <?php tpl_action('admin')?>
        <?php tpl_action('profile')?>
        <?php tpl_action('register')?>
        <?php tpl_action('login')?>
        <?php tpl_action('edit')?>
        <?php tpl_action('revisions')?>
        <?php tpl_action('backlink')?>
        <?php tpl_action('subscribe')?>
        <?php tpl_action('revert')?>
        <?php tpl_action('recent')?>
        <?php tpl_action('media')?>
        <?php tpl_action('index')?>
        <?php tpl_action('top')?>
      </div>
      <?php html_msgarea()?>
      <?php if ($conf['breadcrumbs']): ?>
        <p><?php tpl_breadcrumbs() ?></p>
      <?php endif ?>
      <?php if ($conf['youarehere']): ?>
        <p><?php tpl_youarehere() ?></p>
      <?php endif ?>
      <?php tpl_content(); ?>
      <p>
        <?php tpl_pageinfo()?><br />
        <?php tpl_userinfo()?><br />
        <?php tpl_license()?>
      </p>
      <?php tpl_include_page($conf['sidebar'], 1, 1) ?>
      <?php tpl_indexerWebBug(); ?>
    </div>
  </body>
</html>

You now have all of the buttons, as well as the search field, and this is about everything you need to develop a template.

Look and Feel

An explanation of styles for:

Normal Viewing
Editing
Index Navigation (Or what might typically be called “site map” navigation)
Searching
Form type pages such as registration, profile, administration, configuration, etc.

Should go here, as they all require stylesheet information.

Source

The source of the main.php of the 'dokuwiki' template can be found at lib/tpl/dokuwiki/main.php. The main.php of the Starter template contains even some helpful comments.

DokuWiki

Table of Contents