defunkt / ozimodo

== Welcome to ozimodo 1.2.1

ozimodo is a Ruby on Rails powered tumblelog engine. Its like a blog, but 
different.

Tumblelogs are quick-and-dirty. They are loosely structured and used to share 
various iotas of interest. Throw a link log, a moblog, a quote blog, and a code 
blog (colog? quoblog?) into a blender and out pops a delicious, fat free 
tumblelog.


== Straight to the Source

You probably already know this part, but here it is anyway.

Project Site: http://ozimodo.rubyforge.org
Project Page: http://rubyforge.org/projects/ozimodo/
  Complaints: chris[at]ozmm[dot]org

Too: check us out in IRC on the freenode network in #ozimodo.


== Lay the Blame

ozimodo is a work of collaborative fiction produced with contributions by the 
following wordsmiths:

- Chris Wanstrath (defunkt)
- Dayne Broderson (bish0p)
- Jannis Leidel (jannis)


== Install

=== Ready, Set, Tumble

Awesome, you installed Rails and unpacked the ozimodo tarball into its own directory.  
We'll assume this directory is called 'ozimodo.'

  # Create a database, naming it what you will. 

  # Open up ozimodo/config/database.yml and configure the development section
    to point at your new database.
    
  # Setup the tables using Rails' wonderful migration feature. 
    $ cd ozimodo 
    $ rake migrate

  # Start your development server.
    $ ruby script/server

  # Open your browser (or a new tab, if you're hip) and navigate to
    http://localhost:3000/.  That's it.


=== Hurrah, Hurrah

One more thing... how to tumble?  Surf to http://localhost:3000/admin/ and 
login.  Your username is admin and your very temporary password is changeme.

You may also want to edit some of the options in config/tumble.yml.  This file
is used to determine various behaviors, such as how many posts to display on 
your main page and what site name your Atom and RSS feeds go by.

Now that your tumblelog is up and running like a well oiled piece of 1940's
machinery, you probably want to begin hacking it to bits.  Read on and start 
learning the zen of making your tumblelog an extension of self.

You're going to have to change the permissions of the public/cache directories 
before launching a production app with caching enabled.  Check check check the 
configure info.


=== Dreamers: Apply Within

If you're hosting with the Rails-friendly Dreamhost you may want to check out 
zenchi's guide: Howto Install ozimodo on Dreamhost
- http://www.zenchic.net/articles/2006/04/18/howto-install-ozimodo-on-dreamhost

Of interest: Joseph DeVivo has noted the above instructions didn't work for him on
Dreamhost.  He says: 

  chmoding my log and tmp directories to 0666 like in the dreamhost tutorial you link 
  to actually was breaking my install. chmoding them the way dreamhost 
  suggested fixed it:

  chmod a+x dispatch.fcgi
  chmod -R u+rwX,go-w public log

Joe recommends checking out the Dreamhost wiki's entry on Ruby on Rails:
  - http://wiki.dreamhost.com/index.php/Ruby_on_Rails

=== rescue TheDamnThingBroke

Oh, something went wrong?  Did you check the gigabytes?  They're fine?  In that
case, you have two options:

  * Open a bug in our RubyForge tracker:
    - http://rubyforge.org/tracker/?func=add&group_id=957&atid=3757

  * E-mail chris[at]ozmm[dot]org

  * Peek into our IRC room on freenode at #ozimodo.

Please include a quick copy/paste of the error you encountered. Our crackerjack 
team of lab interns will get right on it. 


== Travel Guide

Here's an extract from the config guide available at: 
- http://ozimodo.rubyforge.org/configure.html

  * How does it work?
  * Tumble Dot YAML
  * How to change the look and feel
  * Adding custom post types
  * Using the content variable as a hash
  * Helper functions
  * Caching
  * Switching themes


=== 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.  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.
Google works.


=== 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 a theme system. 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/tumble/styles/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 (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 
_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.


=== 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.  They are important if you 
wish to use ozimodo's caching facilities.


=== Cache It Up

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

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

Note that as of 1.2, caching is *off* by default.  To turn it back on, open up
ozimodo/config/environments/production.rb and change perform_caching from
false to 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.  

# 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 component your tumblelog
should be using.  Other than that little caveat, it's all rather elementary, my 
dear.


== Thanks

Thanks for using ozimodo.