h2. Travel Guide * "How does it work?":#how-it-works * "Tumble Dot YAML":#tumble-dot-yaml * "How to change the look and feel":#look-and-feel * "Adding custom post types":#custom-post-types * "Using the content variable as a hash":#content-as-hash * "Helper functions":#helper-functions * "Caching":#caching * "Switching themes":#switching-themes h1. How does it work? The basic concept of the ozimodo tumblelog is very similar to a blog. You "log in":http://localhost:3000/, compose a @post@ (via the "tumble":http://localhost:3000/admin/new link), then save your post. Your fresh post will show up on your tumblelog once saved. The @title@ and @tags@ fields are both optional (%(aside)what, "tags":http://en.wikipedia.org/wiki/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":http://whytheluckystiff.net/ruby/redcloth/ gem installed you can use "textile":http://hobix.com/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":http://rubyonrails.org/community "documentation":http://api.rubyonrails.org out there. Not to mention some very "poignant":http://poignantguide.net/ruby/ "Ruby documentation":http://ruby-doc.org/, as well. Help yourself. h1. 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. h1. 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/layout.rhtml * themes/your_tumblelog/tumble/list.rhtml * themes/your_tumblelog/tumble/show.rhtml * themes/your_tumblelog/tumble/error.rhtm * themes/your_tumblelog/stylesheets/tumble.css *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@ (%(aside)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 (%(aside)explained below%). h1. 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":http://wiki.rubyonrails.org/rails/pages/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 (%(aside)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. h1. 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":http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/ 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] %> @
<%= content.quote %>

@ @<% 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 -%> @<%= content.alt %>@ @<% unless content.blurb.blank? -%>
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_. h1. 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. h1. Cache It Up ozimodo automatically uses Rails' built in "page caching":http://api.rubyonrails.com/classes/ActionController/Caching/Pages.html to cache your tumblelog. Make sure that @ozimodo/public/cache@ is writable to your web server. If your app is failing for no (%(aside)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@
h1. 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":http://ozmm.org theme from "http://code.ozmm.org/themes/ozmm-1.2.tar.gz":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":http://localhost:3000 you should see the "ozmm.org":http://ozmm.org tumblelog look instead of the default. If it looks almost right but not quite, try clearing your browser cache. (%(aside)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. * Change the name of your theme directory from @your_tumblelog@ to something else. Whatever you want. * Zip it up. * Trade trade trade! 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.