Typo Theme Tutorial

The new Rails-based typo blog engine is out!

Packed with many new features, it¡¯s no longer a lightweight blogging engine. Some of the many new features include:

• Caching of pages and media for much faster response.
• Reworked admin interface with support for two-part posts (teaser paragraph + extended content)
• Drag & drop sidebar elements (archive list, links, Flickr, Ta-da, etc.)

And of course,

• Themes!

Installing Themes

This article won¡¯t talk about upgrading from typo 2.0. I had a fairly easy time since the app itself recognizes the database version being used and will prompt you if it needs to be upgraded (which involves clicking a single button). However, your mileage may vary.

Typo comes with one theme, the ¡°Azure¡± theme. If you download another theme from elsewhere, installing it is as easy as dropping it into the ¡°themes¡± folder at the root of your rails app.

You can log into the admin pages and choose your theme. It¡¯s that easy.

Making Themes

But you don¡¯t just want to use a theme, you want to make one! Let¡¯s make a theme, shall we?

Making a new custom theme

• Copy the contents of an existing theme.
• Put images, stylesheets, and javascripts in your new theme folder
• Edit ¡°your_theme/layouts/index.rhtml¡±
• Take a snapshot and save it as ¡°preview.png¡±
• Write a description in about.markdown

I started a theme called ¡°balloons.¡± I put together some graphics in Illustrator and sliced them up for use on the page.

Next, I made a copy of the existing ¡°azure¡± folder and renamed it ¡°balloons.¡± This is a great way to start because Justin Palmer has organized the stylesheet in a way that makes sense. And, you can concentrate on how your theme will look instead of hunting down the functions used by typo to show the sidebar, live search, etc.

If you aren¡¯t already using it, you need to stop right here and download Chris Pederick¡¯s Firefox Developer Plugin. It has many great features, one of which is under the ¡°information¡± menu and will show you what CSS class names are being used on the page.

The files in your custom theme folder are laid out in a sensible way:

Anything you put into these folders will be available to your theme when it is active. You can also use resources in the normal /public/ directory, but you should keep anything specific to your theme in these folders.

To refer to your resources, add ¡°theme¡± to the path like this:

/images/theme/my_image.png
/stylesheets/theme/my_stylesheet.css
/javascript/theme/my_script.js

Why is ¡°javascript¡± singular while the others are plural? I have no idea.

How does it work?

The routes are setup to look for ¡±/images¡±, ¡±/stylesheets¡±, and ¡°javascript¡± and send back your requested resource.

But it gets better than that! These resources are part of the new caching features in typo and are also cached for quick retrieval. If you start WEBrick in production mode, you can see it in action:

ruby script/server --environment=production

Load a blog article in your browser and look under ¡±/public/images/theme/your_theme/.¡± You should see copies of the images used in your theme. How cool is that?!

If you are still working on your theme, shut down WEBrick and go back into development mode. The files will be deleted and you can start with a clean slate.

Disclaimer: This theme was thrown together hastily as an example only and has only been debugged on Firefox so far. Use at your own risk.

Balloons Theme

Troubleshooting

No project is complete without a few problems. (These issues may be fixed in a future version of typo).

• Some elements are not themeable without modifying original templates in the app directory. For example, the spinner used for live search is referenced from ¡±/app/views/shared/_search.rhtml¡±, so you are stuck with the blue-backed version unless you modify that template.
• Weird session bugs. Sometimes when fine-tuning my theme, rails would stop working and complain about the session key being invalid. A temporary fix is to clean out your session cookie or restart your web browser. Others have also experienced this and are trying to debug it.

Rumors¡­

There are rumors that a typo theme contest may be coming soon and might include prizes such as iPods, health club memberships, or a kilogram of chunky bacon.

Do not bug the typo team about this¡­you¡¯ll hear about it when it happens.

Other Typo Reviews

Encyte Media

Scott Laird