Table of Contents

Building a Basic Ruby on Rails Application

Introduction

[ To Be Written ]

Creating a Rails Project

All rails applications reside in their own directory tree. This tree is automatically generated by the 'rails' command ( 'man rails' for more information ). To create our project's directory structure, execute the following: 

(alterego@sverige)# rails ~/html/bookmarks --database=sqlite3
(alterego@sverige)# ln -s bookmarks ~/html/rails
(alterego@sverige)# cd ~/html/rails

The first command creates our project's directory tree under the '~/html/bookmarks' directory. Then we create a symlink from this directory, to '~/html/rails' so that the SDF utility scripts will be able to find, and work with this project. ( More info )

The '–database=sqlite3' argument to the 'rails' executable, informs Rails to configure the new project to use an SQLite3 database backend. If you have 'dba' membership then you can use MySQL as your backend by substituting 'sqlite3' with 'mysql'. This tutorial will however focus in using SQLite3 as it is available to all MetaARPA members. If you are going to use MySQL as your database backend, then you'll have to read this in order to configure your backend properly.

The final command changes your working directory to your new projects' root. The rest of the commands in this tutorial rely on you being at this location in order to execute correctly.

Building The Data Model

Now we are sitting in our nice new Rails project's root directory, we can start building our application. The most important thing in any database driven application like this one, is the data model. It specifies what data our application interacts with, and how we interact with it.

In this application, we only have one data type, that is a 'Link', this link must have a name, some descriptive information and the target URI. Normally at this stage you'd have to roll-up your sleaves and write one of those fugly SQL statements to create your table. Not us, Rails has cunningly abstracted database interaction for us, so no more SQL! In order to create our mode we must run this command: 

(alterego@sverige)# ruby script/generate model link

This command line executes the Ruby script, 'script/generate'. The 'generate' script is extremely useful, it automates the process of creating files to add specific functionality to our applications. You can tell what operations a 'generate' command has performed by reading it's output. This command created the two files required to create our 'Link' model.

Next we need to edit the 'db/migrate/001_create_links.rb' file. Files located under the 'db/migrate' directory are used to perform revision changes on your project's database. This file will allow us to specify our databases table without the need for any SQL, and, if required, roll our database back to before this migration occured.

Edit 'db/migrate/001_create_links.rb'

  class CreateLinks < ActiveRecord::Migration
    def self.up
      create_table :links do |t|
        t.column :name, :string
        t.column :info, :string
        t.column :url,  :string
      end
    end
 
    def self.down
      drop_table :links
    end
  end

Now we've specified our 'links' table's structure. We have to commit the revision in order to create the table. To do this execute the following: 

(alterego@sverige)# rake db:migrate

Going into the details of this command is way outside the scope of this document, I wouldn't have used it in this tutorial if it wasn't for it being such an easy way to generate a database across different backends.

A Quick Demonstration!

Before we move on to defining the application controller, I thought I would try and impress you with Rails magic. The next two commands will allow you to list, view, edit and delete items from your database through your web browser: 

(alterego@sverige)# ruby script/generate scaffold link
(alterego@sverige)# ruby script/server -p `id -u`

Right, those two commands did quite a bit. The first one generated a basic set of HTML templates and application logic. The second command started a web server, written in Ruby, running on a port that was specified from your userid. You'll notice on the second line of output from the 'server ' script, the address that it has bound itself too, along with the port number ( your user id ) it is running on in standard URI format.

So, open up a web browser, and point it to 'http://sverige.freeshell.org:[ YOUR USER ID ]' substituting your user id. Your browser should open 'Ruby on Rails: Welcome aboard' page. This just indicates that the Rails environment and server are running. Now, go back to your browsers' address bar, and append '/links' after your user id. Your browser should now show a rather rubbish looking list view, with no elements.

At this point it will probably be a good idea to play around and add some items as we'll need them for the next sections. Besides, I need to make myself a drink …

To Be Continued ...

Appendix A: SDF Utility Scripts

There are two utility scripts written specifically for Rails applications on SDF. The first 'ror' toggles whether the Rails project under '~/html/rails' has it's server started when the syste boots. The second script 'railsctl', is start/stop daemon, which starts or stops the Rails project located in the standard SDF project location.

As you may want to play with multiple Rails projects, it doesn't really matter where you put them, or what you call them. But if you plan on using the SDF utility scripts, which is a good idea if you want to host your project, then it's probably a good idea to symlink your current project directory to '~/html/rails'

Appendix B: Configuring A Database

[ To Be Written ]