life.events.each { |event| learn_from(event) }

Back last July, I wrote a Ruby on Rails tutorial as I was learning Rails. On the one hand, I’m rather proud of the tutorial. It’s pretty plainspoken and straightforward. On the other hand, in the year since I wrote that tutorial, I have learned vast amounts about Ruby and Rails. I still wouldn’t come anywhere near calling myself an expert, of course. That would be foolish. But I have a firmer grasp of what’s possible, and of best practices, and of many other things that could make that tutorial Better™. So I decided it was about time I did that.

What I’m about to do is nab the Rails tutorial and redo it. I was intending on the original tutorial having several parts, each covering some more ground on a single application. I ended up only writing two, but mostly because of time constraints. This time, I hope to update those two and then write several more, so as to complete my original vision. This is part I, which covers about the same ground as half of the original first part, but from a Rails 1.2, REST, BDD, etc, point of view. I think what I really liked about my original tutorial was the fact that it started at the most basic level (installing Rails) and started going into neat things like before_filter and such with real examples (like authentication). I intend on bringing in some plugins and things like that later on, in part to show refactoring and in part to introduce a lot of the neat plugins that already exist out there and can make a Rails developer’s life easier.

Anyway, without further ado, following is A Ruby on Rails Tutorial: Blogification, Part I: Introduction and Setup.

Introduction

This is a Ruby on Rails tutorial! If you’re not sure what in the world Ruby on Rails is, it’s a web application framework built using the Ruby language. For more information on these, see the Ruby website and the Ruby on Rails website.

The key point of Ruby on Rails is convention over configuration. What does this mean? Rails uses sensible defaults, and, if you follow those defaults, the amount of configuration you have to do is almost nonexistent. This is, in part, an attempt to escape the XML forests that spring up for any given J2EE project, for example. And it is also an attempt to reduce the amount of work the programmer has to do—something which Ruby as a language also strives for.

The second key point of Rails is following the DRY principle. DRY stands for “Don’t Repeat Yourself”, which means that we favor code that lets us state something once and only once. The idea behind this is that, if there’s only one place where that code is, bugs only need to be tracked down to, and fixed in, that one place. What does this mean for Rails? It means you don’t have to explicitly include files that fit together naturally. It means you don’t have to redeclare the columns that are in your database table when they’re already defined once in your database.

For purely informational reading, the Wikipedia entries on Ruby on Rails and Ruby are interesting.

What Are We Doing?

So what am I going to show you how to do? The idea came up to make the world a better place by doing yet another blog tutorial. But most blog tutorials do two mini-aspects of a microblog and then leave it at that. This tutorial aims to go quite a ways into writing a blog. This part will walk you through the basics of RoR while designing a database structure capable of dealing with the blog. Subsequent parts of the tutorial will explore other features like tagging, logins, and maybe even CAPTCHA. At least, that’s the plan. Let’s not get ahead of ourselves, now; we’ll focus, for the moment, on the basics.

Do note that this and future tutorials won’t exactly be short, but they will cover the basics of coding in Rails. The idea is that you should probably be able to refer back to parts of this tutorial when you forget how to do simple little things. In fact, I’ll probably be referring back to it myself :-)

On Audience

So who should read this? Well, I’m assuming, if you’re reading this, that you at least have some idea of Ruby. Much of how Ruby itself works can probably be inferred from the examples of code you’ll see here; still, it’s always a good idea to have a decent grasp of a language before you start using frameworks built on top of that language. Then again, I’m the kind of guy who learns by example, which means I actually learned Rails as I was learning Ruby.

Anyway, if you’ve never heard of Ruby, but already know how to program in an OO language like Java or C++, I’ve written `A Superfast Guide to Ruby’, which should get you started more or less quickly with the language.

That said, on to installation!

Installing Rails

Rails is a fairly painless install, thanks in large part to RubyGems, the Ruby package manager.

If you’re running Windows, see my Ruby tutorial for instructions on how to install Ruby and RubyGems. Linux users, you can use your respective package manager to install these two. Mac users, see the tutorial above for a link to a tutorial to install a `fixed’ Ruby (the one that comes with Tiger isn’t the best distribution in the world). If it’s been released and you’re running Panther, you should be set, since it comes with Rails!

Once you’ve got RubyGems, all you hvae to do is run gem install rails and everything will automagically get installed for you. Cool, huh?

Finally, you’ll need a database. I’d recommend MySQL, just because it’s widely used and its database adapter is therefore typically the most mature. There are, however, other options such as PostgreSQL which are also quite good (which is better tends to be a matter of perennial flamewars, so we’ll dodge the issue entirely and say `use whichever suits you best’). You’ll also probably need some sort of frontend for whichever one you use; I’ll leave it up to you to find one that suites you (I tend to run an Apache+mod_php server and MySQL, so I use phpMyAdmin.

Getting Started

Getting started in RoR is frighteningly quick. First of all, create a directory that you want to use for your project. We’ll call ours `blogification’ because… Well… Just because :-P You’ll want to do some of this, at least, on the command line, and it’s always a good idea to have a command prompt open while doing things in Rails, since some of the utilities run on the command line and can make your life a lot easier. So, let’s make a directory:

> mkdir blogification
> cd blogification

Now, we want to initialize the RoR system for our application. You might think `oh no, what do I have to do?’ It turns out, it’s a pretty easy one:

> rails ./

That’s it! Rails will create a full directory structure and copy a bunch of helper scripts into the directory, including a light, all-Ruby web server you can use for testing called WEBrick¹.

On Model/View/Controller

A particularly well-known architectural style in the software world is the Model-View-Controller style. The idea behind this style is that there is a model that takes care of data and how data is manipulated, fetched, and handled, and then there’s a view, which does nothing but display the data. The controller bridges the gap between the two by, for example, formatting the data from the model for the view, or giving the view whatever part of the model it’s going to show. This separation of logic and presentation proves so useful that almost every technology tries to achieve it. Even when we program in XHTML+CSS+JS, it is best to separate the structure (XHTML) from the presentation (CSS) and from the extra logic (JS). This separation is not 100% the same, but it’s a close cousin of MVC.

Ruby on Rails codifies this MVC pattern by creating everything around the paradigm. You create views -- typically rhtml files -- that display information; you have models -- ActiveRecord objects that contain the database information -- for handling all database objects; finally, you have controllers, which take data from the models and pass it on to the view, or take the input from the view and save it to the model.

Configuration the Database

So the first step is typically to configure Rails to understand our database. We need to open the file blogification/config/database.yml. You’ll notice in this file there are three sections, indicated by levels of indentation: development, test, and production. We’re interested in the first one, `development’, for now, but it’s worth explaining the two. The `test’ database is used when running unit tests (which are integrated in Rails quite well; we’ll be using Rspec to do these), while the `production’ database is used when deploying in production mode (where changes to the running application are not permitted without special voodoo²).

Anyway, what we want to do for the development section is to fill in our database name (typically blogification_development), our username and password (for the database), and our host (usually localhost).

Running WEBrick³

WEBrick is the all-Ruby, lightweight web server you can use to test your RoR applicaiton. You run it from the command line. Go to your `blogification’ directory and run⁴:

> ruby script/server

That will start WEBrick, usually listening on port 3000 (the output from running the server should tell you what port it’s listening on). If you point your browser to http://localhost:3000, you should find the RoR welcome page.

Rails, much like PHP, and much unlike Java, will automatically run any changes you make to your application while it’s running in development mode. Thus, if you want to check if an item is nil, you can simply add something to output that and reload the page without having to wait for a redeploy or restarting the server⁵.

So Close…

But that’s where we’ll stop for now. Now that Ralis is set up, we’re ready to launch into the Rails application proper; however, this post is already super-long, so we’ll leave the next bit for Part II. At this point, though, you might want to read the README file sitting in your Rails directory. This can be opened with a regular text editor, for you folks using Windows. It talks a little about the structure and other such things in Rails. In Part II, we’ll get started with some BDD (Behavior-Driven Development), Rspec, and some shiny models to drive our blog.

¹ WEBrick, it bears mentioning, is exorbitantly slow. Rails (in versions 1.2 and above) will also hunt for the mongrel server and use it if it finds it, since mongrel is a bajillion times faster. Really. A bajillion. I swear.

² `Special voodoo’ in this case just means restarting the server, but the point is that it takes more work, and intentionally so.

³ This should work for mongrel, too (and preferentially, i.e. mongrel will be run instead of WEBrick if available), starting with Rails 1.2.

⁴ In all of these code snippets, if you’re running on a UNIX box (e.g., Linux or Mac OS X), you should be able to omit the ruby part of commands. This is because on those platforms, the files are already marked as executable and typically have the appropriate shebang

⁵ Not every file in Rails works this way. In particular, when we get to FormBuilders, you’ll find that these aren’t always reloaded automatically. In those cases, you’ll have to do a manual restart of the testing server.