Creating Custom Themes

With Rethoth you can customise the look, feel and layout of your blog.

Creating a theme

A Rethoth theme may consist of two parts:

• A collection of images, CSS, and JavaScript files, which live in the public directory and that will be visible to the entire world (thus the name).
• A set of layout templates and views, which live in the view directory.

The code that is placed in the view directory executes in the context of Rethoth (under the Ruby VM) and must adhere to the Ramaze, Sequel and Rethoth APIs. Whereas the code in the public directory will execute in the context of the browser (that requests the rendering of a view).

Rethoth comes with a default set of views and public files. To find out where the defaults are located, run thoth --help and look for the “Default Directories” section. Spend a minute or two poking around those directories to see how they’re laid out.

However, do not customise Rethoth by editing these files directly because your changes will be blown away the next time you upgrade Rethoth.

For every Rethoth project that you create, a set of skeleton “public” and “view” directories get created.

If you haven’t already created a Rethoth site, do that now:

thoth --create ~/myblog
cd ~/myblog

This will create 7 new directories inside ~/myblog.

db
log
media
plugin
public
view
tmp

Rethoth will first look inside your project’s ~/myblog/public and ~/myblog/view directories before it looks into its default directories for custom views and static files. Therefore you may create your theme there. If Rethoth can’t find a customised version of the file it is looking for, it will fall-back to the default theme for that file. This means that your theme only needs to contain files you want to change (or new ones that you add yourself).

Customizing Views

The only thing you need to remember when customising views is that the directory structure and file names inside your custom view directory need to match those of the default view directory, or else Rethoth won’t be able to find your views. You can change the contents of the views to your heart’s content, just as long as the names match.

Views are primarily XHTML, but they can also contain Ruby code. This Ruby code is embedded in the views using the Erubis templating engine. Erubis can do a lot , however make sure you use Ruby sparingly, For example, if statements, loops, and variables are okay, but if you find yourself writing something more complex, you should probably consider implementing it as a plugin instead.

Customizing CSS and JavaScript files only

The quickest and easiest way to change the look of your Rethoth site is to add your CSS files. CSS allows you to change colours, background images, and even the positioning of certain elements with very little effort. You can do this without creating a full blown theme by just telling Rethoth that you want to add your own CSS and/or JS files to its default theme.

In the thoth.conf file of your project (e.g., ~/myblog/thoth.conf) find the css: and js: attributes and edit them. There you can append, in a Ruby array format, the files that you want to rendered by the default theme.
e.g.,

    css: [‘/css/new_file.css’,‘http://example.com/css/some.css’]

The same of course applies for Javascript files. Remember that the new JS and CSS files will be loaded in the rendered pages in addition to the default Rethoth CSS and JS. This way you don’t have to override the CSS and JS templates to customise the default theme.

After you do your customisations remember to restart Rethoth!