February 27, 2010

I’ve spent the last few days writing a photoblog theme for Habari to run my future photoblog: http://www.eloquium.co.uk so I am now in a position to compare theming on WordPress to theming on Habari.

A lot about writing themes for Habari will seem familiar to WordPress themers. Although Habari has been written in a way that will allow other theme engines to be plugged into it, the default is plain ole PHP as it is in WordPress so a lot of tricks are going to cross over. The main difference that I noticed was just getting used to the Habari ethos; but I will get to that in due course.

The first point where the themeing differs is in the basic theme information. In WordPress it is placed in a comment at the top of the CSS file and looks like this:

/*
Theme Name: WordPress Default
Theme URI: http://wordpress.org/
Description: The default WordPress theme based on the famous Kubrick.
Version: 1.6
Author: Michael Heilemann
Author URI: http://binarybonsai.com/
Tags: blue, custom header, fixed width, two columns, widgets
*/

Habari on the other hand uses an XML file in the root path. Something like this:

<theme>
<name>K2</name>
<author>K2 Team</author>
<url>http://getk2.com/</url>
<version>1.0</version>
<template_engine>rawphpengine</template_engine>
<description>A port of the popular design K2 and first Habari “theme”</description>
<license url=”http://www.apache.org/licenses/LICENSE-2.0.html”>Apache Software License 2.0</license>
</theme>

Hierarchy

When you start to look at theme structure you will see similarities as well, but the flexible nature of Habari means there are small differences.

With Habari content types are easy to create, so, in addition to a normal entry and a page you could create a ‘podcast’ type. Naturally you would want your theme to keep up with that and it does.

Where WordPress uses single.php, archives.php, categories.php, Habari uses entry.single.php and entry.multiple.php. Where WordPress uses page.php Habari uses the same structure as for entries but for the page type, i.e. page.single.php and page.multiple.php.

If you created a plugin that used a new type of entry, ‘podcast’ then Habari would automatically search for podcast.single.php and podcast.multiple.php.

Habari and WordPress both allow more specific theme pages and follow the ’specific to general’ failover path. So where category-stuff.php if missing would pass to category.php so tag.stuff.php would pass to tag.php.

Functions

The big difference is when you get to the functions. As I mentioned earlier, there are similarities,but there is a different ethos at work. Once you have that figured, and it won’t take long at all, things are pretty simple.

Both Habari and WordPress hold the content in a variable called $posts. The loop in WordPress, and an equivalent foreach loop in Habari iterate through $posts and give access to each post. This is where the differences begin.

With WordPress they have created a great many functions that output HTML. These functions access the classes that the do the work, get the content, and output it. Habari doesn’t work this way.

With Habari you are expected to access the classes and make use of the appropriate methods to get the data and echo it. This doesn’t make it much harder for beginners, but it can make things very flexible.

With WordPress you might use:

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
<h2><?php the_title(); ?></h2>
<?php the_content(); ?>
<?php endwhile; else: ?>
<?php endif; ?>

To do the same in Habari you might use:

<?php foreach ( $posts as $post ) { ?>
<h2><?php echo $post->title_out; ?></h2>
<?php echo $post->content_out; ?>
<?php } ?>

The differences don’t immediately seem that significant but obviously themes are much more complicated than this. Where themers may get a little lost with Habari is that WordPress does a lot more work by default. With WordPress you can add a link to the next post with a single function. Whereas with Habari you need to get the next post as an object and then construct the link.

With WordPress:

<?php next_post_link(); ?>

With Habari:

<?php if ( $next= $post->ascend() ): ?>
<div><a href=”<?php echo $next->permalink ?>” title=”<?php echo $next->slug ?>”><?php echo $next->title ?></a> &raquo;</div>
<?php endif; ?>

I personally don’t find this to be a problem. I have had problems in the past with WordPress where functions simple wouldn’t work in a particular scenario, like on the home page, because the author of the function hadn’t foreseen the need. Habari requires a bit more work, but it is much more flexible.

In particular note $post->ascend(); in the Habari example. This is a great example of the object oriented nature of Habari. The $post is contained within the $posts class. By calling the ascend method it tells the containing class to find the next post meeting the parameters you provider, it finds them, and returns the full post object for the next post. You might need to write more HTML than WordPress but you can write whatever you want very easily.

Extending / Writing your own functions

The final thing I want to look at is creating custom functions and outputs. WordPress uses a functions.php file and Habari a file called theme.php. They have similar purposes but work in a very different way.

With WordPress the functions.php file is called in the same way as a plugin. This means that you can do anything in it that you can do with a plugin, such as create new admin pages. It basically extends WordPress as long as the theme is active.

Habari is very different. With Habari, when a theme is loaded it is loaded by the theme class. The class is created and this loads all the necessary information, including the template engine, gets the theme pages and executes them as specified by the theme engine.

What the theme.php file allows you to do is to extend the theme class and tell Habari to use your class instead. This means you can add functions and variables to it for the theme to access, make changes to data etc, but, because it runs when a theme based page is called it doesn’t provide access to the rest of Habari, like the admin area. If you access the admin area the theme does nothing. To make changes here you need to use a plugin (for the time being at least).

Habari encourages you to put your PHP into methods in the theme class instead of in the template files themselves. How much you choose to do that is up to you but it really helps to separate the logic from the presentation. For example, I moved the PHP for the next post link into the theme.php file:

public function next_post_link( $post ){
//get the next post
if ( $next_post = $post->ascend() ) {
return ‘<a href=”‘.$next_post->permalink.’” title=”‘.$next_post->title_out.’”-post>’.$next_post->title_out.’</a>’;
}
}

So across all my theme files I now need only call $theme->next_post_link( $post ), to output the link exactly as I want it.

There’s obviously a hell of a lot more to theming than I have written about here, I have kept it to a comparison of the main differences, rather than the similarities, but I hope you can see from what I have written so far that it isn’t a huge jump.

Update: Check out the themes page for more information on developing themes for Habari.

If there are any Habari masters out there please feel free to chip in with your favourite theme pointers. For anyone else let me know what other points of comparison concern you and I will write my follow up on those areas.