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 1.2-p1 available

Dario — Tue, 08 Sep 2009 15:28:46 +0000

A patch for WikkaWiki 1.2 (1.2-p1) has been released to fix some minor issues with the support of themes.
Changes on top of 1.2 are described on this page. We recommend installing 1.2-p1 if you experienced problems displaying themes with 1.2 (users potentially affected are those running on Windows servers and Apache servers with mod_rewrite enabled).

Fixing a glitch with themes and mod_rewrite in 1.2

Dario — Sat, 05 Sep 2009 07:38:16 +0000

If your wiki runs on Apache with rewrite_mode on and depending on your server configuration, you may have noticed some glitches with the display of themes. The kubrick theme, for one, doesn’t seem to correctly load the embedded graphics. The fix is simple: rewrite rules should be disabled in the templates folder. Simply create a file with the following content and save it as templates/.htaccess:


        # turn on rewrite engine
        RewriteEngine off

The graphics called by the stylesheets of the themes should now be loaded. The same fix may need to be applied to plugins/templates if you are installing custom themes.

Wikka 1.2 release: Theme support and advanced table markup

Dario — Wed, 02 Sep 2009 14:55:58 +0000

I am proud to announce the release of WikkaWiki 1.2–possibly the most important Wikka upgrade since years.

1.2 is a major release introducing new functionality such as: support for 100%-modular themes, a completely redesigned default layout, menu templates, an advanced table markup, among other enhancements.

The full feature list is available in the release notes, but we will publish in the next days a series of posts to guide users through the new features of Wikka 1.2.

Let me thank Brian for his priceless work on this release, Tormod (who finally sees his brilliant table markup included in an official release) as well as all of our contributors that helped us fix bugs and address issues affecting previous versions over the last months.

Wikka 1.2 is available for download from this page.

Wikka Developer Blog