Creating Custom Themes

A typical Thoth theme consists of two parts:

1. Static resources, such as images, CSS, and JavaScript. These live in the public directory. Anything you put in this directory will be visible to the entire world (thus the name).
2. Dynamic templates, or views. These live in the view directory.

Thoth 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.

You could customize Thoth by editing these files directly, but that would be a bad idea since your changes would be blown away the next time you upgrade Thoth. To make things easier, Thoth allows you to configure custom “public” and “view” directories.

If you haven’t already created a home directory for your Thoth site, do that now. It can be anywhere you like and you can name it whatever you want:

mkdir ~/mysite
cd ~/mysite

Next, create a few new directories under your Thoth home directory to hold your awesome new theme.

mkdir -p awesome/public/css
mkdir awesome/view

Now open up ~/mysite/thoth.conf and configure your new theme directories:

theme {
  public "#{Thoth::HOME_DIR}/awesome/public"
  view   "#{Thoth::HOME_DIR}/awesome/view"
}

This tells Thoth to look for custom views and static files in these locations first. If it can’t find a customized version of the file it’s looking for, then it’ll 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 CSS

The quickest and easiest way to change the look of your Thoth site is to customize the CSS. CSS allows you to change colors, background images, and even the positioning of certain elements with very little effort. To make things even easier, you can include Thoth’s default CSS and only override the parts you want to change, so you don’t need to re-style the entire site.

First, copy css.rhtml from the default view directory into your custom view directory:

cp /path/to/default/view/css.rhtml ~/mysite/awesome/view/

Now open the copy in your favorite text editor. It should look something like this:

<link rel="stylesheet" type="text/css" href="/css/thoth.css" />

<% if check_auth %>
  <link rel="stylesheet" type="text/css" href="/css/admin.css" />
<% end %>

Create a new CSS file in your awesome/public/css/ directory named awesome.css, then open it in your text editor. Add the following CSS:

#hd h1 { background: #1d355f; }

Now switch back to awesome/view/css.rhtml and add a reference to your new CSS file:

<link rel="stylesheet" type="text/css" href="/css/thoth.css" />
<link rel="stylesheet" type="text/css" href="/css/awesome.css" />

<% if check_auth %>
  <link rel="stylesheet" type="text/css" href="/css/admin.css" />
<% end %>

Restart Thoth and you should see a beautiful blue header background. Hooray!

Customizing Views

Actually, you already customized a view in the previous section. See how easy that was?

The only thing you need to remember when customizing 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 Thoth 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. Use Ruby sparingly, though: 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.