The Net is Dead

Typo is probably the newest kid on the block in the blogosphere when it comes to the tools that enable us to run our little weblogs. Powered by Ruby on Rails and packed with fancy AJAX goodies it sure is the most buzz compliant weblog software one can possibly get. After playing around with it for over a month I must admit I kinda like Typo. Even though it's still young and even though it doesn't have the rich feature-set and plugin community that other tools such as WordPress, Movable Type or Pivot have it looks like a rather promising little blog engine. If you're a regular reader of this weblog you'll know I've been very busy creating a theme for Typo last month because a powerbook and an ibook were up for grabs in the Typo theme contest. At the moment of writing I'm still keeping my fingers crossed for the final verdict of the jury.

What I do know already is that my submission Lush received a fair amount of positive comments. I've seen it in use on quite a lot of Typo powered weblogs already which tells me I at least succeeded in providing something nice for a part of the Typo community. This week I was invited by Piers Cawley, a member of the Typo community, to write an essay on the process of creating a theme for Typo. I figured this would be a nice subject for a new weblog posting which is why I accepted and which is why you're reading this posting. So here we go. Let's have a look at what it takes to create a cutting edge theme for Typo.

Installing Typo

Let's start with the hard part: getting Typo to run. Here's an area which has clearly been covered up by the Ruby on Rails hype machine started by the folks over at 37Signals. While Ruby on Rails may very well be an excellent agile development environment, the install process sure as hell wasn't that 'agile'. While setting up an apache server with PHP and MySQL is as easy as making a cup of coffee these days, getting the Rails environment and Typo going felt like 'going to hell and back'. Since I did manage to deliver a fully functional Typo theme you may conclude that I managed to get it installed eventually. There's definitely some work to be done here. I didn't plan for this article to become a 'how to install Rails' guide but I'll give some pointers nevertheless. There are several things that tend to go wrong a lot of times so maybe this list may save you at least a part of the trouble.

• Once you've unpacked Typo, make sure that your_typo_dir/public/ becomes the root directory of your new Typo powered website
• Go through your_typo_dir/public/.htaccess and check whether everything is right
• Make sure you've edited your_typo_dir/config/database.yml and all databases are setup correctly. This is where things often go wrong. Double, no, triple check whether the stuff you entered here really works. Even though real Rails developers have three databases, one for production, one for development and one for testing I've found it's perfectly acceptable to use just one database when you're building a theme. Therefore you can enter the same database for all three modes.
• When first testing your kit, try to start the built-in Webrick server. Do this by going into your Typo install dir at the commandline and typing ./script/server -e development. Don't start it from within the script directory or from anywhere else! This should fire up a tiny http server running at http://your.host.com:3000. Try if you can access it. If it works you can continue muddling in an attempt to get it to run with Apache fastcgi (I used this) or the recommended Lighthttpd variant. I never tried Lighthttpd so you'll have to get your info on that elsewhere.
• Run in development mode at all time or Typo will cache everything into oblivion. That means your changes won't be visible until you manually flush the cache from within Typo's admin area.

As I pointed out before, this isn't an install guide. I'm not proficient enough when it comes to Rails and the installation issues that surround it to write such a guide. But... let's assume you managed to get Typo going and you want to create a nice looking theme for it!

Which Typo? Trunk or release

Typo is changing rather rapidly and as far as I'm concerned the so-called 'Trunk builds' are the way to go if you want your theme to work on future versions of Typo. I've even heard that (some) Typo 2.6.0 (current release) themes are likely to break when the next major release comes out. As stated on the Typo site, Trunk builds are usually rather stable. I can acknowledge that claim wholeheartedly. When developing my contest theme I've used various Trunk builds between v747 and v760 and never encountered any problems. Getting a trunk build is easy as well. It's explained on this Wiki page. If you need to get it with Windows, just download TortoiseSVN and install it. Right click on any windows folder and choose 'SVN Checkout'. Type svn://leetsoft.com/typo/trunk in the box called URL repository: and hit OK. It's that easy really. You now have the same thing you'd have when downloading a release zip except for the fact that this is the latest Trunk release. Get it installed using the pointers I gave earlier and you'll be rocking with the cool kids who like living on the bleeding edge.

Now that we got that out of the way, let's have a look at the actual theme creation process.

The default theme: 'Azure'

Typo comes with a default theme named 'Azure'. It's a a simple but elegant theme which can serve as a perfect starting point for your Typo theming endeavour. 'Azure' is what you see when you first check out your Typo powered weblog once you got it up and running. Now let's start hacking it.

Inside your typo directory you'll find a subdirectory named themes/. Go into this directory and you'll see there's another directory named 'Azure'. Copy this directory with everything in it and call the copy whatever you want to call it. Since my Typo theme is named 'Lush' I named mine 'lush'. (Hey, there's a pattern here!).

The first files to edit

You will spend most of the time editing just two files. This will result in a main structure for your theme and all pages Typo generates. Inside your newly created copy of the Azure directory you will find a subdirectory called layouts/. Inside you'll find a file named default.rhtml. This file contains the main (x)html template used in your theme. You can change the entire document structure to your own liking. Make sure however you don't touch any of the ruby code elements you'll find in it. These can be recognized easily because they're surrounded by special tags. They look like this:

<%= link_to config_value('blog_name'), 
{ :controller => '/' } %>

The CSS files

As you can see they're easy to recognize. Most tags have more or less descriptive stuff in it which makes it rather easy to recognize what they're doing, even if you don't know anything about programming with Ruby on Rails. If you do you can do tons of things by tinkering with the Ruby stuff but that's not what this article is about right now. We're only dealing with the design aspect of creating a Typo theme here.

DON'T touch any Typo/Rails tags if you don't know what they're doing. Don't edit them or remove them. If you have no idea what they mean you can easily break your theme. If this is the case just stick to editing the HTML part of the templates. You can create great themes without touching any of the code!

The second file you'll be editing of course is the CSS file. You'll find it inside the stylesheets/ directory inside your theme directory. It's called azure.css for the azure theme. Feel free to change it's name into something else but make sure you also change that name in the CSS link tag on top of the default.rhtml file we just discussed. The call looks like this:

<%= stylesheet_link_tag "/stylesheets/theme/azure", 
:media => 'all' %>

This means that if you renamed the file into kickasstheme.css you'll have to change the 'azure' into 'kickasstheme'. In case you decide to add additional stylesheets make sure you place them into the same stylesheets/ directory and link them with the same kind of tag. It's important to use the ruby tag or it might screw up on other people's installs in which things are placed in a subdirectory for example. So, got a print.css file? Just add an extra tag like this:

<%= stylesheet_link_tag "/stylesheets/theme/print", 
:media => 'print' %>

Images done right

Got images? Put them all into the images/ directory inside your theme directory. Whenever you use images in your CSS, refer to them like in the following example:

#somebox  {
  background: url(../../images/theme/some_image.gif);
  }

The path from within your CSS file is always ../../images/theme/ as you can see in the example.

If you want to refer to images from within your HTML, you should NOT use a normal <img> tag because this may result into path issues. Instead, use the 'rails way' of linking to an image:

<%= image_tag("powered.gif") %>

This will correctly create an image tag for the image named 'powered.gif' located in your theme's image dir.

Custom javascript

Got extra javascript? Here's the correct way to link the script in within the head element of default.rhtml:

<% js_path = url_for :controller => 'javascript', 
:action => 'theme', :id => 'yourscript.js' %>
<script src="<%= js_path %>" 
type="text/javascript" />

This example assumes you created a .js file named yourscript.js containing your own nifty javascript stuff which is placed inside the javascript directory inside your theme's directory.

If you've never programmed anything using Rails this may all look rather intimidating. If you've never programmed anything AT ALL this will be even worse. Don't panic though. When I started working on my Typo theme I didn't know a thing about Rails. In fact I still know very little about it. However, if you follow these instructions by the letter, which is what I did, you'll be absolutely fine.

This should be enough information to get you going and finish your theme for 70-80% by just editing these two files. I guess everyone has a different way of working when applying themes/skins to existing cms engines. I myself started with a bare HTML dummy document and set up the main page structure outside Typo. Once my page structure was done I started copy/pasting all relevant Ruby/Typo tags from Azure's default.rhtml into my barebones HTML document. Other people might like to immediately edit the Typo template itself. Do whatever you like best. Once you're done with this you'll end up with a Typo site with your very own page template applied. But of course there's a lot more to customize than just the main page structure!

Advanced theming: overriding views

Azure is a simple but elegant theme. It consists of only one template file: default.rhtml located in your theme's layouts/ directory. You probably noted that this one file doesn't quite contain all HTML that Typo generates. You may already have wondered where the HTML for the comment form is, or how you can customize the HTML for the comments themselves.

If you browse away from your theme directory for a minute and explore the Typo install directory itself you will find a directory named app/. Inside the app/ directory you will find another one named views/. This is where all the stuff is that you already wondered about but were afraid to ask!

Inside your theme directory you will also find one named views/. What we're going to do now is copy all files we want to override into our own views/ directory, INCLUDING any subdirectories they may be in. The most interesting files are in app/views/articles/. Therefore we'll create an articles/ directory inside our theme's views/ directory and copy the files we want to override. Let's have a look at which files are interesting:

_comment.rhtml

This file controls what individual comments look like. A lot of people probably like to customize this.

_comment_box.rhtml

The comment form! Here's your chance to change it into a nifty table-less form.

_comment_error.rhtml

The error message displayed when there's a problem commenting.

_trackback.rhtml

Controls the look of trackbacks

archives.rhtml

Controls the way individual posts look on an archive page.

categorylist.rhtml

Controls a page (that hardly anyone uses) that shows a list of all available categories

comment_preview.rhtml

This is what a comment preview looks like.

error.rhtml

Typo's own error page

index.rhtml

This file controls what individual postings on the frontpage look like. You most probably want to edit this one.

read.rhtml

Another one you might like to change: This controls what a full post view looks like after a user clicked on an entry on the frontpage.

search.rhtml

The search results page in case someone submitted the search form instead of waiting for the AJAX livesearch.

taglist.rhtml

The tag cloud page

view_page.rhtml

This template is used for Typo's static pages created by blog owners from within the CMS.

By customizing all this you can already create a really nice theme. There's one important thing to remember when working with view overrides:

If a Typo/Rails related syntax error is found in a view overriding template, Typo will not use it but use the default one instead.

That means whenever you wonder why nothing changes you probably screwed up something in your overriding template.

Other view overrides

Most of the stuff you might want to override can be found in the app/views/ directory inside the Typo install dir. There's some other interesting ones though.

In app/views/live/ you'll find search.rhtml. This controls the output of the AJAX livesearch. If you feel like overriding it, create views/live/ inside your own theme dir and copy the file named search.rhtml into it and start customizing.

Customizing sidebar plugins

A last thing you may want to do is change the way sidebar plugins look. So far we've seen we can happily recreate the directory hierarchy found in app/views/ in our own views/ directory inside our theme's directory. Not so for the sidebar plugins that come with Typo. You will find those in components/plugins/sidebars/ inside your Typo install dir. Each sidebar plugin has it's own directory. The file we can change is always called content.rhtml. If we want to override sidebar plugin templates we have to recreate what we've found in components/ inside our theme's views/ directory. Not very 'intuitive' but this is the way it is right now. Suppose we want to change the looks of the the del.icio.us plugin. You'll find a content.rhtml file in components/plugins/sidebars/delicious/. Now create your_theme/views/plugins/sidebars/delicious/ and copy the original content.rhtml into it. Edit it and you're changing the way the del.icio.us plugin looks. Wanna do more plugins? It works exactly like in this example for the del.icio.us plugin.

Closing notes

Wow... that was quite a long article! Some people may think creating a theme for Typo is rather difficult compared to creating themes for other weblog systems such as WordPress. This is definitely true. Typo is very young compared to many weblog tools. In fact the underlying framework (rails) is still young even. Therefore let me state the obvious:

Typo isn't really for the faint at heart.

If you want a rock solid, trouble free weblog tool because you don't want to mess around with something that's new, not yet all that documented and not yet all that trouble free, by all means get WordPress, Pivot or something else. However if you want to be part of the buzz-surrounded Rails movement including fancy Ajax features and you're not afraid of getting your hands dirty from time to time, Typo is a very nice little weblog system. Even though I've had my times when I wanted to scream or even destroy my computer because something didn't quite work I can honestly say I had fun creating my Typo theme. What also surprised me in a very positive way me is the friendliness of the Typo / Rails community. There's always someone out there ready and willing to help you out, without the risk of getting flamed or made fun of. Here's a warm thank you to everyone on the #typo and #rubyonrails channels on IRC who helped me solve various issues.

Some tags: Typo, design, theme, template, weblog, ruby on rails, rails.