Week 13: Ruby on Rails

This week we continue from our look at the Ruby language with an examination of the Ruby on Rails framework.

What is Ruby on Rails?

Ruby on Rails is a framework which allows easy development of web applications using the Ruby language. The key feature of Ruby on Rails is that a lot of the common web development tasks are "wrapped up" in the framework, so you can develop code which queries or modifies a database with very little effort.

The Model/View/Controller architecture

Ruby on Rails is based on a common software development architecture known as Model/View/Controller. Under Model/View/Controller, the application is broken down into three components:

The model: the code which represents the actual application data. In Ruby on Rails, the model typically "wraps" a database, allowing the application to query the database using Ruby code rather than SQL queries. An example of model code might be a Hit class which represents a song on HitTastic!
The view: how the data is presented to the user and gathered from the user. In a Ruby on Rails application, this is a web page with embedded sections of Ruby code within it, rather like a page consisting of a mixture of HTML and PHP in a PHP web application.
The controller: the interface between the model and the view, which queries the model for data and presents it to the user in the view, or, alternatively, reads in user data from the view and uses it to modify the model.

Model-View-Controller

More on controllers

In Rails, a controller represents a particular entity or "thing" such as a song, a user or a person. Controllers contain a set of methods or actions which do certain things to that "thing", and each action maps to a URL. Therefore, the controller is the entry point to the application from the web browser. For example, for a controller called hits, representing a hit (song) in the HitTastic! database:

We might have a controller method called update which reads information about a song from the user and uses it to update the details of that song. Such a controller method might have a URL such as:
```
http://hittastic.com/hits/update/1024
```
We would post form data (the view) to that URL and use it to update the song with the ID of 1024 in the database (the model).
A controller method called get_details might exist, with a URL such as:
```
http://hittastic.com/hits/get_details/1024
```
This controller method would retrieve all the details (from the model) of the song with the ID 1024 and present the details to the user as a web page (the view).

Controllers in Rails

Building some basic Rails applications

Rails is a bit different from most server side scripting techniques in that a lot of code is pre-generated for you. You can easily create a basic application to read and modify a database without writing a single line of code!

A simple Rails application

Here are some step by step instructions to generate a basic Rails application. The first example does not involve a database, but it will allow us to examine the structure of a Rails application.

Load up InstantRails (we'll demonstrate this in class) and start a new application. A DOS prompt will come up. Type the following:
```
rails hello 
```
This generates a Rails application called hello. You'll also see a new folder called hello appear.
Move to the hello folder:
```
cd hello
```
Next, you are going to generate a controller for the application. An application can have many controllers, each representing a different entity within the application. Remember that the controller is the entry point of the application for the user, and maps to a URL. Type this in:
```
ruby script/generate controller me
```
This generates a controller called me, which is designed to represent a person. Each controller typically represents an entity of some kind, such as a person or a song. In this way, Rails applications follow REST principles.
Now move to the controllers folder within the app folder:
```
cd app/controllers
```
You'll notice an auto-generated file called me_controller.rb. This file will store all the controller code relating to the me entity. Edit this file and modify it so it looks like this:
```
class MeController < ApplicationController
    def name
        @n = "Barack Obama"
    end

    def age
        @a = Time.now.year - 1961 - 1
    end
end
```
(replace Barack Obama and 1961 by your name and year of birth respectively. The -1 is because it's so early in the year and chances are you won't have had your birthday yet)
We have defined a controller called me with two methods: name and age. The name method initialises the variable @n to a name, and the age method initialises the variable @a to an age.
Note that we do not actually print these out. Remember that it's the view's role to print things out, not the controller's.
You've now created the controller, so next you need to create the corresponding views. There will be two views: one for the name and one for the age. Change folder to the views folder:
```
cd ../app/views/me
```
and create two files, name.rhtml and age.rhtml. The first is a view for the "name" method of the "me" controller, and the second is a view for the "age" method of the "me" controller.
```

<html>
<body>
My name is : <%= @n %>
</body>
</html>
```
```

<html>
<body>
My age is : <%= @a %>
</body>
</html>
```
Note the following:
- The code resembles mixing HTML and PHP. The <% tag begins the embedded Ruby, and the %> ends it.
- Notice also how in embedded Ruby we do not use puts to print out the variable, but simply use =.
- The @n and @a are the same variables as we initialised in the controller. So this code will display whatever data we initialised in the controller. (The view code is part of the MeController class, as well as the model, and @n and @a are attributes of the MeController class. The code which links the controller to the view is hidden away within the Rails framework).
Now you can test it out. Return to the top level folder for your project:
```
cd ../../..
```
Now start the server from the InstantRails GUI window:
Type the following addresses into your browser:
```
http://localhost:3000/me/name
http://localhost:3000/me/age
```
All being well, the first URL will bring up your name, and the second, your age.
Note how the URLs map to the controllers and views:
- The first URL will call the name method of the me controller while the second URL will call the age method of the me controller.
- Each controller reads data from the model (here, the model is simply your name and your age) and uses the matching view (me/name.rhtml or me/age.rhtml) to decide how to present the data
- The separation of functionality in the Model/View/Controller architecture allows the easy replacement of one view by another without having to change the model or the controller. So if we wanted to show the name and age in a PDF document rather than an HTML page, we would just need to change the view .rhtml files, not the controller (or the model if it existed)

A database driven Rails application - HitTastic! on Rails!

The example above was designed to get you used to the layout of the various files which make up a Rails application, in particular the controller and views. However a real Rails application is likely to talk to a database. The InstantRails environment we are using comes with a MySQL database.

Setting up a basic framework

We are going to use the HitTastic! music site as an example to develop a database-driven Rails application. Create a new Rails application:
```
rails hittastic
```
and move to the hittastic folder generated:
```
cd hittastic
```

Next, load up MySQL:

mysql -u root

and create a database:

mysql> create database hittastic_development;

Tell MySQL that we're using this database:

mysql> use hittastic_development;

and create the hits table in the database:

mysql> CREATE TABLE hits (id INT PRIMARY KEY AUTO_INCREMENT,title 
VARCHAR(255), artist VARCHAR(255), year VARCHAR(255), chart VARCHAR(255), 
quantity INT, price FLOAT)

Finally exit the database client:

mysql> quit

You can now generate a so called scaffold. A scaffold in Rails is pre-generated code which will automatically perform common actions with a pre-existing database. To do this:
```
ruby script/generate scaffold Hit
```
This will generate a scaffold called Hit, to represent hits. Note that the scaffold name is always the singular of the table name, with the initial letter capitalised, e.g. for a table hits it would be Hit; users becomes User.
Look in the controllers and views folders. You'll find a number of pre-written controller methods and corresponding views. Start up the server and try out some of these in the browser. (Remember from the first example how the controller methods map to URLs)

Explanation of the code

To help you understand what's going on with Rails code, we'll go through one of the controller methods, namely the show method of the hit controller.

Look at the generated controller, hits_controller.rb. You'll see there are several methods, for example there is the show method:
```
def show
    @hit=Hit.find(params[:id])
end
```
The show method of the hits controller will be called by a URL of the form:
```
http://localhost:3000/hits/show/1
```
much like the simple me controller above. Note however the additional "1" on the end. This is a parameter, representing the ID of the hit. Behind the scenes the "1" is converted to a query string parameter id with a value of 1. (One of the features of Rails is that it uses clean REST-style URLs).
So what happens next? The params[:id] will contain the hit ID passed into the controller. This ID is the passed to the Hit.find method, and the hit returned is placed in the variable @hit. So if a user entered:
```
http://localhost:3000/hits/show/1
```
the variable @hit will contain hit number 1.
Here we are interacting with the model. When we call Hit.find, we are calling the find method of the Hit class. The Hit class is the model, i.e. the part of the code which directly talks to the database. In other words, the Hit.find method talks directly to the database.
So where do we display that variable @hit? Like the basic me example above, we display it in the view. Look inside show.rhtml within the hits folder within the views folder. There is a lot of pre-generated code in the view, but the important thing for now is that the @hit object, first retrieved in the controller, is being used again. Once again this underlines the Model/View/Controller technique of development: interact with the model in the controller, and retrieve something, then display it in the view.

Writing our own controller method

If you play around with our pre-generated HitTastic! application, you'll find you can do quite a few things: you can add new hits, you can edit hits, you can delete hits and you can list all hits. However we might want to add one or two extra items of functionality. In the HitTastic! application we might wish to:

Allow the user to buy a hit.
Re-stock a hit (increase the quantity in stock);

We are going to add two new controller methods to allow our users to do this, one for buying a song, and another for re-stocking a song. These will have URLs of this form:

http://localhost:3000/hits/buy/1
http://localhost:3000/hits/restock/1

Note once again the descriptive, REST-style URLs.

Carry out the following steps:

Move to the hits folder within the views folder and edit the list.rhtml in WordPad. This is the view for the list controller method: the action which lists all the hits. Notive how there are a number of lines reading link_to. This is Ruby code which writes out a hyperlink. Note how they are of the form:
```
link_to 'Show', { :action=>'show', :id=>hit }
```
This code will call the link_to method, and pass it two parameters:
- The text on the link (Show)
- The action associated with the link. This is a hash with several fields. In this example, the hash contains an action field representing where to link to (here, the 'show' method of the 'hit' controller), and the query string parameters (here, an 'id' parameter with the value 1).
Below the existing link_to methods, add a new one which calls the buy controller method (not written yet) and passes it the ID of the current hit. The text on the link should read "Buy Hit"
Now start to write the buy controller method. Move back to the controllers folder and load up hits_controller.rb. Add a new buy method which looks like this:
```
def buy
    @hit=Hit.find(params[:id])
    @hit.buy
    redirect_to :action => 'list'
end
```
Note how this is working:
- We find the hit with the ID passed in (as before)
- We call the buy method of the Hit class. This is a new concept: we are interacting with the model. This is discussed further below.
- Finally we redirect to the 'list' action. In other words, once the hit is bought, we go straight back to the 'list' page to list all hits.
Finally, we have to write some new code in the model. We need to write a buy method in the Hit class which will reduce the quantity in stock of a given hit by one, by interacting with the database. Move folder to the models folder and edit the hit.rb file in that folder. It will look like this:
```
class Hit < ActiveRecord::Base

end
```
This means "the Hit class inherits from the ActiveRecord::Base class". ActiveRecord::Base is an inbuilt class which is part of Rails: it contains methods for interacting with a database. Note how the Hit class has no actual code in it yet. However, you can perform several actions (such as finding a hit by ID with the find method) on a Hit object because these methods are part of the inbuilt ActiveRecord::Base class.
We're now going to write a custom method inside the Hit class called buy. The buy method will buy a hit by reducing the quantity in stock by 1. Add this code:
```
def buy
    if self.quantity > 0
        self.quantity = self.quantity - 1
        save
    end
end
```
This code is saying "if the quantity of the current hit is greater than 0, reduce its quantity by 1 and save the change in the database". self is a reference to the current object: basically, it's rather like this in Java.
Try it out by typing in the URL for listing all hits:
```
http://localhost:3000/hits/list
```
and try buying a hit.

Error handling

OK, that works, but it would be nice to display an error message if the selected hit is out of stock. How do we do that? First return to the model and modify the buy method so that it looks like the following:

def buy
    if self.quantity > 0
        self.quantity = self.quantity - 1
        save
        return true
    else
        return false
    end
end

Note how the buy method of the Hit class is now returning true if the hit was bought successfully, or false if it is out of stock. We can take advantage of this in the controller, as we will do in a moment: we can react differently depending on the value that the buy method returns.

Return to the hits_controller.rb file. Modify the buy controller method as follows:

def buy
    @hit = Hit.find(params[:id])
    if @hit.buy==true
        flash[:notice] = 'Hit successfully bought'
    else
        flash[:notice] = 'Out of stock'
    end
    redirect_to :action => 'list'
end

What we are doing here is calling the find method of the Hit class in the model, and testing if it returns true or false. If it returns true, we set up a flash message (see below) indicating that the hit was successfully bought. This will be displayed in the view, see below (remember that all displaying must be done in the view, not in the controller or the model). If not, we bring up a similar message indicating that it's out of stock.

We've done the model and the controller for our buy action. We don't actually need a specific 'buy' view, because buying a hit is an action which doesn't require an associated web page: it simply buys the hit by reducing the quantity by 1. However we do wish to display a message to the user to indicate whether the hit is bought successfully or not, so we need a view of some kind. Recall from above that we redirect to the 'list' action when the buy operation is done. So, logically our flash message should be displayed in the 'list' view. It turns out however that the 'list' view will automatically display any flash messages set up in the controller that called it.... which means that we're done!

Another action: restocking a hit

We're now going to implement another action: restocking a hit. This is a bit more complex as it requires user input, because the user will have to enter the amount they want to increase the stock by. Because of this, we actually need two controller methods:
- restock: for reading in the amount from a form;
- do_restock: for actually updating the quantity in stock in the database.
This is illustrated below:

The first thing we'll do is create a view for the restock controller method. Go to the views folder and create this file, restock.rhtml:
```
<h1>Update quantity of existing hit</h1>

<% form_tag :action => 'do_restock', :id => @hit do %>

<p><label for="quantity">Amount to increase stock by:</label><br/>
<input name="quantity" id="quantity" />
<input type="submit" value="Go!" />
<% end %>


<%= link_to 'Show', :action => 'show', :id => @hit %> |
<%= link_to 'Back', :action => 'list' %>
```
Much of this is just HTML, but note the form_tag command, this is a Ruby call which automatically sets up a form with an action of 'do_restock' (we'll come onto this in a moment) and passes the ID through the form.
We've written the view, so now we need to write a controller for restock, so that the server can respond appropriately to a URL such as:
```
http://localhost:3000/hits/restock/1
```
All we need to do for the controller is to find the hit, so that it can be passed on to the view, so that the view knows which song we are re-stocking. So just add this code:
```
def restock
    @hit = Hit.find(params[:id])
end
```

The do_restock action

We've created a restock action which is associated with a view allowing the user to enter an amount to increase the stock by. However now we need a do_restock action which actually restocks the hit, i.e. increases its quantity in the database. If you go back to the view for the restock action, note how the form posts to do_restock already, so all we need to do is write the code for the do_restock action.

First (as always), write the controller method. In this case, the controller method responds directly to the form, so we need to read in the ID and the quantity from the form and update the database using this information. Note in the form how we used the Ruby code:
```
<% form_tag :action => 'do_restock', :id => @hit do %>
```
In other words, the form keeps a record of the ID, which is posted along with the quantity. So our controller code should read the ID and quantity from the form using the params hash (which is rather like $_POST in PHP):
```
def do_restock
    @hit=Hit.find(params[:id])
    if @hit.restock(params[:quantity].to_i) == true
        flash[:notice] = 'Success'
    else
        flash[:notice] = 'Invalid quantity'
    end
    redirect_to :action => 'list'
end
```
The do_restock controller is working in a similar way to the buy controller, above. We find the hit with the given ID, then we call a restock method in the model (which we haven't written yet), test its return value, and set up ana appropriate flash message.
So lastly, we need to add a restock method to the model, i.e. the Hit class. This will actually restock a given Hit by increasing the value of its quantity field in the database. The restock method will look like this:
```
def restock(amount)
    if amount > 0
        self.quantity = self.quantity + amount
        save
        return true
    else
        return false
    end
end
```
Hopefully this should be fairly self explanatory: the restock method takes a parameter representing the amount to increase the stock by, then the quantity is increased by that amount and the changes saved to the database. Finally we return true or false depending if there was an error: if the supplied amount was 0 or less, we return false to indicate an error.

Summary of the architecture of a Rails application

A Rails application contains:

A number of controllers, each of which represents a particular entity, such as a Hit or a User. Each controller has a number of methods representing different things you can do with the entity, such as show it, buy it or restock it.
A corresponding view, one for each controller method, e.g. a form (for an action such as restocking a hit) or a web page containing a list of items (for an action such as list).
Some controller methods do not have a view. For example the buy method did not have a view. This is because buying a hit is an action which manipulates the database, but does not write anything to the screen. Rails allows us to have a controller method without a view as long as we redirect to another page in the controller (as we did: we redirected to the 'list' page)
The model: that part of the code which talks to the database directly. In Rails the model is a class of the same name as the controller, but capitalised and in the singular (e.g. hits->Hit).
If we want to add new code to interact with the database in a custom way (e.g. reduce the stock by 1, or increase the stock by a given amount) we add a new method to the model.