== 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] %>
<%= 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_. === 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.