Skip to main content

Typo theming

This article has been migrated from f3 Internet, with permission.

Typo is a blogging platform built on Ruby on Rails. It supports theming to change the look and feel of the site. Many themes are available to download from typogarden, or you could write your own.

This article will explain how to create a theme for Typo 5.1.3. It will help if you have a basic understanding of how Rails serves web pages, via its ActionPack framework.

Copy an existing theme

The easiest way to create a new theme is to simply copy an existing one and change it.

The themes bundled with Typo are located in the [typo]/themes directory, where [typo] is the Typo root. Copy one of the theme directories contained within and give it a name similar to (or the same as) the name of your theme. Your new theme directory should contain something like the following:

about.markdown
images
layouts
preview.png
stylesheets
views

I copied the default theme for version 5.1.3, called Typographic, on the assumption that the latest default theme would contain improvements over the previous themes.

Describe your theme

The about.markdown file contains a description of the theme. This will show in the Themes section of the Typo administration interface. Edit it to describe your theme and optionally link to your web site. For example, the brighternet theme simply has the following:

### Brighternet by [Brighternet][1]

Theme for [Brighternet][1]

[1]: http://brighternet.com/

The file uses Markdown syntax.

Customise the default layout

The main layout of the theme is controlled by default.html.erb, in the layouts directory. This is an ERb file, which is basically a mix of HTML and Ruby code, interpreted by Rails.

Feel free to edit and reshuffle the markup, but be careful not to break any Ruby code. If you’re not familiar with ERB, it’s best that you read up on it so that you at least know how to keep it intact.

Reference your stylesheets

The markup generated by the existing templates are generally good, so you may not need to change the default layout much. You will however want to reference your own stylesheets. This is done by changing the name of the CSS files referenced by the stylesheet_link_tag method. Look for lines like the following (remove the space from < % or < %= wherever they occur):

< %= stylesheet_link_tag '/stylesheets/theme/style.css', :media => 'all' %>

This stylesheet_link_tag method will output a HTML link tag that points to the stylesheet. You can have as many of these lines as you’d like and change the name of the CSS file or the media type:

< %= stylesheet_link_tag '/stylesheets/theme/all.css', :media => 'all' %>
< %= stylesheet_link_tag '/stylesheets/theme/screen.css', :media => 'screen' %>

Using the examples above, the stylesheets should be placed in the stylesheets directory, though you could place them elsewhere within your theme directory as long as you edit the stylesheet_link_tag path accordingly.

Customise the views

When Typo displays a page, one of a number of views are inserted into the default layout in place of the following line (remove the space from < % or < %= wherever they occur):

< %= @content_for_layout %>

Each view is represented by an ERb file somewhere in the views directory. The ERb files that do not start with an underscore align with each view – the index page, an individual article, etc.

index.html.erb => The index page, which displays a list of the most recent articles.
read.html.erb => A single article.

Any ERb files that begins with an underscore (like _article.html.erb) are called “partials” and will be used in a number of different views. Look for mention of render :partial =>. For example, the _article.html.erb file is used in both the index.html.erb view and the read.html.erb view.

Override default views

As well as the views that are already in your theme directory, you can override the Typo default views to customise them. In [typo]/app/views there will be the views for all different parts of the application. Views in the articles, live and comments directories are most relevant to your site.

To override a view, copy it into your theme’s view directory, making sure that the directory structure mirrors that of the default views. For example, to override the comment view, create a directory called comments in your theme’s view directory and copy show.html.erb from [typo]/app/views/comments/show.html.erb into it.

mkdir [typo]/themes/[yourtheme]/views/comments
cp [typo]/app/views/comments/show.html.erb [typo]/themes/[yourtheme]/views/comments/show.html.erb

Take a screenshot

View your new theme in a browser and save a screenshot as preview.png. This picture will show up in the Themes section of the administration interface, above your theme’s description.

Gotchas

Caching

If you use fragment or page caching, you’ll need to refresh the fragment cache or rebuild cached HTML if you you alter the theme layouts or views.

Typo caches the theme stylesheets and images in [typo]/public/stylesheets/theme and [typo]/public/images/theme when you select your theme as default. When you alter any of the stylesheets or images, you need to temporarily change to a different theme then back to your theme in order to have the cache updated.

Stylesheets and images

Because of theme caching, your CSS will have to reference images either using an absolute URL that points to the cache (http://thesite/images/theme/…) or a relative URL that steps down two directories (../../images/theme/…). This is annoying because it makes it a hassle to test your design outside of Typo unless you use the same directory structure.

AJAX

Existing themes make use of AJAX, for search and submitting comments for example. Make sure you don’t remove any markup that is needed to update the page when the user does something. Look for mention of things like :update, Element.show and Element.hide to see what HTML tag IDs are being referenced.

Posted by Stephan on 03/10/2008.


Comments

Comments closed.