Travel Guide

How does it work?

The basic concept of the ozimodo tumblelog is very similar to a blog. You log in, compose a post (via the tumble link), then save your post. Your fresh post will show up on your tumblelog once saved.

The title and tags fields are both optional (what, tags?). The post type is the way in which your content will be displayed. Your content will be anything from an image url to a quotation to a rant. If you have the RedCloth gem installed you can use textile in your post titles and content.

We are making a bit of an assumption, here: you are familiar with Rails. If not, there is a wealth of amazing Rails documentation out there. Not to mention some very poignant Ruby documentation, as well. Help yourself.

Tumble Dot YAML

If you want to hang out with the default ozimodo theme, by all means. However, note that there are some out-of-the-box configurable options available to you. Open up ozimodo/config/tumble.yml and have a look.

Whatever the name option is set to will be displayed in the header and title of your tumblelog, as well as in your feeds. Also of interest is the salt option, used by ozimodo for cookie authentication. Just make something up, but try to steer clear of the default.

That Tumbly Look and Feel

ozimodo separates your tumblelog’s rhtml templates and related code from its own code through the use of Rails’ themes. All your blog specific code can be found in themes/your_tumblelog/.

When you’re ready to throw your own HTML at ozimodo, these are the files you will need to edit. Their purposes are pretty self explanatory.

themes/your_tumblelog/tumble/_post.rhtml

This is the important one. Both show.rhtml and list.rhtml call this file for each post. It sets up the basic divs and layout for a post, including anchor links, and then calls a post type (see below) partial.

themes/your_tumblelog/tumble/theme_helper.rb

Check out this file. It’s where you put all your random helpers, ones that have nothing to do with post types (explained below).

Post Types

At the heart of the tumblelog is the dynamic way in which different types of information are displayed. A quote you post may look much different from a link you post. How do you change the display of existing types and add new ones?

Within your tumblelog’s directory structure are three locations which control how posts are displayed:

themes/your_tumblelog/tumble/types/

In this directory are various partials with names like _quote.rhtml or _ruby_code.rhtml. When your tumblelog needs to display the content of a post, it checks this directory for _post_type.rhtml and, if it exists, inserts the post’s content into the local variable content. It then renders this mini-template.

If a post has a post type for which no corresponding partial exists, your tumblelog will use the _post.rhtml partial as a default. Don’t confuse this file with themes/your_tumblelog/tumble/_post.rhtml—there is a big difference between the two.

To add new post types, simply add new files to the themes/your_tumblelog/tumble/types/ directory. Follow the naming scheme and once the file is created a new post type will become available to you in the Post Type dropdown box when creating a new post.

themes/your_tumblelog/stylesheets/types.css

Simple enough. Keep all your type-specific CSS in this file. The styles contained within will always be available to your post type partials.

themes/your_tumblelog/theme_helper.rb

If you need to do any complex (or not so complex) logic, or if you plan to share a function between more than one partial, place that code in this helper file. The functions within will always be available to your post type partials. Code for how to display your crazy post types in your Atom feed also goes here.

Post Types with content Hashes

Sometimes just a content variable isn’t enough. A quote, for instance, may typically have two separate value: the quote itself and the originator. What then?

ozimodo, like an olympic gymnast, is flexible enough to handle these situations with grace. Going with the quote example, you would add a line to the top of themes/your_tumblelog/tumble/types/_quote.rhtml telling ozi you want the content variable to be a hash instead of a string. The line might look like this:

<%# fields: [quote, author] %>

This is an ERB comment; it will not be displayed in your rendered HTML and will be ignored by normal Rails processing. It’s special to ozimodo, though. The line means that instead of just content in your _quote.rhtml file you will have available both content.quote and content.author.

Your complete _quote.rhtml file might then look like this:

<%# fields: [quote, author] %>
<blockquote><%= content.quote %></blockquote><br/>
<% if content.author %>-- <%= content.author %><% end %>

Of course, that’s a simple example. What if you want more control over how the your custom fields are edited on the admin side? Well, you can just tell ozimodo what you want and it will listen. How about, say, an ‘image’ post type?

<%# 
src:
  type: text
  default: http://ozmm.org/images/typed/
alt: text
blurb: textarea
-%>
<img src="<%= content.src %>" class="type-img" alt="<%= content.alt %>" />
<% unless content.blurb.blank? -%><br/>also: <%= content.blurb -%><% end -%>

That makes sense, right? You can also get fancy with stuff like this:

<%# 
quote: 
  type: textarea
  cols: 20
  rows: 30
  default: Nothing to see here.
author: textarea
source:
  type: text
  size: 20
-%>

Eat your heart out.

Note that any changes to a fields: directive requires a restart of your web server, even in development mode.

oz_help_me_out()

app/helpers/tumble_helper.rb

Instead of mucking up your rhtml templates with important decisions and cache-related code, we’ve placed a lot of code into functions contained within this file.

ozimodo helper functions typically follow a format of oz_function_name. Take a peak in this file to see what they do, if you are so inclined, and feel free to use them over and over again in your templates.

Cache It Up

ozimodo automatically uses Rails’ built in page caching to cache your tumblelog.

Make sure that ozimodo/public/cache is writable to your web server. If your app is failing for no (apparent) reason in production mode, this may be the reason.

Please note that as of 1.2, caching is by default off. To turn caching on, edit ozimodo/config/environments/production.rb and change

config.action_controller.perform_caching = false
to
config.action_controller.perform_caching = true

ozimodo themes are like baseball cards! Trade them!

As of 1.2, ozimodo themes are entirely self contained. You can download someone else’s ozimodo tumblelog, slip it into your themes directory, and away you go! This also means you can have more than one tumblelog theme living in the themes directory. While you can’t run more than one tumblelog with the same instance of ozimodo, you can swap between themes rather quickly.

Using A Different Theme

Let’s say you’ve downloaded someone else’s ozimodo tumblelog theme and you want to use it yourself. No problem! To follow along at home, download the ones zeros major and minors theme from http://code.ozmm.org/themes/ozmm-1.2.tar.gz Unzip it into your themes directory so it lives alongside the your_tumblelog directory. Good.

Now open config/tumble.yml and change the ‘themes’ line from your_tumblelog to ozmm, which is the directory name of the theme you downloaded. Start your tumblelog with ruby script/server. When you visit http://localhost:3000 you should see the ozmm.org tumblelog look instead of the default. If it looks almost right but not quite, try clearing your browser cache. (Option-Apple-e in Safari)

Okay okay. That’s all there is to it.

Preparing Your Theme For Trading

In only a few steps, your theme can be as portable as the ozmm theme.

Remember to change config/tumble.yml to specify which theme your tumblelog should be using. Other than that little caveat, it’s all rather elementary, my dear.