If you remember last week we added another table in our db schema file which was the Users table, today we will talk about users in our application and how to make our application a more social one.

The options we have in order to have a user management setup for our applications are mainly three:

• Do it ourselves from zero.
• Use some decent plugin like Acts As Authenticated.
• Use a ready generator like Salted Hash Login Generator.

Before we choose between these three let’s see what are the main differences between them:

If we write our code from zero we will definitely learn more, we will have a better understanding of the whole process but at the same time we will be spending too much time on something became very regular and common in every web application and in some way we will be doing some not required extra work.

Acts As Authenticated and Salted Hash Login Generator are almost the same from some functionality point of view but the main difference is that the act is more dynamic and customizable because it is simpler, it let us take care about few things that we should really be responsible of while the generator take care about everything in some more advance way, so personally I prefer to go for Acts As Authenticated for its simplicity and core functionality that will help us understand how things work and allowing us to add some extra functionalities by ourselves.

Acts in rails are some sort of plugins and extensions to our framework extending it with few extra features, there are many great acts we will use in this application, some of them are completely independent from rails and some like Acts As Taggable became so common to the level they got packaged with rails itself.

Acts As Authenticated

It’s a simple system that helps us deal with users in our applications, it generate the required code to support user authentication and management starting from the regular MVC code ending with migration and tests.

Installation

To start with we have first to install the plugin on our system, to do this we have first to update our repositories index and then install the plugin.

D:\\Projects\\Book Swap\\bookswap>ruby script/plugin source http://svn.techno-weenie.net/projects/plugins
Added 1 repositories.

D:\\Projects\\Book Swap\\bookswap>ruby script/plugin install acts_as_authenticated
+ ./acts_as_authenticated/CHANGELOG
+ ./acts_as_authenticated/README
.
.
.
Consult the Acts As Authenticated wiki for more: http://technoweenie.stikipad.com/plugins/show/Acts+as+Authenticated

The Generator

After installing the plugin now we are able to generate all the required files, acts_as_authenticated have mainly two generators, one for the authentication system itself, the core functionalities and their corresponding model, views and controller. And the other generator is the mailer, the one responsible for sending notification and verification emails to our registered users.

To use:

  ./script/generate authenticated user account

This generates a basic user model, a controller, some basic views, and tests.

So to generate the authentication system we have first to decide the controller name to be generated and remember here that the controller is the one that normally appear in our URL (to deal with the books controller we had to call http://localhost:3000/books) so what will be the best controller name for our users? Account? Readers? Owners? Well personally I prefer to stick with the defaults and the classics, at the end these are our applications Users, and this is what we called the database table earlier so let’s stick to it and name it “users”:

D:\\Projects\\Book Swap\\bookswap >ruby script/generate authenticated user users
      exists  app/models/
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/users
      exists  test/functional/
      exists  test/unit/
      create  app/models/user.rb
      create  app/controllers/users_controller.rb
      create  lib/authenticated_system.rb
      create  lib/authenticated_test_helper.rb
      create  test/functional/users_controller_test.rb
      create  app/helpers/users_helper.rb
      create  test/unit/user_test.rb
      create  test/fixtures/users.yml
      create  app/views/users/index.rhtml
      create  app/views/users/login.rhtml
      create  app/views/users/signup.rhtml
      create  db/migrate
      create  db/migrate/001_create_users.rb

If we examine the generated files we can see that acts_as_authenticated has generated for us the user model, users controller and its corresponding views, a helper, some unit and fixture tests and finally a migration file, as we have all these files generated it seems that BookSwap is ready now to have users, let’s see if this is true http://localhost:3000/users

It seems that it works, it already directed us to the signup method http://localhost:3000/users/signup, ok let’s give it a try and see what will happen (click to enlarge):

Oops, we have a problem, but at least we have some information that we can work with to understand what we have done wrong.

Fixing The Conflict

With the user friendly error page we should be able to catch what we’ve done wrong, it’s saying: “undefined local variable or method `crypted_password’ for #<User:0×39499b8>”, so basically the problem is in “crypted_password” and it is in the model User, we remember that the Model is the one that deals with the database, if you remember from our first part in the db schema definition we named the password column “salted_password”:

Error: Could not open schema.rb

So from where did this “crypted_password” come from?

Back to Migrations

Maybe it’s time to go back and check what’s inside the migration file that acts_as_authenticated generated for us and and check if it has anything realted:

Error: Could not open 001_create_users.rb

First let’s understand the migration process more, the migration is made to allow us move up and down in our application with a decent control over our database modification, in this case we can understand that acts_as_authenticated did create the migration file for us so we migrate to it.

Any migration file is separated into two parts, up and down. From the names “up” is the actions which will take place when we move forward in our migration like migrating from 4 to 5 for example, and “down” will hold the actions that will be executed when we move backward in our migrations like migrating from 6 to 5 for example.

The 001_create_users.rb migration file creates a table in its up method and drop it in its down method, the table it creates is the Users table which we already created earlier in our schema, it almost have all the columns, few more and some with different names, here we can find the mysterious “crypted_password” we saw in the error page, it’s the column we named as “salted_password”, so we found what’s wrong, now how to fix this conflict?

We have to write our own migration instead of using the default migration generated by acts_as_authenticated, we will tweak it to suit our needs. First we don’t need to create the Users table as it is already created, we don’t need to recreate the fields we have already created as well but we need the new fields required by acts_as_authenticated and sure we have to fix and rename the field salted_password into crypted_password. This will make “up” method like this:

Error: Could not open 001_create_users_up.rb

Instead of the create_table method we used some individual methods that deals with an existing table, add_column, remove_column and rename_column are simple methods that takes the table name as their first parameter and the column name as their second, only the rename_column method takes an extra parameter which is the new column name.

As this is the first migration file we have it got the 001 numbers at the beginning of its name automatically, from now on any new migration will get a serial prefix to its name that indicate its place among other migrations.

Whenever we do any changes or modifications to our database we have to support going back by defining the opposite actions in the “down” method of our migration as follows:

Error: Could not open 001_create_users_down.rb

So at the end our modified 001_create_users.rb file will end up like this:

Error: Could not open 001_create_users_new.rb

Logically we have solved the conflict error but there is still one step left which is migrating our application to the latest migration available and for now it is 001, to migrate our application we have to call the command “rake migrate”, if we called it without any parameter it will automatically migrate our database to the latest migration available, if we specified the “VERSION=X“ parameter it will migrate the application to migration X whether it is newer or older from our current migration level.

D:\\Projects\\Book Swap\\bookswap>rake migrate
(in G:/Projects/Book Swap/bookswap)
== CreateUsers: migrating =====================================================
-- rename_column(:users, :salted_password, :crypted_password)
   -> 0.3590s
-- add_column(:users, :salt, :string, {:limit=>40})
   -> 0.3280s
-- add_column(:users, :created_at, :datetime)
   -> 0.3600s
-- add_column(:users, :updated_at, :datetime)
   -> 0.3430s
-- add_column(:users, :remember_token, :string)
   -> 0.3440s
-- add_column(:users, :remember_token_expires_at, :datetime)
   -> 0.3600s
== CreateUsers: migrated (2.0940s) ============================================

Back to our application checking if the user system is working now, let’s try to sign up again and see what we will get (http://localhost:3000/users/signup):

“Train delayed? and what’s to say?” nice poetry after such a cool process, so we are signed up and logged in now, this is what acts_as_authenticated can give us so far and the rest is on us.

Have you noticed that the column fullname didn’t show up in the signup page? That’s because the templates generated by acts_as_authenticated plugin don’t know about it YET.

Tailoring

To be able to tailor and customize the authenticated system we have to understand the generated files and know how to deal with them and we will start with the views:

The generated templates are three, login, signup and index, they are all placed under the “users” subdirectory in our app/views directory, what we want is to allow users to add their fullnames when they signup so let’s have a quick look at the signup.rhtml template:

Error: Could not open signup_old.rhtml

It looks that we have a pattern for every property of the user object to generate its corresponding form input, if we followed the same pattern to generate the required input for the user fullname our template will look like this:

Error: Could not open signup.rhtml

This template like any other rhtml view template contains two types of code, the basic xhtml/html code and an embedded ruby code which we call ERb. To embed a ruby code in our views we have to surround it with <% and %> this will execute the ruby code but it will not show any output so it’s called “evaluation ERb block”, if we want to show the output of this code we have to add an equal sign after the introductory signs so it will be surrounded by <%= and %> and this is called “output ERb block”.

In any of the ERb block types we will deal mainly with two things, first is the ActionController methods and actions, these will help us generate the required xhtml/html, js and xml code in a dynamic smooth way.

The second thing we will deal with in our views is the instance variable received from the related action in the related controller, each view will be parsed after its corresponding action in its related controller is requested, in that particular action we set some instance variables that we can manipulate in our views, we will see that in more details soon.

How is it working?

In order to understand the code and the way it is generated in signup.rhtml let’s have a look at the parsed version of it, the html source code of the page we get in our browser when we call http://localhost:3000/users/signup:

Error: Could not open signup.html

Back to our rhtml template we notice that it starts with an output ERb block with the method error_messages_for which will output all the error messages of the user object in this form if there is any, as we don’t have any errors here we didn’t find any related html code in the parsed version.

Then comes an evaluation ERb block that opens a block by its turn, the form_for method do the required preparation to output a form fully customized to hold the information of a specific object and by ready I mean setting this form inputs names and ids to form a set of the object’s data in the post parameters. So what we do is to specify the object name we are preparing this form for, which in our case “user”, we can also specify the action this form will be directed to when it’s submitted, if we don’t specify any (like in our case) it will be submitted to itself so our form will be submitted back to the signup action of the users controller.

The form_for method prepared a form helper object for the “user” object and name it “f”, then the generating of the required inputs for each column started by simply calling their corresponding helper methods, notice that only two methods are used so far: text_field and password_field and they are called as methods of the form helper object called “f”, notice as well that these methods are called in an output ERb block so they can return their output in the parsed template.

Let me try to simplify this code by trying to write it in plain English: “Start a form for a new user then generate the required text fields and password fields for this user and then post them back to the same current page.”

The main idea of setting the names and ids of the generated inputs is to simplify the way we deal with them in our actions as post parameters, rails has a standard for this and therefore it has the ready tools to generate what’s required to follow these standards and get things faster.

After we are done with our form fields we find a submit_tag named “Sign up” then the form_for block is simply closed by an “end” and we are done. When someone signup and fill all these fields and hit the sign up button the form data will be posted to the same action “signup” where it will be handled to add a new user to the Users table accordingly, if it faced any errors it will return to the same form and show the errors at the top (as the results of the error_messages_for method), if not it will simply login to our poetry page.

Are We Logged In?

Now let’s change this literal poetry in the index.rhtml template to some code poetry, how about we change the output of this view depending on the status of the user, if he/she is logged in we show a link to logout, if not we show links to either signup or to login. I don’t think this is difficult it’s just a quick if statement:

Error: Could not open index_new.rhtml

I guess the code is self-explanatory now, I just want to note that we used the method logged_in?, in ruby whenever there is a method with a question mark “?” at the end of it will return a Boolean, True or False, so in English it’s like a simple question, is the current user logged in? this method is a part of the acts_as_authenticated plugin.

The other thing I wanted to talk about here is the link_to method, it is an ActionView helper method, it generates an anchor, takes the first parameter as the anchor name and the second as the action name we want to link to, it will automatically understand and generate the corresponding URL of the action we specify, for example when we specify the “logout” action it will know automatically that its URL is http://localhost:3000/users/logout.

So we have changed our index.rhtml file, now let’s see if it’s working and how it will look like, remember that our last state where logged in after we signed up and saw the lovely poetry:

We are logged in, that’s true, it seems that everything is really working fine and we don’t have any problems so far, how about the link to “logout”? is it working? let’s check out:

Yes it is working, we are logged out now and we have one of two options, either to login again or to signup for a new account, try logging in and out again to see how it’s working and then let’s try a new signup to see if the fullname field we have added is present or not:

Wonderful, we have a simple user authentication system now that we modified a little, so far it works for signup, login and logout, it doesn’t do anything more yet but at least it helped us understand few concepts and how things work at the backend.

More Security by Filtering

To care more about security and to get the most benefit out of the latest rails 1.1.6 security release let’s use the new method of ActionController (released in rails 1.1.6) “filter_parameter_logging”:

“ActionController#filter_parameter_logging lets you filter form data that you don’t want saved in the log. This is useful for preventing sensitive data like passwords and credit card numbers from being logged in the clear, for keeping huge pieces of data from clogging the log file, and so on.” from Filtered Parameter Logging of the Ruby on Rails official Blog.

This method job –as clarified in rails weblog- is to filter fields from being logged, in our case what we want to filter is the password fields and we will do that by adding the filter_parameter_logging line to our application controller in controllers/application.rb:

Error: Could not open application_filtered.rb

By doing this the password and password_confirmation fields will never be logged anymore and will be replaced by “[FILTERED]” in the log files, to check that yourself you can check your log/development.log file and see how the passwords of the users added to the system earlier were plainly logged while the passwords of any new users will be replaced with “[FILTERED]“.

Summary

In this part we have implemented the Acts As Authenticated plugin into our application, modified it a little and understood few backend behaviors specifically the way the view templates handle ERb code, we also had a better look at Migrations and understood how they help us have a better control over our database modifications in a very dynamic way.

During the next week I will release a sidenote post on how to checkout the project files from the subversion repository I’m using for it, I’m also working on creating packaged files for each part of the tutorial and will release it on RubyForge soon too.

In the next part we will talk about relationships, as for now we have a user system and a simple books system, we will link them together using some magic relationship mapping from ActiveRecord maybe we will do some testing as well to ensure things are working properly, so… see you next week.

It seems that I underestimated the amount of work this tutorial is going to take that’s why I’m a day late, because of that I will change the weekday each part of this series will come up from Saturday to Sunday and sorry about this delay.

If you remember our project is BookSwap, a small system based on users, it will give them the chance to exchange and swap books between each others from their online bookshelves that they create. so let’s get started:

Normally I prefer to get something up and running as soon as I can, at least to enjoy seeing results from the very beginning of my project work and this is what we are going to do with this project as well, so to start let’s decide what is the simplest database design we can start with?

Database Schema

Basically from the light definition of our project we can tell that this project includes two main things: users and books, and from here we will go, we need two tables, one to hold the users data and we will call it Users and another one for books data and we will call it Books and now let’s discuss the relationship between these two tables

Obviously every user will have many books, and many users can own the same book (I mean the same title not the same physical book), so the relationship we have here is the many-to-many relationship which requires a third table in our database called users_books, therefore our database should look like this (db model is generated using DBDesigner4):

As you can tell from the database model above, I have mentioned the common and very basic columns of each table; fullname, login, email and salted_password for the Users table and title, author, publisher and ISBN for the Books table and naturally both of them have the default ID column as well.

We will use MySQL as the database server for this application, it’s time to create the three databases we will work with on our way:

bookswap_production: This will be the database we will use when we finish our development work and ready to have a live and completely working web application, that’s why it’s called the production database, it should contain the most stable version of our database structure with the most stable version of our code that’s why we separated it from the development database.

bookswap_developmentt: As you can tell, this is the database that we will play with during our development process, whenever we need to change anything or touch anything related to the database this is the one we should be dealing with in order to keep our production database in peace.

bookswap_test: In a sooner part of this tutorial we will cover the testing of our application, we will write code that will test our code and this testing code will deal with a completely separate database from both development and production databases, it will deal with the test database as it will require a lot of data insertions and deletion while testing which we want to keep away from other live and development databases.

If you have a GUI for your MySQL server you can create the above databases from there or we can simply use the command line admin tool:

D:\\Projects>mysqladmin -–user root -–password create bookswap_production
Enter password: ********

D:\\Projects>mysqladmin -–user root –-password create bookswap_development
Enter password: ********

D:\\Projects>mysqladmin -–user root -–password create bookswap_test
Enter password: ********

We will only create the databases now, we will not create any tables or relationships yet and actually we will do all that in Ruby and Rails after we get to know the directory structure of our rails application.

Generating The Rails Application

Before we get started with generating the rails application let’s just clarify few things, we are using Rails 1.1.6 for this application which got announced only few days ago (from the date of this post), so if you have Rails installed earlier before the update please upgrade before we proceed.

To generate our rails application we have to run the rails command, personally I have created a directory called “Book Swap” where I will store everything related to this project, including the rails app itself. So all I have to do now is to run the “rails” command in my directory with the project name to get my files generated.

D:\\Project\\Book Swap>rails bookswap
      exists
      create  app/controllers
      create  app/helpers
      create  app/models
      .
      .
      .
      create  doc/README_FOR_APP
      create  log/server.log
      create  log/production.log
      create  log/development.log
      create  log/test.log

I guess you agree with me that these are a lot of files and directories that Rails has generated for us, maybe we should give them a quick scan and try to understand what they are for and what we will be dealing with more frequently:

File Structure

app

This directory is the one that will contain most of our working files, it already contains four subdirectories (controllers, helpers, models and views), that is made to support the MVC nature of Rails, in brief the MVC methodology is based on separating our code into three levels:

First we have the Model which carries the core functions and responsible for all the data handling and manipulation, then comes the Controller which normally interacts with the model to retrieve data and prepare it to be viewed by the View which by its turn is the responsible of doing all the “show” business.

As for Helpers, they are the view supporters, when we reach the level that we have too much code in the view we better go and make a helper function and use it instead, once we start writing code we will get a better understanding of all these concepts which will happen very soon.

Behind The Scenes

All of these models, controllers and views are just the children of a bigger and more general parts of Rails, actually Rails is a union of different parts for each task which makes it more understandable and customizable to fit our best needs.

ActiveRecord is the part of Rails that’s responsible of interacting with the database and lets us deal with it as a complete object oriented solution, which really sounds like the model behavior (core functions and data manipulation) which is true, normally the model classes in our models directory are subclasses of ActiveRecord where they inherit the magic powers of it and get such strong tools to deal with the database.

“Active Record objects don’t specify their attributes directly, but rather infer them from the table definition with which they’re linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.” From Rails API

Following the same path Rails also depends on ActionController for its controllers, which is the midpoint between the views and the models, it receives the web requests from one side, activate the corresponding action which will contact the model for few data objects and then render the views to show the results.

“Action Controllers are the core of a web request in Rails. They are made up of one or more actions that are executed on request and then either render a template or redirect to another action. An action is defined as a public method on the controller, which will automatically be made accessible to the web-server through Rails Routes.” From Rails API

And finally we’ve got the views which are ActionView templates, we will see how they are just normal html, js or xml pages but with embedded Ruby code inside which also known as ERb, this embedded code helps us represent the data with some behavior and have a better separation between our design and our backend code.

“Action View templates can be written in three ways. If the template file has a +.rhtml+ extension then it uses a mixture of ERb (included in Ruby) and HTML. If the template file has a +.rxml+ extension then Jim Weirich’s Builder::XmlMarkup library is used. If the template file has a +.rjs+ extension then it will use ActionView::Helpers::PrototypeHelper::JavaScriptGenerator.” From Rails API

config

From its name, config directory is where the configurations files are stored, the database link file, routs and environments files. database.yml is the database link file, where we will setup our database connection settings, environment.rb is the file where we specify our application environment, remember when we talked about development, production and test databases; each one of those is related to one separate environment as well that we can run our application on.

Config directory include environments subdirectory too which include environments configurations files, for each environment a different file, to control all the environments we have the father file we’ve just talked about environment.rb.

Finally comes the routes.rb file which (as it’s named) take care of all the web requests routing in our application, starting from some very basics routes up to a very complicated ones, it is very helpful for making clean and meaningful URLs as well.

components

In this directory we can create and store components which are something like a small application with model, controller and view that we can use all over our website instead of repeating ourselves for some modules.

db

From its name, the db directory will store our database related files, earlier we used to store the SQL files that generate our database structure but now it will hold only ruby files. It will store the schema and migrations files that we will discuss after a while in this part.

When we first generate our rails application the db folder will be empty but as we move along it will contain the schema.rb file that stores our database schema definitions and a subdirectory named “migrations” to store the versioned migrations we will create.

lib

Sometimes but not always there are some code that we want to write and it doesn’t fit under any of the MVC hierarchy, such custom code will be stored in the lib directory.

public

An interesting fact about Rails that none of these directories we are talking about is viewable or accessable online except for “public“, it contains the cgi/fcgi dispatchers that will do all the underground work to deal with the routes and our application, it also contains the images, stylesheets and javascripts subdirectories that we will be calling in our views and layouts.

script

You will notice when go a little further that rails is full of generators and embedded scripts that help us along the road to generate and create many things and even run a tiny web server as well the script directory is where all these stuff are hidden.

test

The test directory is where all the automotive tests are stored, there are functional tests for our controllers with some fixtures to load and a couple of unit tests for our models as well.

vendor

As in any application, sometimes we don’t want to reinvent the wheel, we don’t want to do something that’s already done, rails as an open source framework have many wonderful plugins and resources available that we can use in our applications and we will do that as well in BookSwap, all these external libraries and plugins will be stored in the vendor directory.

doc, log, and tmp

These three directories we don’t interact with their files much as they are automatically generated and updated, the log directory will store the log files of our web server for each environment, tmp will store the session, cache and socket temporary generated files and finally doc will store the html documentation that we will generate for our application (we will cover this up in some later part).

Link The Database

After we had this quick overview over the file structure in Rails we have to configure our rails application to connect to the databases we have created earlier, the responsible configuration for this is config/database.yml which normally looks like (notice that the databases names are exactly like the one we’ve created as they follow the project name):

Error: Could not open original_database.yml

Now for the sake of DRY ‘ing our configuration file we will change it a little bit and add our database connection details as well to:

Error: Could not open dried_database.yml

Basically what we have done is taking all the repeated information from the three database configurations parts, collect them under one reference and call this reference back in the configurations parts, by doing this we are not only DRY ‘ing our database configuration file but we also allowed different database engines to be defined more easily.

So our Rails application is linked to its blank databases using the MySQL adapter and it’s time to implement the structure we’ve decided on earlier using the rails schema and migrations facilities.

Rails + Database = Schema + Migrations

Migration in rails is the way Rails allow us to move back and forth in our application easily without losing any data from our databases but also keeping track of all the database structure changes from version to version (something like version control for our code files).

Database schema in Rails is very first database schema our rails application will have so if we want to install it on a new machine or load our database structure in any different database server it will be ready as a schema file that gets accumulated by the migrations files to move between versions.

In this part we will deal only with the schema part and later on with our versions and modifications we will get to know migrations better and have a closer look at them, now let’s generate the schema file and see how it looks like:

D:\\Projects\\Book Swap\\bookswap>rake db_schema_dump

This command will create a new file in our db folder named schema.rb, this file will hold all the starting schema setup and definitions and as this is a fresh application it will be empty from any definitions yet:

Error: Could not open original_schema.rb

Now let’s implement the basic database schema we agreed on at the beginning of this part, three tables with few fields, after the modification our schema.rb will be like this:

Error: Could not open schema.rb

If you read the above code you can easily understand that we simply created three database tables and identified their columns accordingly but notice also that we didn’t define the id column of the users and books tables, this is because ActiveRecord will create it by default.

create_table is a simple method that generates SQL code of creating a table, we used its block form to add columns of our desired type, in the block form an instance of the table definition is created as “t” and when we call t.column it’s like if we say add_column in the regular form of the create_table method.

We have a schema file that contains our database structure, we have a rails application linked correctly to our database all we have to do now is to tell rails to import this schema to the linked database:

D:\\Projects\\Book Swap\\bookswap>rake db_schema_import
(in D:/Projects/Book Swap/bookswap)
-- create_table("users")
   -> 0.3440s
-- create_table("books")
   -> 0.1410s
-- create_table("users_books")
   -> 0.1720s

Running this command will import the database schema defined in schema.rb to our development database and that’s because the default environment of any new rails project is the development environment which can be changed and configured at anytime in config/environment.rb.

With this ruby-based database schema file we have saved ourselves from being attached to any database engine, Rails supports too many database engines like SQLite, Oracle, DB2, SQL Server and PostgreSQL, now our application can work with any of those by simply changing the connection adapter in config/database.yml file and import our schema to it using the above rake command.

This is one of the reasons why many designers or non-developers liked Ruby on Rails when they started to learn it as their first web development language and framework, Ruby has this beautiful self-explanatory code and Rails is full with Agile practices, it saved us from dealing with any SQL code and made our application cross-database-engines with Schema and Migrations.

All this read and all this steps and we didn’t see anything in action yet, maybe it’s time for us to try Scaffolding which is a quick auto-generator that we tell it about a table we want to scaffold and it will generate all the required Model, Controller and Views to connect with it and control it.

By running the following command we will be able to add, edit, delete and list all the data of our Books table:

D:\\Projects\\Book Swap\\bookswap>ruby script/generate scaffold Book Books
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/books
      exists  test/functional/
  dependency  model
      exists    app/models/
      exists    test/unit/
      exists    test/fixtures/
      create    app/models/book.rb
      create    test/unit/book_test.rb
      create    test/fixtures/books.yml
      create  app/views/books/_form.rhtml
      create  app/views/books/list.rhtml
      create  app/views/books/show.rhtml
      create  app/views/books/new.rhtml
      create  app/views/books/edit.rhtml
      create  app/controllers/books_controller.rb
      create  test/functional/books_controller_test.rb
      create  app/helpers/books_helper.rb
      create  app/views/layouts/books.rhtml
      create  public/stylesheets/scaffold.css

This command will ask Ruby to run the scaffold generator to create the MVC setup for our table Books, the first parameter after “scaffold” is the Model/Table name and notice here that the table name here is not plural as we have specified it in our schema.rb, it’s Book not Books and this is because Rails will take care of this with it’s pluralization magic.

The second parameter in the scaffold command is the Controller/View name, basically it will create controller of the same name and a directory in the views directory named books with few templates for each action in the created controller.

Few other files got created too in the process, a helper and few test files, for now we will not deal with any of them but we can at least understand that for each data table of our database we can have all these structured files, a model to interact with the database and present the table data as objects, a controller which interact with these objects, filter them and prepare them to be viewed by the views which are templates with light embedded ruby code.

With this very minimum work, few commands and modifying a couple of files, we didn’t even write any code yet but we have something up and running and it’s time to have a sneak view on how it will look like.

D:\\Projects\\Book Swap\\bookswap>ruby script/server
=> Booting WEBrick...
=> Rails application started on http://0.0.0.0:3000
=> Ctrl-C to shutdown server; call with --help for options
[2006-08-20 16:49:04] INFO  WEBrick 1.3.1
[2006-08-20 16:49:04] INFO  ruby 1.8.4 (2005-12-24) [i386-mswin32]
[2006-08-20 16:49:04] INFO  WEBrick::HTTPServer#start: pid=5652 port=3000

We don’t even need to install a webserver while developing a rails application, we can simply try it with WEBrick, the simple http server bundled with rails. It will run by default on port 3000 on the localhost server so let’s check it out http://localhost:3000.

Rails welcomes us, read this page as it has some useful information that we have discussed some and will discuss the rest (routes specifically) in depth later in other parts.

So where is the magic? We have generated a scaffold for the books table and we chose the controller/view name to be books, rails understand that and it will run everything automatically under the following mapping: servername:port/controller/action, in our case the servername is localhost running on port 3000, the controller we’ve created is named books but we don’t know any action yet but let’s try this: http://localhost:3000/books/

Great!! We have a page with the title “Listing Books”, an empty table with same headers of our columns names and finally a link that says “New book”. By clicking on this link we will see something more wonderful, a ready form, lovely and simple that allows us to add new books to our database.

Let’s try filling it out with some data and add the book, where will we go next? Back to the listing page but now it’s not empty like before, we have the new book we’ve just created listed there:

What else have we got there? Three links in same row with our recently created book, Show, Edit and Destroy.. Do we have to explain? Clicking on Show will take us to a separate page that shows only the data of this particular row, Edit will take us to a form page loaded with the information of this record, ready to be edited while Destroy will popup a warning message before it will delete this record. This is it, one line only and the scaffold generator created all this for us.

Follow the URLs of each action and see how they are very meaningful and clean, all this web requests are handled in config/routes.rb as we said above, with the default route (mapping) as /:controller/:action/:id so for example if we go to http://localhost:3000/ books/show/2 routes.rb will forward this request to the books controller to run the show action on the book with 2 as its id.

Naturally scaffolding is not made to be used on its own, it’s made just to provide us with the very basics functions in a very simple way so we can understand how things work but we have to do the rest and modify the code to what perfectly suit our needs and that is what we will discuss in the next parts.

At The End

In this part we have met Rails in a little depth, had a quick look at the file structure it generates and understood some of the migrations and schema magic as well, technically we have now a basic rails application for books where we can add, edit and delete any record at any time after we wrote a very minimum amount of code and left the rest on Rails to take care of.

In the next part we will talk about creating some more tables, discussing migrations a little further and getting a better look with a nice interface and see how to implement the design with our Rails application as well, sorry for the length of this part and see you next week…