main.php
Main.php encompasses most pages you'll see when browsing a DokuWiki installation; this includes all of the “DokuWiki actions” listed in the configuration manager.
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 an html tag that tells the browser what language and text direction so that it works in any language.
<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. Additionally, this call is required before most other functions will work.
<head>
<?php tpl_metaheaders()?>
Next is tpl_pagetitle, which (optionally) pulls the first heading to use as the page title. It is shown below with a reference to the title of your wiki1):
<title><?php tpl_pagetitle()?> - <?php echo hsc($conf['title'])?></title> </head>
Once you're ready to display, you'll need the following div tag so that your page works correctly with plugins that use stylesheets.
<body> <div class="dokuwiki">
You'll need all of the utility buttons to really make your wiki functional. Here are all of the buttons provided by the default template — let's put them in a table, above the content:
<table border=1 cellpadding=0 cellspacing=0><tr><td>
<?php tpl_link(wl($ID,'do=backlink'),"Backlinks")?>
<?php tpl_button('permalink')?>
<?php tpl_button('edit')?>
<?php tpl_button('history')?>
<?php tpl_button('recent')?>
<?php tpl_searchform()?>
<?php tpl_button('subscribe')?>
<?php tpl_button('admin')?>
<?php tpl_button('profile')?>
<?php tpl_button('login')?>
<?php tpl_button('index')?>
<?php tpl_button('top')?>
</td></tr></table>
Now consider yourself in the content area of your page. First you'll need a call to the error display function, html_msgarea. This is what allows you to see configuration errors in DokuWiki whenever you have one, 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, 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']) { tpl_breadcrumbs(); } ?> <?php if ($conf['youarehere']) { tpl_youarehere(); } ?>
The climax of the whole process is displaying the content of the page; it's just one call, 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:
<?php tpl_pageinfo()?> - <?php tpl_userinfo()?>
And finally, you need this function to ensure that meta data is properly created for 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:
<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> </head> <body> <div class="dokuwiki"> <table border=1 cellpadding=0 cellspacing=0><tr><td> <?php tpl_link(wl($ID,'do=backlink'),"Backlinks")?> <?php tpl_button('edit')?> <?php tpl_button('history')?> <?php tpl_button('recent')?> <?php tpl_searchform()?> <?php tpl_button('subscribe')?> <?php tpl_button('admin')?> <?php tpl_button('profile')?> <?php tpl_button('login')?> <?php tpl_button('index')?> <?php tpl_button('top')?> </td></tr></table> <?php html_msgarea()?> <?php if ($conf['breadcrumbs']) { tpl_breadcrumbs(); } ?> <?php if ($conf['youarehere']) { tpl_youarehere(); } ?> <?php tpl_content(); ?> <?php tpl_pageinfo()?> - <?php tpl_userinfo()?> <?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.
Avoiding problems
Here are a few problems template developers run into and how to avoid them:
- Don't put JavaScript commands in the body tag of a page, this includes onLoad and others.
Although breaking this rule doesn't affect FireFox at all, Internet Explorer (even IE 7) will have JavaScript errors due to the JavaScript required for page editing, and this can result in pages that won't display correctly, and you will find the editing bar will be missing when you need it.
An alternative to onLoad is to place script tags right before the closing body tag, and there is another script call or two (?) that you can use to attach your own JavaScript.
- Turn off “Compact CSS and JavaScript files” while developing a template.
Some template developers experience problems with DokuWiki cacheing CSS and JS files due to this option being on, although this has been hard to pinpoint. To be safe, turn this off temporarily.
- Use “forced refreshing” after you make changes to CSS files. (You can accomplish this by holding down shift-control-alt and hitting the refresh button in your browser.)
This is not due to how DokuWiki works, but how current browsers cache files. All current generation browsers appear to cache stylesheets even when new versions are available, so you will need to do this.
Source
The source of the default main.php can be found here.
Revised by — Terence J. Grant 2007-02-06 04:51
