Porting Wordpress themes to Serendipity - Part 2

The theme banner
We're going to work on the index.tpl file first, start by opening this in your favourite text editor. The header of our new theme isn't working as we would expect it to, so first replace <div id="header"> with <div id="serendipity_banner">

The next line inserts a container div for the home link, and in serendipity this doesn't exist, instead our banner links have a class attribute. Rather than remove the container div, we'll leave it in place, but so that other serendipity users can follow this tutorial and compare this theme against other serendipity themes we'll change the name from title to homelink - note that a normal serendipity theme uses the classes 'homelink1' and 'homelink2'. Our next lines contain the blog title and description. Wordpress themes often only use the blog title and since this theme looks best without the extra line, lets remove the description.

A final amendment to the banner area needs to be the length of the title. In many themes the full length of the blog title easily fits, but due to the graphical nature of this theme we need to add some smarty code to truncate the title to about 40 or 50 characters. In addition, Serendipity allows us to use the blog title on overview pages, and then switch to the entry title on detail pages. I believe this helps search engines to index your content, so lets stick with the status quo.

Our blog and entry title is contained within an <h1>, but within this you'll notice we have some smarty code. I don't intend describing the HTML used in the theme since I assume you are conversant with HTML and CSS. Smarty however is different, so sit back and enjoy reading this short tutorial on the smarty code used in the banner area of our theme. The final banner code weithin the index.tpl file will look like this;

<div id="serendipity_banner">
<div id="homelink">
<h1><a href="{$serendipityBaseURL}">{$head_title|@default:$blogTitle|truncate:40:' ...'}</a></h1>
</div>
</div>

The first smarty variable you should notice is within the link, $serendipityBaseURL. This tells serendipity to include the link back to the startpage, so that regardless of which entry you are reading you can always return to the blog start page. Theoretically you could change this link so that it points to another page within your blog, or perhaps even to your website homepage if this is different. A word of advice though, if you plan to release the theme to other users, stick with serendipity's default link.

You should also notice another small piece of smarty code within the link, and this is more sophisticated than the previous smarty code. It is

{$head_title|@default:$blogTitle|truncate:40:' ...'}

and is quite clever despite its small size. Simply speaking it tells serendipity to insert the blog or entry title into the link text. If you're interested, the words that begin with a dollar sign are smarty variables, whilst the other expressions are smarty modifiers. You probably don't need to know this, but if you ever need to ask a question in the forums about any smarty code you may find one of the serendipity developers will use these terms in their reply.

Ok, enough rambling, how does that code actually work? Well, it tells serendipity to use the entry title ($head_title), but if this doesn't exist, for example if the user is looking at an overview page, then use the default (@default) blog title ($blogTitle). However we've added a twist. If either of these variables ($head_title or $blogTitle) are more than 40 characters, then truncate to 40 characters, and insert three dots at the end (truncate:40:' ...'). Smarty is not infallible and you may find that it doesn't truncate to exactly 40 characters but at least your theme won't look terrible.

Remainder of index.tpl
The dusk theme sets up a containing div for the post within the content column. Wordpress might require this but serendipty already has a container div (.serendipity_entry) for entries which is located in the entries.tpl file. Rather than edit this right now, we will revisit the entries in my next article, lets instead remove the code for the post div. It isn't required and confuses the situation.

You'll also notice that our content div contains another smarty variable $CONTENT, which tells serendipity to open our entries.tpl file and process it. This variable determines where on the page the html output for the the entry body, 'continue reading' byline, extended entry, trackbacks, comments, and comment form are placed. Theoretically you could customise your index template file to place the content anywhere. Clever use of CSS might even allow you to create a theme that looks nothing like a blog.

Sidebars in serendipity are curious things, they contain our sidebar plugins which are dynamically generated by serendipity, and their order or placement is determined by the blog user within the admin suite. Wordpress doesn't have this sophistication, and relies on theme designers to position the plugins. Adding new plugins to a theme can be daunting for WP users who don't have experience of html and php. Serendipity theme designers do need to be aware of this fundamental difference if they plan to port WP themes since in WP a designer may alter the default layout of a plugin, or even create their own within the php code, and the serendipity designer may need to remove this custom coding.

Looking at the sidebar code in our index.tpl, notice the code is fairly simple, it sets up a containing div, and calls two smarty functions. Note I said functions, not variables or modifiers. The function serendipity_printSidebar tells serendipity to print one of the sidebars at this location, which basically means checking the database to see which plugins the user has installed. The additional condition (side="right" or side="left") tells serendipity to build a right or left sidebar as requested by the user in plugin management. Grasping this isn't difficult and you can easily see how this works. The dusk theme is only two column, so both right and left sidebars need to be included. I always place the right sidebar first. I do this because a fresh install of serendipity has all plugins placed in the right column. The user is expected to change this after installation.

Finally, within our index.tpl you'll notice a footer div with the author details. In part one I used an index.tpl from another theme and simply modified it to do what I wanted it to do. Unfortunately, looking at the output I can see that the credits were written differently from the original WP theme. Rebecca, the original author hasn't commented, but I see from her site that she is justifiably proud of her work, and her only request to users of the theme is that here credits remain in place. Out of respect for her wishes, I have changed the serendipity index file. May I encourage serendipity users to do the same. Few of us in the open source community gain any financial result from our efforts, often the only recognition we get is when another user pats us on the back figuratively speaking.

The completed index.tpl now looks like this;

<div id="wrapper">
<div id="serendipity_banner">
<div id="homelink">
<h1><a href="{$serendipityBaseURL}">{$head_title|@default:$blogTitle|truncate:40:' ...'}</a></h1>
</div>
</div>
<div id="content">{$CONTENT}</div>

<div id="sidebar">
{serendipity_printSidebar side="right"}
{serendipity_printSidebar side="left"}
</div>
<div id="footer">
Design by <a href="http://beccary.com" title="Theme designed by Beccary">Beccary</a> and <a href="http://weblogs.us" title="Theme sponsored by Weblogs.us">Weblogs.us</a> · Ported to <a href="http://www.s9y.org">Serendipity</a> by <a href="http://www.carlgalloway.com">Carl</a></div>
</div>
</div>

Editing the stylesheet
We want our theme to maintain the conventions used within serendipity, so some of the dusk style names need to change. This will make it easier to modify in the future, and large chunks of the serendipity code rely on s9y specific style names to work as they were intended.

The changes we need to make to the stylesheet are relatively minor for this article, and simply need us to do the following;

1. change #header to #serendipity_banner
2. change #title, #title h1, and #title h2, to #homelink, #homelink1, and #homelink2