How to design themes for WikkaWiki
With the release of version 1.2, we introduced support for 100%-modular themes in WikkaWiki. We believe a wiki engine should not force you to use its default layout: the best wikis are those that can be modified to seamlessly run behind the scenes without betraying their presence or to match the look and feel of an existing website.
In this post we’ll guide you through the creation of a custom theme.
Where are my themes
A Wikka theme is a collection of PHP files, images, stylesheets as well as optional javascript libraries stored in a theme folder. The typical file structure of a theme folder is as follows:
templates/ ..mytheme/ ....css/ ......mytheme.css ....img/ ....js/ ....footer.php ....header.php
Core themes are stored in the templates/ folder while custom themes can be found (and installed) in plugins/templates/. The theme selector in the user settings lists all the core and custom themes installed on a wiki.
Anatomy of a theme
The basic elements of a theme are the two files: header.php and footer.php. These files are used to generate the elements required for the complete XHTML output of a wiki page.
The default page output is generated through the following steps:
- the page header. header.php opens the <html> tag, adds all the required page metadata inside the <head> element (as well as loading stylesheets, javascript dependencies, favicons etc.), opens the <body>, the global page wrapper (<div id="page">) and displays the actual page header (<div id="header">), i.e. a div that typically contains the wiki name, the name of the current page, an optional logo, and the main navigation links.
- the page content. the main wiki content is then displayed, wrapped in a div called <div id="content"> and followed by the comments block (<div id="comments">). Note that the main wiki content is controlled by the active handler: by default Wikka calls the /show handler but this can vary as a function of the operation (e.g. /edit, /clone, /acls etc.) requested by the user.
- the page footer. footer.php finally generates the page footer (<div id="footer">), a div with wiki action links, page information, copyright and license information and validation links; it then closes the page wrapper, the <body> and the <html> tags. Code required for visitor tracking services (such as Google Analytics) is also typically included in footer.php
It should be noted that a Wikka theme does not need to contain an actual page header or page footer: as long as the necessary XHTML elements are generated and the page layout corresponds to the appropriate selectors in the stylesheet, a theme can use all sort of possible layouts.
Useful theme methods
A number of core methods can be useful to dynamically embed content in a theme:
GetThemePath() can be used to generate URL-rewrite-safe paths to specific theme components (e.g. stylesheets, images, favicons, JS libraries etc.), e.g.
<link rel="stylesheet" type="text/css" href="<?php echo $this->GetThemePath() ?>/css/wikka.css" /> </link>
GetMethod() can be used to test for the active handler, in order to generate output as a function of the currently specified action, e.g.
if ($this->GetMethod() == 'revisions'){ echo '<meta name="robots" content="noindex, nofollow, noarchive" />'."\n"; }
PageTitle() can be used to display the human-friendly title of the current page (i.e. the content of the highest-level heading, if available), e.g.
<title>< ?php echo $this->GetWakkaName().": ".$this->PageTitle(); ?></title>
The $page array can be used to access metadata of the current page, e.g.
if ($this->page["tag"] == 'SandBox')
while config settings can be accessed using the GetConfigValue() method, e.g.:
if ($this->GetConfigValue("hide_comments") == 1)
Href() can be used to create links to a given wiki page using the specified handler, e.g.
echo '<link rel="alternate" type="application/rss+xml" href="'.$this->Href('revisions.xml', $this->tag).'" />'; echo '</link>';
MakeMenu() can be used to generate a menu bar from the specified menu template file, e.g.
< ?php echo $this->MakeMenu('main_menu'); ?>
(we will dedicate another tutorial to menu templates)
Most importantly, you can use the Action() method to embed in a theme any of the actions bundled with Wikka or installed in the plugins/actions/ folder. For example you can embed a Flash object in the page footer via the following line of code:
< ?php echo $this->Action('flash url="http://example.com/example.swf" width="150"'); ?>
On top of Wikka’s internal methods you can obviously use any valid PHP method, e.g. you can display the current date via PHP’s date() function:
<div class="left"><span class="noprint">< ?php echo date("l d F Y"); ?></span></div>
The stylesheet
To style the output of the page you will need to include with your theme a stylesheet with all the CSS selectors that are required to correctly render the template. The best way to make sure all the basic CSS options are included (i.e. those required by the core functionality of the wiki) is to modify the stylesheet included in the “default” template: templates/default/css/wikka.css. To control the output of Wikka using other kinds of media (e.g. a printer or mobile device) you will need to create and load the respective stylesheets.
That’s all folks!
These are just basic instructions to get you started with the design of a custom theme, further information can be found on the documentation server.
We look forward to seeing your best creations!
Good work. This has always been a hangup with wiki’s – the resulting sites always looks too “wiki-ish”. Also I like the Light theme. The first thing I would always do is edit the CSS to fixed-width.
Mauriat
13 Sep 09 at 4:33 pm
Excellent work guys! Our documentation wiki over at http://www.jmonkeyengine.com/wiki has been a central topic for a long time, and we are debating whether DokuWiki should stay or go. This update of yours might’ve tipped the scales for me.
From what I’ve seen so far, it just seems like WikkaWiki makes more plain *sense* as a (wiki) web software when compared to competitors like DokuWiki and MediaWiki. Your direction kinda strikes me as similar to what ZenPhoto did for the gallery ‘market’ when Coppermine and MenaltoGallery were busy getting bloated beyond recognition.
If we end up going with WikkaWiki, I am looking forward to getting more closely affiliated and involved with what I can only hope is a blossoming wikka community. But where’s the blog!?
Do me and yourselves a favor; don’t try to show off by making your wiki something it’s not by utilizing it as a forum application; please go with an *actual* forum, like SMF or BBpress if you wanna keep it simple and easily integrated with your blog.
Erlend
20 Sep 09 at 10:03 am
Hi Erlend,
thanks for the nice words (especially the comparison with ZenPhoto, a project whose vision I really like). I am not sure I understand your point about using Wikka as a forum though. I don’t think we do on any of our websites (there are users who tweaked Wikka to work as a “bliki” but I think I wouldn’t go this way myself).
The reason why we didn’t create a support forum, on the other hand, is that at present the community list and the IRC channel are very effective at handling support requests, while the community website is the best place for finding hacks and user contributed plugins. Rest assured that the day we decide to install a forum we will use a dedicated engine, not a Wikka-based application
Dario
20 Sep 09 at 6:44 pm
I was a bit puzzled by your strict conventions for UserNames. I ran this by my old associates at jfusion.org just to check if it would be compatible with the JFusion integrations, and it seems you’re in the okay on that one. On a different note though, apparently your theme(s) are not entirely HTML & CSS compatible according to the validators listed in this post:
http://www.jfusion.org/index.php/forums/viewtopic.php?f=6&t=4495
Erlend Heggen
30 Sep 09 at 5:06 am
Hi Erlend, we may drop this restriction in the next major release (that will include the FormatUser() method already available in trunk). Glad to hear jfusion found a way around this restriction anyway.
As for the validation issues, the engine currently running the Wikka website is based on a slightly modified version of Wikka. We are going to upgrade it to match the latest release. WikkaWiki 1.2 (as well as any of the previously released versions) is fully XHTML and CSS compliant.
Dario
30 Sep 09 at 11:17 am
Hi Guys,
I was just about to start theming my new Wikka Wiki. Is there a support forum or IRC channel or somewhere one can ask questions?
CpILL
4 Nov 09 at 12:49 pm
–> http://wikkawiki.org/TheLounge
Dario
4 Nov 09 at 1:06 pm
Hi, i really love this Wiki. After trying so many i finally went with this over MediaWiki. The only thing that is letting it down in my opinion is the WikiName convention. Any way this can be changed because i want to integrate it with phpbb? When will the next major release be would you know?
Jonny
11 Nov 09 at 4:21 pm
Hi Jonny, thanks for choosing WIkka. As to usernames, see my response to Erlend above.
We are now working on 1.3, the next major release. We will provide a tentative release date as soon as the final task list has been defined. You can follow the development of 1.3 in the tracker.
Dario
11 Nov 09 at 4:36 pm