How to design themes for WikkaWiki

Dario — Fri, 11 Sep 2009 22:38:20 +0000

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 tag, adds all the required page metadata inside the element (as well as loading stylesheets, javascript dependencies, favicons etc.), opens the , the global page wrapper (
) and displays the actual page 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
and followed by the comments block (
). 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 (
), a div with wiki action links, page information, copyright and license information and validation links; it then closes the page wrapper, the and the 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.

 echo $this->GetThemePath() ?>/css/wikka.css" />

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 ''."\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 '.$this->Href('revisions.xml', $this->tag).'" />';
echo '';

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!

Wikka in action: 9 screencasts to understand how a wiki works

Dario — Sun, 28 Oct 2007 09:59:45 +0000

If you are new to the concept of a wiki and wish to preview some of the features of WikkaWiki, then these screencasts may be what you are looking for.
Nine short QuickTime videoclips introducing the basics of Wikka.

From simple tasks such as:

creating and editing a page
adding links

to more advanced ones like:

embedding an external feed in a page
adding a code example
adding a Flash object to a page

Check them out: Wikka in Action

Wikka Developer Blog » Documentation