Table of Contents

• • Foreword
  • Code
  • License
• Introduction to Ruby on Rails
  • What is Ruby on Rails?
  • Prerequisites of this Course
  • Required Software
• Installing Ruby on Rails
  • Installing on Windows
  • Installing on Linux
  • Linux on Windows
  • IDE
  • API Documentation
• Web Application in 5 Minutes (or Less)
  • Aling Nena’s Request
  • Creating the Application
  • Generating the Scaffolding
  • Frequently Asked Questions
• Modifying the Application
  • Aling Nena’s Follow-Up
  • Rails Migrations
  • An Introduction to the Model-View-Controller Architecture
  • Modifying the Model
  • Modifying the Controller?
  • Modifying the View
• Rails Applications Without Scaffold (part 1: Show and List)
  • The Plan
  • Viewing a Record
  • Adding a List Page
• Rails Applications Without Scaffold (part 2: Delete and Search)
  • Deleting a Record
  • Adding a Search Screen
• Rails Applications Without Scaffold (part 3: Insert and Update)
  • Creating a Record
  • Editing a Record
• Rails Applications Without Scaffold (part 4: RESTFul Routes, Callbacks, Filters, and Layout)
  • Reduce Route Entries with Resource-Based Routing
  • Perform Actions While A Model is Saved using Callbacks
  • Limiting User Access with Filters and Authentication
  • Layouts and Rendering in the View
• Associations
  • Migrations for Associations
  • Defining Associations in Models
  • One-to-One Relationships
  • One-to-Many Relationships
  • Many-to-many Relationships
• Skimming through Rails
  • Rails Migrations
  • Active Record
  • Action Controller
  • Action View
  • Active Support Time Extensions
• Ajax
  • Prototype
  • jQuery
• Automated Testing with RSpec
  • Overview to Automated Testing
  • RSpec
  • Analysis of the Generated Specs
  • Test Driven Development with RSpec
  • More about Automated Testing
• Deployment
  • Configuration
  • Internationalization
  • Deployment Options
  • Rake

Foreword

Computer Science teachers have it easy. Every time a new semester rolls in, they can simply reuse the material they’ve been using for years.

As a teacher of a quickly evolving web framework, I do not have that luxury.

As I write this, less than 24 hours has passed since the Rails Core team released the new version of Ruby on Rails: version 3.1.0. This means that I now have to update my student manual (i.e. this document) for upcoming classes to use this new version. Having done that before when we moved from Rails 2.3. to Rails 3.0, I know how much of this document will be changed: sections will be gutted, swaths of code rewritten, and at least one new chapter would be added.

And, yet again, I will not be paid a single cent for those updates.

So instead of just letting this nearly obsolete document go to waste, I’ve decided to give it away for free.

Code

Code examples in this book are available at the following locations:

• https://github.com/bryanbibat/rails-3_0-tutorial-code - up to date code. written under Ubuntu 11.04
• https://github.com/bryanbibat/alingnena-rails3 - mostly outdated. has the advantage of being written and verified under Windows 7

License

This book is copyright ©2011 by Bryan Bibat.

This work is licensed under the Creative Commons Attribution-NonCommercial 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA

tl;dr: I’m cool with you modifying this document in order to better suit your needs e.g. turning Aling Nena into Farmer Bob, changing the Chrome/Firefox screenshots to Safari, using Swahili instead of Tagalog in the I18n section, etc. What isn’t ok is modifying this work in order to sell it, profiting off it while leaving this poor third-word developer to starve. =(

Introduction to Ruby on Rails

What is Ruby on Rails?

Ruby on Rails (often shortened to Rails or RoR) is a web development framework written in the Ruby programming language. Some popular examples of websites using Rails are Hulu, BaseCamp, and GitHub.

The biggest draw for Rails is the radical improvement in productivity compared to other web application platforms. Rails makes programming web applications easier by making several assumptions about what every developer needs to get started. This allows you to write less code while accomplishing more than many other languages and frameworks. Longtime Rails developers also report that it makes web application development more fun.

Prerequisites of this Course

This course assumes that the student is an experienced web developer and is familiar with:

1. Basic web development: HTML, CSS, and JavaScript
2. Web application development: HTTP 1.1, server-side scripting
3. Object-Oriented Programming
4. SQL and RDBMS concepts

This course will focus on theRails part ofRuby on Rails. This means that knowing the Ruby programming language is not a prerequisite of this course, nor will we dwell too much on the language. We will only discuss just enough Ruby as we go along the lessons – don’t worry; you can still do a lot in Ruby on Rails even with limited Ruby knowledge.

Learning Ruby beforehand will help, of course. Some suggested sites for learning Ruby:

• TryRuby.org
• Learn Ruby The Hard Way

Required Software

For this training course, we will be using the following software:

• Ruby 1.9.2
• Ruby on Rails 3.0.20
• RSpec Rails 2.5
• SQLite 3 or MySQL 5

Installing Ruby on Rails

The Apple Macintosh is the platform of choice for developing Ruby on Rails apps. However, the reality is that most of us struggling developers don’t have the money to spare in buying expensive Apple computers.

This section will cover how to install a Ruby on Rails development environment on Windows and Linux.

Installing on Windows

Download and use the latest RailsInstaller from the linked website. This installer already includes Ruby 1.8.7, Rails 3.0.7, SQLite 3 as well as Git and essential tools for building native extensions in Windows.

A smaller alternative would be RailsFTW. This installer does not contain Git and build tools, but it’s smaller, comes in both Ruby 1.8.7 and 1.9.2, and includes MySQL support.

Don’t worry about these installers using slightly older versions of Rails; version 3.0.7 will still work with the examples in this book.

Installing on Linux

Installing RVM

There are several ways of installing Ruby in Linux. Here we will be using Ruby Version Manager (RVM) which will handle the installation for us. RVM requires Git, curl and essential build tools, while Ruby and SQLite have their own requirements. We install them all using (note that the following command must be in a single line!)

$ sudo apt-get install curl build-essential git-core bison openssl libreadline6
  libreadline6-dev zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev libxslt-dev
  autoconf libc6-dev libsqlite3-0 libsqlite3-dev sqlite3 

(For the sake of simplicity, we’ll assume you’re using Ubuntu for the entireInstalling on Linux section.)

After installing the required packages, we install RVM using the following command:

$ bash < <(curl -s https://rvm.beginrescueend.com/install/rvm) 

To complete the installation, we must first tell bash startup RVM whenever we open bash shell by adding the following line at the end the .bashrc file in your home folder:

[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" 

Open a new terminal window to startup RVM and run the following command to install the latest version of Ruby 1.9.2:

$ rvm install 1.9.2
$ rvm 1.9.2 --default 

Installing Rails and SQLite

Installing Rails and SQLite is a matter of calling RubyGems, Ruby’s package manager. Thanks to RVM, we do not need to have admin rights to install Rails:

$ gem install rails -v=3.0.20
$ gem install sqlite3 

Linux on Windows

Compared to Mac OS X and Linux, certain Rails commands are noticeably slower in Windows. This is more pronounced once you start using RSpec.

If your computer is fairly new (i.e. multi-core processor and 2 or more GB of RAM are cheap nowadays), you might want to consider running Linux in a virtual machine; Ruby can run faster in Linux even though it’s just a virtual machine.

There are free virtualization software available on the Internet. The most popular ones are Oracle VirtualBox and VMware Player.

As for the Linux distribution, we recommend Ubuntu so that you could just follow the installation instructions above for installing Ruby on Rails.

IDE

ASP.NET and Java EE developers might be surprised to know that the most popular “IDE” for Ruby on Rails is TextMate, a relatively simple text editor on the Mac. As we shall see later, there are some reasons why Ruby on Rails does not require full-fledged IDEs for development.

Any text editor will do fine for Ruby on Rails development. For Windows, Redcar and Sublime Text 2 are good choices because they’re free (as of this writing), has Ruby syntax highlighting, and can handle Linux and Mac line breaks properly (unlike Notepad). Linux users can usevim oremacs; both editors have steep learning curves but they can be more productive than IDEs once you get the hang of them.

If you still insist on using an IDE, there’s Aptana RadRails, NetBeans 6.9.1, and JetBrains RubyMine.

API Documentation

This document is meant to be more of a training manual than a reference manual. It will not contain detailed descriptions of each function available in Ruby on Rails, instead, you will have to refer to the official API documentation for those details.

While API docs for Rails and the other software above are freely available online, you can also download searchable API docs from RailsAPI.com for local viewing.

Web Application in 5 Minutes (or Less)

Aling Nena’s Request

Imagine one month from now you’re walking down your street. Passing by your neighborhood sari-sari store, its owner, Aling Nena, calls you over.

“You know how to make websites, right?”

Now, you’ve known Aling Nena since childhood so you know that she’s not your typical sari-sari store owner. Instead of a TV, she’s got a desktop computer with broadband connection to occupy herself while waiting for customers. It’s not uncommon to see her browsing social networking sites or chatting with her children and grandchildren abroad whenever you buy something from her store.

“I’d like to have a website for tracking the debts of my customers. I’m using a spreadsheet now, but it’s getting more and more of a hassle to open the spreadsheet file when I could just open a new tab in my browser. Think you could do it? I’ll give you a week-long supply of cornik for your trouble…”

Once you heard the last part, you immediately accepted the request. I mean, who could turn down such an irresistible offer like a week-long supply of cornik?

And so Aling Nena enumerated what she wants the website to do:

• It must be able to list all of the her customers’ debts.
• It must be able to create a new debt record.
• It must be able to retrieve and display the details of a single debt.
• It must be able to update the details of a debt.
• It must be able to delete a debt record.

Also, a debt record should have the following details:

• name – the name of the customer with the debt
• item – contains the items bought under credit; can be much longer than the name field
• amount – the amount the customer owes Aling Nena; should allow cents.

“Sure, no problem,” you replied after seeing the requirements.

You take out your laptop from your bag, booted it up, and then entered the following commands in the command line:

$ rails new alingnena-app
$ cd alingnena-app
$ rails generate scaffold debt name:string item:text amount:decimal
$ rake db:migrate
$ rails server 

After running these commands, you open your browser to http://localhost:3000/debts and showed the results to Aling Nena.

Clicking the New Debt Link will open the New Debt page.

Clicking Create will save the new debt.

Finally, clicking the Back link will return you to the List Debts page. Each existing record has Show, Edit, and Destroy links so that Aling Nena can view, update, and delete the records, respectively.

If you’re like Aling Nena, who’s staring speechlessly at the screen amazed at how fast you created the web application, you might be wondering, “That’s it?!?”

Yes, that’s all you need to do to create a working Ruby on Rails application. In the next few sections, we shall discuss what just happened here.

$ sudo apt-get install libmysqlclient-dev
$ gem install mysql2 

$ rails new alingnena-app -d mysql
$ cd alingnena-app
$ rails generate scaffold debt name:string item:text amount:decimal
$ rake db:create
$ rake db:migrate
$ rails server

$ rails destroy scaffold debt 

Creating the Application

The first command tells Rails to create the directory structure and the files needed by the application.

$ rails new alingnena-app 

In this case, we named our application “alingnena-app” and the following directory structure was created by rails:

Here’s a brief explanation for each item in the application folder:

At this point, we can already test if the application is setup properly by skipping the 3rd and 4th commands above i.e.:

$ cd alingnena-app
$ rails server 

Opening your browser to http://localhost:3000/ will result in the following screen:

If you’ve read the table above thoroughly (which I bet you didn’t), you’ll realize that http://localhost:3000/ points to the public/ folder. Like many web servers, the default HTML file returned by the server is index.html when you don’t specify the page. You could verify this by manually opening the said file.

Basically that index.html file is the “home page” of the application. Later in this course, we shall discuss how to replace that static web page with a dynamic one.

Generating the Scaffolding

The next command generates everything needed for the debt application: the code for setting up the database tables, the code to handle the user’s actions, the web pages displayed to the user, etc. The command is a bit complicated so let’s dissect the command part-by-part:

$ rails generate scaffold debt name:string item:text amount:decimal

• rails generate – tells ruby to run the “generate” script
• scaffold – tells the generate script to create a scaffolding. Like its construction counterpart, a scaffold is just a temporary structure where we start building our applications.
• debt – the name of this part of the application. In the next chapter, we shall discuss the concept ofConvention Over Configuration and this is a prime example of that approach. Take note of how Ruby on Rails uses this single word as aconvention throughout the application:
  • “Debts” will become the name of the resource i.e. the table in the database.
  • The model class that will handle the database operations for that resource will be named “Debt.”
  • The debt handling application will be accessed via http://localhost/debts.
  • “Debts” will be the name of the debt handling application as we shall later see in the Action Controllers.
  • name:string item:text amount:decimal – these define the fields for the Debts table. As you may have guessed, this part tells the script that the table will have a “name” field containing strings, an “item” field containing text (longer than a string), and an “amount” field containing a decimal value. Convention Over Configuration is also active here, by looking at the type of field, the script knows that “name” should use an <input type="text"> element in the web page while “item” would use <textarea>.

The command generates the following files:

One thing to note here is that generated scaffolding only has one flow:

While this might be sufficient for simple applications, this flow is rarely used in typical real world applications. Being a temporary structure, it’s very likely that you will modify the scaffolding to the point that the finished product is very different from where you started. That said, many experienced Ruby on Rails developers avoid scaffolding entirely, preferring to write all or most of their source code from scratch.

Setting Up the Database

The final command deals with setting up the database:

$ rake db:migrate 

Database migrations are Ruby classes that are designed to make it simple to create and modify database tables. The rake command above applies all migrations not yet applied to the target database.

In our example, the command above applies the migration that was part of the generated scaffolding, 2011xxxxxxxxxx_create_debts.rb. Let’s take a look at the contents of that file:

class CreateDebts < ActiveRecord::Migration
  def self.up
    create_table :debts do |t|
      t.string :name
      t.text :item
      t.decimal :amount
      t.timestamps
    end
  end
  def self.down
    drop_table :debts
  end
end 

This is an example of a real working Ruby code. You might notice how high-level Ruby code is; even if this is the first Ruby code you’ve seen in your life, it doesn’t take much effort to see that this creates a table named “debt” along with the fields we’ve specified before. This file also defines (“def”) the “down” behavior, namely, to drop the created table (the opposite of the “up” behavior). Later in the course, we shall discuss how to do other things with migrations like modifying tables and rolling back changes.

Frequently Asked Questions

Did Ruby on Rails compile the generated code?

No. Ruby is an interpreted language like JavaScript and so it isn’t compiled. You could even edit your code while the server is running – you would immediately see the changes the next time you access the updated application.

Can I use a different web server aside from the bundled one?

For most cases, the built in web server (WEBrick) is sufficient for development. You can just switch to more full fledged servers like Apache and nginx once you deploy the live version of your application.

However, if you feel WEBrick is somewhat slow and you’re using Linux or OS X, you might want to consider using Unicorn instead. The latter can be installed via:

$ gem install unicorn 

Once installed, you can start the server by running unicorn instead of rails server. Note that this will start up the server in port 8080 instead of port 3000.

Some commands start with rails, others with rake. What’s the difference?

• rails – the command used to create an application and run Rails scripts.
• rake – similar to C’s “make” (rake = Ruby + make), it’s a tool that allows more complicated scripts for tasks like database migration and running unit tests.

Modifying the Application

Aling Nena’s Follow-Up

After being astounded by how fast you build the program, Aling Nena suddenly remembered something.

“Can you add another field where I can put remarks like ‘This was partially paid’ or ‘He promised to pay for it before the end of March’ and so on?”

This is a common sight in software development. Software (being soft) are often subject to changes. Fortunately for us, Rails provides ways to easily handle changes in the requirements.

Looking at this change request, it is clear that we need to do two things:

1. update the table in the database to add the new field, and
2. update our application to accommodate the new field.

Rails Migrations

As mentioned in the previous chapter, Rails uses migrations to simplify database tasks. Before we move on to how to use migrations to meet our task (i.e. add a new field to the database), let’s discuss why there are migrations in Rails.

In other more traditional software development platforms, when you want to add a new field to the database, you’ll need to write an SQL statement like

ALTER TABLE debts ADD remarks VARCHAR(255); 

and give it to someone who is responsible for maintaining the databases in order for it to be applied to all those databases. Now, granted SQL isn’t that hard to learn, and having a DBA managing the database changes can be a somewhat efficient way of handling the data, but there are some reasons why migrations have the upper hand over this approach.

The first benefit of migrations is that it simplifies the whole database management process. Rails includes scripts to apply changes to different databases allowing any developer (or even a batch script) to deploy changes without the need for a database administrator.

Rails migrations also have a limited set of data types which are internally converted to the appropriate data type for different kinds of databases. In other words, unlike with manual SQL wherein you have to take into account the differences between Oracle, MySQL, IBM DB2, etc., you don’t need to worry about these things in migrations.

Another benefit of migrations is that it provides ways to migrate to a certain snapshot of the database structure. As there are timestamps in the file name, anyone can use a command to choose which timestamp to roll back to. This is useful when you’re testing old builds which require an older version of database schema to work. (We will discuss this command in a later chapter.)

Generating the Migration

As migrations have timestamps in their file names, it may not be practical to create them from scratch, with the developer defining the current timestamp in the file name. A better approach would be to use the built in migration generator which creates an empty migration file with a proper timestamp.

The format of the command to generate the migration is:

$ rails generate migration [MigrationName]

MigrationName can be in camel case or lower case separated by underscores (Rails converts the former to the latter in the actual file name, and the latter to the former in the class name). Here is a sample file produced by the command:

class MigrationName < ActiveRecord::Migration
  def self.up
  end

  def self.down
  end
end

The generated file, as mentioned above, is empty, and it is up to the developer to define the changes to be applied to the database using migration commands. Migration methods called in self.up will be applied when the migration is executed, while methods in self.down will be called when the migration is reversed or rolled back.

Rails provides a shortcut for creating migrations that add or remove columns from tables. When you name your migrations as Add[ColumnName]To[TableName] or Remove[ColumnName]From[TableName] followed by a series of field_name:data_type pairs, Rails will automatically create the add column or remove column statements, respectively, in the migration. For example, we can perform the required change to our application without having full knowledge of the migration commands:

$ rails generate migration AddRemarksToDebt remarks:text 

This command will create the following migration file:

class AddRemarksToDebt < ActiveRecord::Migration
  def self.up
    add_column :debts, :remarks, :text
  end
  def self.down
    remove_column :debts, :remarks
  end
end

Rails supports the following data types:

We’ll discuss the other possible migration options in a later chapter. For now, let us just stick with add_column / remove_column.

$ irb
irb(main):001:0> def hello(x)
irb(main):002:1>   "hello #{x}"
irb(main):003:1> end
=> nil
irb(main):004:0> hello("world")
=> "hello world"

x = 10
x = "20"

def add(a, b)
  return a + b
end

def add(a, b)
  a + b
end

class AddRemarksToDebt < ActiveRecord::Migration
  def self.up
    add_column :debts, :remarks, :text
  end
  def self.down
    remove_column :debts, :remarks
  end
end

puts add(3, 3) 

puts add 3, 3 

add_column :debts, :remarks, :text 

add_column :debts, :remarks, :text 

class AddRemarksToDebt < ActiveRecord::Migration
...
end 

module ActiveRecord
  class Migration
    ...
  end
end 

module Module1
  def hello
    puts "hello"
  end
end

module Module2
  def world
    puts "world"
  end
end

class HelloWorld
  include Module1
  include Module2

  def initialize
    hello
    world
  end
end

An Introduction to the Model-View-Controller Architecture

With the database side of the task out of the way, we can now move on to modifying the application itself. But before that, let’s take some time to understand how various components are organized in Rails via the Model-View-Controller (MVC) architecture.

MVC was originally created in the 1980s as a pattern to follow when creating graphical user interfaces in Smalltalk. It found a resurgence in the early 2000s when it became apparent that this model was also applicable for web applications.

In MVC, systems are divided into three parts: the model, the view and the controller. A typical flow through an MVC system would be as follows:

1. User (in the form of a browser here) sends a request to the Controller
2. Controller interacts with the Model
3. Controller invokes the View
4. View renders the information sent to the User.

Putting this in context of Rails applications, when a browser visits a Rails web page, it goes through the following steps:

1. Browser requests a page from the server e.g. http://my.url/books/123
2. Routing finds the Books Controller
3. Controller interacts with the Model
4. Controller invokes the View
5. View renders the page to be sent to the browser

Why use MVC?

In the early days of the web (and even up to now), many web applications were written with all of the processing logic (business processing, routing, rendering) concentrated in a single location. This approach didn’t scale well for some reasons:

• Maintenance was hard. Lack of structure meant that the dependencies between modules aren’t clear. Changing one part of the system might affect another part of the system without a programmer knowing it.
• Debugging was hard. As all of the processing logic were contained in single files, a programmer hunting for the code that caused a bug would have to scan through a lot of code which has nothing to do with the bug itself before finding it.

MVC addresses these problems. First off, the structure provides a degree of isolation between modules. Sure, changing a Model might still affect a lot of programs in the system, but at least the extent of the changes can be easily predicted.

When you encounter a bug in a Rails application, you also have a better idea where to look for the problem. This diagram shows where the source code for the MVC components are located:

MVC best practices

There are many best practices when it comes to using MVC. We’ll list down a few here, but we’ll also have to use an analogy to make it clearer to someone who hasn’t used MVC before.

Our analogy would be a restaurant analogy.

In a fine dining restaurant, you have your chefs (Models) which prepares the food for the customers (Views). There are also waiters (Controllers) that facilitate communication between the customers and the chefs.

Chefs are expected to do all of the preparing, cooking, and plate presentation on the dishes. Aside from very trivial changes to the dishes (e.g. offering to add pepper to the soup) the waiters do not do anything to the food. Here is the first best practice for MVC: Models should do most of the processing, controllers should only focus on the routing. Similarly: If you find your controllers doing a lot of processing, find a way to move those logic to the model. This is usually called the “fat model, skinny controller” approach.

Some dishes are so complicated that a single chef isn’t enough to handle it. In this case, it’s alright for multiple chefs to work on a single dish without having to go through the waiter. In other words, Related models can communicate with each other before passing their result to the controller.

As for our customers, they should not talk directly to the chef and vice versa i.e. Views should not directly call models directly, and vice versa. However, this does not mean that the customers should be mindless. It’s up to them how to eat their food. In MVC terms, Processing logic is allowed in views, as long as it’s related to the view or presentation.

Now that we understand the basic underpinnings of Rails, we now have a basic idea about what to modify in our system to meet the demands of the current task.

Modifying the Model

…or not.

Veterans of other MVC frameworks might think that we need to modify some model related files to reflect the changes to the database. In some frameworks, we might need to add additional fields to certain classes. In other frameworks, we might need to modify certain XML files to include the new fields.

Fortunately for Ruby on Rails, we don’t need to do any of those.

At the heart of Rails’ model components isActive Record, a Ruby package that handles the database related portion of Rails. Not only does Active Record provide functions for saving and retrieving data, it also provides other features that help simplify database management e.g. migration commands.

To make development easier, Active Record directly checks the database schema to determine the fields of the model. This is made possible thanks to Convention over Configuration (database fields and model fields should be named the same) and Ruby’s dynamic nature (methods can be defined on the fly). In short, there is no need to change any part of the model when the database is changed – the change is automatically applied to the model and we could access theremarks field via @debt.remarks.

Of course, if we would need to add some field validation (e.g. mandatory checking, field length checking), we will need to modify the app/models/debt.rb. We will leave that topic for a later chapter.

Modifying the Controller?

By looking at the flow of the MVC model, you could see that adding a new field to our screen wouldn’t affect our controller: the routing of data is still the same after the change. Therefore, we don’t need to modify debts\_controller.rb.

(By the way, the Ruby package that handles the controller for Rails is ActionController.)

Modifying the View

In the end, the only files we have to modify to include the new field is in the View, namely the four view files for Listing, Show, Create, and Edit.

Insert the highlighted lines into app/views/debts/index.html.erb:

<h1>Listing debts</h1>
<table>
  <tr>
    <th>Name</th>
    <th>Item</th>
    <th>Amount</th>
    <th>Remarks</th>
  </tr>
<% @debts.each do |debt| %>
  <tr>
    <td><%= debt.name %></td>
    <td><%= debt.item %></td>
    <td><%= debt.amount %></td>
    <td><%= debt.remarks %></td>
    <td><%= link_to 'Show', debt %></td>
... 

Insert the highlighted lines into app/views/debts/show.html.erb:

...
<p>
  <b>Amount:</b>
  <%= @debt.amount %>
</p>

<p>
  <b>Remarks:</b>
  <%= @debt.remarks %>
</p>
...

And finally, insert the highlighted lines into app/views/debts/\_form.html.erb:

...
  <div class="field">
    <%= f.label :amount %><br />
    <%= f.text_field :amount %>
  </div>
  <div class="field">
    <%= f.label :remarks %><br />
    <%= f.text_area :remarks %>
  </div>
  <div class="actions">
...

(Just as in the controller, the Ruby package that handles the view for Rails is ActionView.)

Rails Applications Without Scaffold (part 1: Show and List)

Pleased with how you handled the “Debt Records” program, Aling Nena has decided to hire you part time in order to computerize every aspect of her shop.

Part of this job is to create a system to to handle the inventory of her shop’s goods. So for your next task, you need to create a program which maintains the list of products in her shop.

This is a good time to discuss how to create a program from scratch i.e. without using therails generate scaffold script.

The Plan

The Product Maintenance program has 6 different parts:

• User must be able to create a product record
• User must be able to view the product record
• User must be able to view a list of product records
• User must be able to modify a product record
• User must be able to delete a product record
• User must be able to search for a product record

In addition to this, we also need to setup the database for a Products table with the appropriate fields. In the end, we have 7 tasks to be done in the following order:

1. Create the migration for Product
2. Program the “Show Product” module
3. Program the “List Products” module
4. Program the “Delete Product” module
5. Program the “Search Products” module
6. Program the “Create Product” module
7. Program the “Edit Product” module

We’ve chosen this order of tasks so that the tasks are done in increasing coding complexity. So without further ado, let’s proceed with the first 2 tasks.

Viewing a Record

First up is the “Show Product” module, a page that displays the details of a certain Product record. We’ve combined this step with the “generate migration” step because we’re going to generate the migration along the way anyway.

The basic flow for showing a single record from the user is as follows:

1. User provides the id of the record via the URL
2. Program retrieves the record from database
3. Program renders the retrieved data into a web page and sends it to the user

In this lesson, we shall see how these steps are coded in Rails.

Generating a Model and adding test data

Instead of usingrails generate scaffold, we shall userails generate model, a script that only generates the migration and the model for the specified model and fields. The syntax of the latter is the same as the former:

$ rails generate model Product name:string description:text cost:decimal stock:integer 

We need to modify the generated migration to add some dummy data for our new screen. Add the highlighted lines to the migration file:

class CreateProducts < ActiveRecord::Migration
  def self.up
    create_table :products do |t|
      t.string :name
      t.text :description
      t.decimal :cost
      t.integer :stock
      t.timestamps
    end
    Product.create :name => "test product 1", :description => "test description 1", 
                   :cost => 1.11, :stock => 10
    Product.create :name => "test product 2", :description => "<b>test description 2</b>", 
                   :cost => 2.22, :stock => 20
  end

  def self.down
    drop_table :products
  end
end

Generating a Controller and View Page Templates

A controller action (not to be confused with Action Controller) is a public instance method inside the controller class that processes requests from the user. We can generate controller actions and their corresponding views with the use of therails generate controller script. The syntax for the script is:

rails generate controller controller_name action [action2 action3 ...] 

Given the conventions, here’s the script for generating our controller and view:

$ rails generate controller products show 

This script will create the controller app/controllers/products_controller.rb:

class ProductsController < ApplicationController
  def show
  end

end

and also the view app/views/products/show.html.erb:

<h1>Products#show</h1>
<p>Find me in app/views/products/show.html.erb</p>

You can now test the new controller and view by running the server (rails server) and going to http://localhost:3000/products/show. The following page should be displayed (you may have to restart the server through rails server):

The show action in the controller automatically refers to the show.html.erb file even without additional code as mentioned in the Rails conventions above.

We still have 2 problems at this point:

1. We still haven’t displayed the details of the record.
2. The format of the URL is different from the convention used by the code generated fromrails generate scaffold i.e. http://localhost:3000/products/1.

The 2nd problem is simpler and deals with routing so let’s tackle that first.

Routing

Routing deals with how different pages and controllers are linked to each other in a system. In Rails, there is a central configuration file that determines the available routes in the system. At first glance this may look like a violation of the Convention over Configuration mantra, but as we shall see much later, there are ways to let this routing file use convention to reduce the amount of configuration needed.

For this tutorial, we shall do away with the convention-related shortcuts so that you could understand how rails routes pages together. Take a look at the generated config/routes.rb file:

AlingnenaApp::Application.routes.draw do
  get "products/show"
  resources :debts  
  # The priority is based upon order of creation:
  # first created -> highest priority.
  # Sample of regular route:
  #   match 'products/:id' => 'catalog#view'
  # Keep in mind you can assign values other than :controller and :action
  # Sample of named route:
  #   match 'products/:id/purchase' => 'catalog#purchase', :as => :purchase
  # This route can be invoked with purchase_url(:id => product.id)
  # Sample resource route (maps HTTP verbs to controller actions automatically):
  #   resources :products
  # Sample resource route with options:
  #   resources :products do
  #     member do
  #       get 'short'
  #       post 'toggle'
  #     end
  #
  #     collection do
  #       get 'sold'
  #     end
  #   end
  # Sample resource route with sub-resources:
  #   resources :products do
  #     resources :comments, :sales
  #     resource :seller
  #   end
  # Sample resource route with more complex sub-resources
  #   resources :products do
  #     resources :comments
  #     resources :sales do
  #       get 'recent', :on => :collection
  #     end
  #   end
  # Sample resource route within a namespace:
  #   namespace :admin do
  #     # Directs /admin/products/* to Admin::ProductsController
  #     # (app/controllers/admin/products_controller.rb)
  #     resources :products
  #   end
  # You can have the root of your site routed with "root"
  # just remember to delete public/index.html.
  # root :to => "welcome#index"
  # See how all your routes lay out with "rake routes"
  # This is a legacy wild controller route that's not recommended for RESTful applications.
  # Note: This route will make all actions in every controller accessible via GET requests.
  # match ':controller(/:action(/:id(.:format)))'
end

It can be a daunting file at first glance, but removing all of the comments, we can see that it’s a pretty simple file:

AlingnenaApp::Application.routes.draw do
  get "products/show"

  resources :debts  
end

Before we proceed with creating our routes, let’s discuss first the idea behind the routing conventions in Rails: REST.

Representational State Transfer (REST)

Representational State Transfer (REST) is a scheme for communicating between clients and servers using HTTP. It was promoted as a stateless means of communication in a 2000 paper by Roy Fielding.

We will not go into detail about REST, and instead, we shall only focus on the parts that are relevant to us in Rails. In that regard, there are two main points about REST that we should know:

1. All resources are uniquely identified by a URL. For example, a product record can be identified with the following URL:

   http://my.url/products/1

   In contrast, an item done in a non-REST framework might look like this

   http://my.url/view_product.do

   In this case, all product records share the same URL and are differentiated only based on the user’s state, either via session or cookie.

2. Actions done on resources are defined by the HTTP verb of the request. Here are some examples:
   • GET http://my.url/products – get (a list of) all products
   • POST http://my.url/products – post a new product to the list of products
   • GET http://my.url/products/1 – get the product with the id of 1
   • PUT http://my.url/products/1 – put an updated product with the id of 1 to the database
   • DELETEhttp://my.url/products/1 – delete a product with the id of 1

The 5 HTTP commands in the 2nd point above are, by convention, how resources should be handled in Rails.

Now that we know the convention for the URL (http://localhost:3000/products/1) and the convention for the controller action (method must be namedshow for viewing records), we can now move on to connecting the two in our config/routes.rb.

Configuring Routing in routes.rb

Going back to the diagram in MVC, all browser requests to our Rails server goes to the routing component of the controller first. At this point, Rails checks entries inside the routes.rb file from top to bottom to see which controller and action to call.

We want to add a new “route” to theshow action in theproducts controller and we can do this using thematch declaration inside the routing block. The basic syntax of match is:

match(path_string, options_hash)

When Rails reaches amatch line in the routes.rb file, it first checks the path_string if it matches the request’s URL. The Ruby symbols in the path_string are placeholders and may match any part of the URL. When these symbols are matched to a part of the URL, they are converted into parameters inside aparams hash. (See Ruby Corner – Hash below for a discussion on hashes)

For example, if you removed the commented from the last line in the default resource

match ':controller(/:action(/:id(.:format)))' 

and then you called http://localhost:3000/products/show/1, Rails would match this request with the route match ':controller(/:action(/:id(.:format)))' producing the following parameters:

params = { :controller => 'products', :action => 'show', :id => 1 } 

Based on this params hash, Rails can now route the request to the controller and action we created earlier.

We don’t need to define the :controller and :action symbols within a route. We can specify them as defaults using the => form of match:

match('products/show' => 'products#show') 

In this case, opening http://localhost:3000/products/show will make Rails use the controller and action defined in the right side, in this case, the show action of the products controller.

We can also use the :via option to constrain the request to one or more HTTP methods. For example:

match('products/show' => 'products#show', :via => :get) 

Would make the route accessible only via the GET method. Note that the above route has a shorthand version, and it was inserted in our routes.rb when we used the generator script:

get "products/show" 

At this point, we can create a route that matches Rails’s conventions on “show record” pages:

AlingnenaApp::Application.routes.draw do
  resources :debts
  match('products/:id' => 'products#show', :via => :get)  
 
end

Going to http://localhost:3000/products/1 will create the following parameters:

params = { :controller => 'products', :action => 'show', :id => 1 } 

As you can see, while the whole URL is matched by the path (‘products/:id’) only the:id part is converted to a parameter. The rest of the parameters for controller and action are provided as defaults at the right of the => symbol.

Testing http://localhost:3000/products/1, we now see the following page:

We’ve completed the routing setup. We can now proceed to building the rest of the “Show Record” program.

my_hash = {}
another_hash = { :key =>"value", 1 => "a number" }

puts another_hash[:key]
my_hash["test"] = :value

match(':controller/:action/:id', { :via => :get, :defaults => { :id => 1 } } )

match(':controller/:action/:id', :via => :get, :defaults => { :id => 1 } ) 

match ':controller/:action/:id', :via => :get, :defaults => { :id => 1 }

Putting it all together: Retrieving a Record

To recall, our basic flow for this program is:

1. User provides the id of the record via the URL – already done
2. Program retrieves the record from database
3. Program renders the retrieved data into a web page and sends it to the user

Steps 2 and 3 can be better illustrated by the MVC diagram we had before for Rails:

Retrieve Record in the Controller using Model

According to the diagram, retrieving the data has 3 steps:

1. After the routing dispatches the request to the controller, the controller calls the model to retrieve the data.
2. The model retrieves the data from the database.
3. The model sends the data back to the controller.

The first half of the first step has already been done. All requests to 'products/:id' are now dispatched to the Products controller’s show method. All that is left to do is to actually utilize the model to retrieve data from the database. We can do the remaining steps by inserting the following line to theshow method:

class ProductsController < ApplicationController
  def show
    @product = Product.find(params[:id])
  end
end

Retrieving the data is done using the Product.find(id) method, a class method in Active Record that retrieves a record with anid matching the passedid argument. In the statement above, thisid argument is taken from theparams hash passed to the controller via routing.

To pass the data to the controller, we store the result of thefind method to an instance variable of the controller. This instance variable will be passed by the controller to the view in the next part of the process.

class SomeMigration < ActiveRecord::Migration
  def self.up
  end

  def self.down
  end
end

class Square
  def side_length
    @side_length
  end

  def side_length=(new_length)
    @side_length = new_length
  end
end

s = Square.new
puts s.side_length         # returns nil
s.side_length = 10
puts s.side_length         # returns 10   

...
    create_table :products do |t|
      t.string :name
      t.text :description
      t.decimal :cost
      t.integer :stock
      t.timestamps
    end
...

Display Model data using View

We only have 2 more steps in the Rails MVC diagram:

1. The controller sends the data to the view.
2. The view renders the web page based on the data and sends it to the user.

Rails automatically handles the first step: when you pass control over to the view at the end of the action method, Rails gives the view a bunch of variables to work on:

• special variables like the params hash are available in the view through accessor methods
• all instance variables in the controller are created instance variable counterparts in the view i.e. when you put values in the @product instance variable in the controller, you can access it in the view as@product

Now that we know that we can access @product in the view, the contents of our view should be easy to code. Replace the contents of app/views/products/show.html.erb to:

<h1>Show Product</h1>

<p>
  <b>Name:</b>
  <%= @product.name %>
</p>

<p>
  <b>Description:</b>
  <%= @product.description %>
</p>

<p>
  <b>Cost:</b>
  <%= number_to_currency(@product.cost, {:unit => 'PhP'}) %>
</p>

<p>
  <b>Stock:</b>
  <%= @product.stock %>
</p>

Opening http://localhost:3000/products/1 will give us the following result:

And with that, our “Show Product” page is now complete.

The time now is <%= Time.now %>

Ruby Corner – Escaping HTML characters

Rails automatically escapes HTML characters in views. Try visiting http://localhost:3000/products/2 and check the contents of the description field.

Rails provides a way of outputting raw data via theraw helper method. Try reloading the same page after enclosing the data with a raw method call:

<%= raw(@product.description) %>

Escaping HTML important in web pages: if we do not escape text, malicious users can insert HTML code into our pages and attack our users with Cross-Site Scripting (XSS) and Cross-Site Request Forgery (CSRF) attacks. A simple example would be to go back into our Debts program and create a debt with “<script>alert('hello world!')</script>” as a customer or item, then add raw calls in either the index or the show pages.

Every user who views the item now has a JavaScript code run in their browsers. At this point, hacking the user’s personal information should only take the hacker a few more lines of code. Therefore, one must always take care in using displaying raw output via the raw helper.

<p>
  <b>Cost:</b>
 <%= number_to_currency @product.cost, :unit =>'PhP'%></p>
</p>

Adding a List Page

Let’s move on to our List Products page. The approach is similar to the Show Product page, namely, we retrieve the records then render them in the view.

Preparing the New Files

We don’t need to create or modify anything for the view so let’s proceed with the controller.

There’s no script for updating the controller so we have to do the changes by hand. First, let’s apply the first convention above to the controller and view. Insert a new action index to the controller (the order of the actions do not matter):

class ProductsController < ApplicationController
  def index
  end

  def show
    @product = Product.find(params[:id])
  end
end

Let’s also create a dummy view for the action, app/views/products/index.html.erb:

<h1>Listing Products</h1>
<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Cost</th>
    <th>Stock</th>
  </tr>
  
</table>

For the 2nd convention, we add a new route in config/routes.rb for routing the request to the controller action:

AlingnenaApp::Application.routes.draw do
  resources :debts

  match 'products' => 'products#index', :via => :get 
  match 'products/:id' => 'products#show', :via => :get 
 
end

You can now verify the routing by going to http://localhost:3000/products.

Retrieving All Records

In “show product”, we used the Active Record method find() to find a single record. For “list products”, we shall use all(). Add the following line to the index action:

  def index
    @products = Product.all
  end

Using the all() class method instructs Active Record to retrieve all of records of the model. This variation of the method returns an array of objects instead of a single object.

puts array[3]   # outputs the contents of the 4th element of the array
array[1] = 10   # sets the 2nd element of the array to 10

my_array = ["one","two","three","four","five","six"] 

another_array = [ 10 ]
another_array << 20    # the array now contains [ 10, 20 ] 

# array contains a number, string, symbol and an array
mixed_array = [ 10, "twenty", :thirty, [ 40, 50 ] ]   

puts an_array.size     # outputs the size of the array
an_array.delete_at(2)  # deletes the 3rd element of the array

Displaying the Records

All we need to do now is to display the @products array in the view. This part is slightly complicated so it’s OK to take a peek at how our Debts program handles it.

<% @debts.each do |debt| %>
  <tr>
    <td><%= debt.name %></td>
    <td><%= debt.item %></td>
    <td><%= debt.amount %></td>
    <td><%= debt.remarks %></td>
...
  </tr>
<% end %>

There are three new concepts in this code snippet alone. Let’s discuss two of them before we proceed with adding the actual code our view.

# print "hello world!" 10 times
10.times do 
  puts "hello world!"
end

# print numbers 1 to 10 
1.upto(10) do |number| 
  puts number
end
# print numbers 10 down to 1
10.downto(1) do |number| 
  puts number
end

# print the contents of the array
an_array.each do |item| 
  puts item
end

# print the contents of the array using Enumberable#each_with_index
an_array.each_with_index do |item, index| 
  puts "The element at index #{index} is #{item}"
end
# adds 10 to each element in the array using Array#collect!
an_array.collect! do |item| 
  item + 10
end

<% temp_variable = 20 * 1024 %>
<%= temp_variable %>

<ul>
<% an_array.each do |item| %>
  <li><%= item %></li>
<% end %>
</ul>

Now that we are familiar with iteration and scriptlets, we can now code the rest of the app/views/products/index.html.erb file:

<h1>Listing Products</h1>
<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Cost</th>
    <th>Stock</th>
  </tr>

<% @products.each do |product| %>
  <tr>
    <td><%= product.name %></td>
    <td><%= product.description %></td>
    <td><%= number_to_currency product.cost, :unit => 'PhP' %></td>
    <td><%= product.stock %></td>
  </tr>
<% end %>  
  
</table>

Once coded, we can now go to http://localhost:3000/products to view the “list products” page:

Since we’re done with the “list products” page, we now have time to discuss the third concept introduced in the above code: Ruby Blocks and Procs.

do |var1, var2, ...| 
  ...
end

{ |var1, var2, ...| ... }

Linking the List Page with the Show Page

Before we proceed with deleting records, let’s add links between the index and show pages together first. It can be annoying to manually type http://localhost:3000/products and http://localhost:3000/products/1 just to go between these two pages.

For this, we can use the link_to helper method. This method returns a link based on the arguments you pass it. The syntax is as follows:

link_to(name, options = {}, html_options_hash = nil) 

The name argument is the text used in the link. The options argument can be three different things:

• a string – this will be the URL used by the link. As this is brittle for internal use (paths can be easily changed in the routes.rb), this is only used for external links.
• a hash – the link will be based on both the hash and the routes.rb.
• a non-hash, non-string object – Rails will create a URL based on this object, usually an Active Record. This will be discussed after we finish the entire Product program.

Finally, the html_options_hash is simply a hash of HTML attributes you wish to assign to the link. For example, this link has the CSS class and the id set to “external-link” and “google-search”, respectively:

<%= link_to("Go to Google", "http://www.google.com", 
            { :class => "hello world!", :id => "google-search"}) %>

The resulting link is:

<a href="http://www.google.com" class="hello world!" id="google-search">Go to Google</a>

If the text is too long, you can use the block form of link_to:

link_to(options = {}, html_options_hash = nil) do
  # name
end

To use it, just put the text inside the block:

<%= link_to("http://www.google.com") do %>
  <strong>This link goes to Google</strong>
<% end %>  

Now that we know how to use link_to, let’s link the show and index pages. Insert the following line to index.html.erb:

...
<% @products.each do |product| %>
  <tr>
    <td><%= product.name %></td>
    <td><%= product.description %></td>
    <td><%= number_to_currency product.cost, :unit => 'PhP' %></td>
    <td><%= product.stock %></td>
    <td><%= link_to('Show', { :action => 'show', :id => product.id }) %></td>
  </tr>
<% end %>  
...

And add the following line to the end of show.html.erb:

<%= link_to('Back to List of Products', { :action => 'index' }) %>

<td><%= link_to 'Show', :action => 'show', :id => product.id %></td>

<td><%= link_to 'Show', { :action => 'show', :id => product.id }, :class => 'link' %></td>

Named Routes

There are a couple of problems with using an options hash in link_to. The most obvious problem is that it’s too long. Even if the :controller and :action options can be derived from the current page, it’s still too long for practical usage.

Another problem is that it’s brittle. Suppose we have a link scattered around our system, say an approve account link. Initially our link goes to the approve_account action in the users controller so our links were generated using:

<%= link_to 'Approve Account', :controller => 'users', :action => 'approve_account' %>

Later, we changed the page that handles the account approval to theapprove action of the accounts controller. We would have to manually search all instances of the approve account link and modify it accordingly.

<%= link_to 'Approve Account', :controller => 'account', :action => 'approve' %>

To remedy these two problems, Rails provides a way for us to name routes in theroutes.rb file.

Here’s how you modify our routes for index and show to become named routes:

AlingnenaApp::Application.routes.draw do
  resources :debts
  match 'products' => 'products#index', :via => :get
  match 'products/:id' => 'products#show', :via => :get
  match 'products' => 'products#index', :via => :get, :as => 'products'
  match 'products/:id' => 'products#show', :via => :get, :as => 'product'
 
end

By adding an :as option, we tell Rails to provide two new helper functions based on the route:

• xxxx_path – returns the relative path of the matched route. For example, calling products_path will return /products
• xxxx_url – returns the complete URL of the matched route. For example, calling products_url will return http://localhost:3000/products

The path and URL are interchangeable in almost all cases. For this manual, we shall use the xxxx_path methods due to it being used in generator scripts. Here’s the named route version of the link in show.html.erb:

<%= link_to 'Back to List of Products', products_path %>

When the path in the route contains placeholder symbols, both methods accept arguments to fill up these placeholders. For example, if we want to generate the URL to a certain product, we can use:

...
    <td><%= product.stock %></td>
    <td><%= link_to('Show', { :action => 'show', :id => product.id }) %></td>
    <td><%= link_to 'Show', product_path(product.id) %></td>
  </tr>
<% end %>  
...

...
    <td><%= link_to 'Show', product_path(product.id) %></td>
    <td><%= link_to 'Show', product_path(product) %></td>
...

...
    <td><%= link_to 'Show', product_path(product) %></td>
    <td><%= link_to 'Show', product %></td>
...

Rails Applications Without Scaffold (part 2: Delete and Search)

Deleting a Record

Our next task is deleting a record. Deleting is similar to showing a record, the only differences being the HTTP verb involved and that instead of rendering the specified record, we destroy it.

That said, this task has three steps that we need to code:

1. Provide a way to call the controller action for deleting a product
2. Delete the product record in the controller action
3. Display the “list products” page after deleting the product

Creating a DELETE link

We already know how to create a GET link. In this part, we shall discuss how to create a DELETE link.

First off, let’s create a new route for delete based on the conventions:

AlingnenaApp::Application.routes.draw do
  resources :debts

  match 'products' => 'products#index', :via => :get, :as => 'products'
  match 'products/:id' => 'products#show', :via => :get, :as => 'product'
  match 'products/:id' => 'products#destroy', :via => :delete
 
end

Here we see how Rails can differentiate between the HTTP methods. The destroy action will only be used when the HTTP method is DELETE.

With the route set, we can now modify our controller to add our new destroy action.

  def destroy
    # destroy the specified record
    redirect_to products_path
  end

The redirect_to method can be used to replace a view. Instead of rendering a view, it tells the user’s browser to redirect to another page, resulting in a fresh new request to the target page. In this case, we redirect the user to the “list products” page after deleting the record.

The parameters for redirect_to is the same as the 2nd parameter for link_to (they use the same helper method, url_for) so you can use string for direct URLs, hash for route based URLs, or objects for shortcuts.

Now that we’ve finished setting up the route and the controller, it’s time to make the actual link. Add the following to app/views/products/show.html.erb:

...
</p>
<%= link_to('Delete this record', @product,  
             { :confirm => 'Are you sure?', :method => :delete }) %> <br />
<%= link_to 'Back to List of Products', products_path %>

As you can see, this is practically the same as the “Show” link; we only added some new html_options to change the behavior of the link.

link_to has 3 special html_options:

• :confirm – you can set a confirmation question which will be prompted to the user on click of the link. The link is processed normally if the user accepts.
• :method – this accepts an HTTP verb symbol, either :post, :put, or :delete. With this set, clicking the link will call a JavaScript function which will submit a request to the specified URL with the specified method. If JavaScript is disabled, the link will fall back to GET.
• :popup – This will force the link to open in a popup window. By passing true, a default browser window will be opened with the URL. You can also specify an array of options to pass to JavaScript’s window.open method.

By using :confirm and :method, we create a link that both prompts the user if he wants to continue and sends a request using the DELETE method.

Trying this out results in:

Clicking OK will redirect us to the “list products” screen, confirming that the link and route works.

Deleting the Product

Now it’s time to add the missing lines in our destroy method:

  def destroy
    @product = Product.find(params[:id])
    @product.destroy
    redirect_to products_path
  end

The first line retrieves the record in from the database. We’ve already seen this in our show method.

The second line deletes the record using the Active Record destroy method. Simple, huh?

Trying this out, we see:

Re-running a Migration

We’re still going to add another feature to our destroy action, but before that, we’re going to have to deal with a certain problem first: running out of test data. We only have two test records so we’re bound to end up with an empty database when we continuously test our destroy action.

Thankfully, there’s a command for re-running a migration:

$ rake db:migrate:redo 

This command rolls back the previous migration and runs it again. You can also specify the number of migrations to roll back and re-run by using the STEP environment variable:

$ rake db:migrate:redo STEP=3 

Note that re-running a migration will call the self.down method of the migration. This may or may not damage your data, but it’s something to keep in mind.

Displaying a Message using Flash

The missing feature we’re talking about earlier is the lack of confirmation messages. Right now, our program simply deletes the record and redirects the user without telling her if the operation was successful or not.

We use instance variables to pass data from the controller to the view. However, data in the instance variables are only present in the current request. A new request is generated when we useredirect_to so all of our instance variables are cleared. So for messages to be displayed after a redirect, we have to use another controller specific container: the flash hash.

Like the params hash, the flash hash is available for use in both the controller and the view. What’s different is that items put inside the flash hash last until the next request.

Here’s how to modify our destroy action to include a flash message:

  def destroy
    @product = Product.find(params[:id])
    @product.destroy
    flash[:notice] = "Product was successfully deleted."
    redirect_to products_path
  end

Then we add an additional line at the top of app/views/products/index.html.erb to display the message (the scaffold stylesheet already includes #notice):

<p id="notice"><%= flash[:notice] %></p>

<h1>Listing Products</h1>
... 

Trying the destroy link now results in:

Note that items in the flash hash last until the next request. If you don’t redirect, a message will be present in both the current request and the next request. You can use flash.now instead of flash to set messages that are only available in the current request.

By the way, the most common types of flash messages are :notice (information messages, often in green) and :alert (error messages, often in red). We shall see these two again later.

Adding a Search Screen

Just as deleting records is similar to showing records, filtering records is also similar to listing records.

Here’s the process for searching / filtering product records:

1. Submit a query to a search action
2. The search action retrieves records based on the query
3. Render the retrieved records using the view

In this part, we introduce two new concepts: generating HTML forms in the view, and using an Active Record dynamic finder for searching records. These two concepts deal with step 1 and 2, respectively, while we already know how to do the third step.

Preparation

The choice for the action name is arbitrary so let’s just stick to “search”. With that in mind, let’s modify our controller and view accordingly. Let’s start off with a new route:

AlingnenaApp::Application.routes.draw do
  resources :debts
  match 'products' => 'products#index', :via => :get, :as => 'products'
  match 'products/search' => 'products#search', :via => :get, :as => 'search_products'
  match 'products/:id' => 'products#show', :via => :get, :as => 'product'
  match 'products/:id' => 'products#destroy', :via => :delete 
 
end

We added a named route “search_products” pointing to our new action so that we could simply use search_products_path in our form later.

Let’s add the search action to app/controllers/products_controller.rb:

  def search
    @products = Product.all
  end

We’re not doing any filtering yet; we’re just copying the approach in the index action. We’ll continue with the index-cloning with app/views/products/search.html.erb:

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Cost</th>
    <th>Stock</th>
  </tr>
<% @products.each do |product| %>
  <tr>
    <td><%= product.name %></td>
    <td><%= product.description %></td>
    <td><%= number_to_currency product.cost, :unit => 'PhP' %></td>
    <td><%= product.stock %></td>
    <td><%= link_to 'Show', product_path(product.id) %></td>
  </tr>
<% end %>
</table>

Yes, it’s basically a copy of app/views/products/index.html.erb.

Adding the Search Form to List Products

As web developers, we already know how to tinker with the URL to pass query strings to the server. Our users obviously don’t know how to do that manually so we have to provide a search form for them to use.

Insert the following lines to app/views/products/index.html.erb:

<%= form_tag(search_products_path, {:method => :get} ) do %>
  <%= label_tag("name", "Search by product name:") %>
  <%= text_field_tag("name") %>
  <%= submit_tag("Search") %>
<% end %>

If you view the source of the updated form, you will realize that every helper we used corresponds to an HTML form element.

The form_tag helper generates a form element, enclosing everything inside the block inside the form. Its syntax is (note that the tag must be in an expression, not a scriptlet):

<%= form_tag(url_for_options = {}, options = {}, *parameters_for_url) do %>
  ...
<% end %>

The url_for_options are the same as the options used in link_to and redirect_to (the string, hash, or object parameter in case you forgot). Like link_to, the second hash allows you to set HTML attributes for the form along with two additional options: you can set :multipart to true if you want to set the enctype to “multipart/form-data” (useful for submitting files), and you can set the :method to either :get, :put, :post, or :delete (:post is used by default). The parameters_for_url is simply a hash.

Here’s a quick rundown on the other form helpers we used in the search form:

• label_tag – creates a label. It has 3 parameters:
  • first parameter sets the for attribute
  • second parameter sets the text inside the label. Uses the value of the first argument if not specified.
  • third parameter is a hash for setting HTML attributes
• text_field_tag – creates a standard text field. Also has 3 parameters
  • first parameter sets the name attribute
  • second parameter sets the value of the field
  • third parameter is a hash for setting HTML attributes. You can also set additional options: you can set :disabled to true to disable the field, you can also set the :size to set the number of visible characters that will fit in the input, and you can also set the :maxlength which is the maximum number of characters that the browser will allow the user to enter.
• submit_tag – creates an HTML submit button. It only has two parameters: the first sets the text inside the button (default is “Save changes”) and the second is an options hash for setting HTML attributes. Like with link_to, form_tag and text_field tag, this parameter has some special options:
  • :confirm – behaves the same way as the:confirm in link_to
  • :disabled – disables the button if set to true
  • :disabled_with – if this is set and the user clicks the button, the button will be disabled and the provided text (e.g. “Please wait…”) will replace the button’s original text while the form is being submitted. Useful for preventing the user from clicking the button twice on submit.

We only used one field in our form, the name field. Our plan is for this search module to return all records with a name that matches our submitted name. But enough talk, let’s see our newly coded form in action:

As you can see, the get method puts the query string in the URL. We could verify that the parameters were passed by looking at the web server logs.

With this we know that we could access the search parameter “name” through the params hash entry params[:name].

<%= form_tag search_products_path, :method => :get do %>
  <%= label_tag "name", "Search by product name:" %>
  <%= text_field_tag "name" %>
  <%= submit_tag"Search" %>
<% end %>

Filtering Results

So now we have the search parameter available in our controller. Let’s now add the code which will filter the results accordingly. Replace the line in the search action with:

  def search
    @products = Product.find_all_by_name(params[:name])
  end

Here we used a dynamic finder. In addition to providing accessors for each field in the database, Active Record also provides class methods for retrieving filtered for each field. These methods are in the form of:

• .find_by_xxxx() – returns a record whose field xxxx matches the provided argument. Like .find(), it throws an error if no record is found. (When you think about it, find equivalent to find_by_id)
• .find_all_by_xxxx() – returns an array of records whose field xxxx matches the provided argument.

Later we shall discuss a more flexible method for filtering, thewhere method.

The search function should work properly at this point. Try using the search form at http://localhost:3000/products to see if it works.

Finishing Touches to the View

Let’s make some minor changes to our search results screen to make it more functional.

<h1>Listing Products</h1>

<p>Displaying Products with name "<%= params[:name] %>"</p>

<table>
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Cost</th>
    <th>Stock</th>
  </tr>

<% @products.each do |product| %>
  <tr>
    <td><%= product.name %></td>
    <td><%= product.description %></td>
    <td><%= number_to_currency product.cost, :unit => 'PhP' %></td>
    <td><%= product.stock %></td>
    <td><%= link_to 'Show', product %></td>
  </tr>
<% end %>
</table>

<p><%= link_to "Back to original list", products_path %></p>

The first change displays the current search criteria, while the next change links back to the original list, basically resetting the filter.

Rails Applications Without Scaffold (part 3: Insert and Update)

Creating a Record

So far we’ve encountered tasks that require one controller action and one view as well as a task that required only one action with no views (delete). For next two tasks, creating and updating a record, we will need two actions and one view:

• one action to prepare the form
• one view to render the form to the user
• one action to process the submitted form. This action will simply redirect in case of success or re-render the view in case of an error.

The flow for creating records is slightly more complicated than the previous functions so let’s just discuss the flow as we go along.

Preparing the New Files

First step is to insert new actions into our controller. The pseudocode below explains the basic flow for this function:

  def new
    # create a dummy Product
  end
  
  def create
    # create a Product based on submitted form
    # save Product
    # if save is successful
    #   show new Product
    # else 
    #   go back to current page and display error
  end

Let’s also create a dummy app/views/products/new.html.erb so we could test the routing before we add the processing logic.

<h1>New Product</h1>

<p>form goes here</p>

Here are the new entries for our routes.rb:

AlingnenaApp::Application.routes.draw do
  resources :debts

  match 'products' => 'products#index', :via => :get, :as => 'products'
  match 'products' => 'products#create', :via => :post
  match 'products/new' => 'products#new', :via => :get, :as => 'new_product' 
  match 'products/search' => 'products#search', :via => :get, :as => 'search_products'
  match 'products/:id' => 'products#show', :via => :get, :as => 'product'
  match 'products/:id' => 'products#destroy', :via => :delete 
 
end

Try out the new screen by going to http://localhost:3000/products/new:

Making the Create Form

Here’s the rest of new.html.erb:

<h1>New Product</h1>
<%= form_for @product do |f| %>
  <div class="field">
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </div>
  <div class="field">
    <%= f.label :description %><br />
    <%= f.text_area :description %>
  </div>
  <div class="field">
    <%= f.label :cost %><br />
    <%= f.text_field :cost %>
  </div>
  <div class="field">
    <%= f.label :stock %><br />
    <%= f.text_field :stock %>
  </div>
  <div class="actions">
    <%= f.submit 'Create' %>
  </div>
<% end %>

<%= link_to 'Back', products_path %>

We’re using a different form helper here; before, we used form_tag in our search screen, while here we used form_for. The former is called a non-model form because it doesn’t use a model. On the other hand, form_for is a model form – it takes a model and uses it to populate the fields inside the form.

The syntax for form_for is as follows:

form_for(record_or_name_or_array, options = {}) do |f|
  ...
end 

The record_or_name_or_array parameter determines the model/s used in the form. As the name implies, it accepts a single or an array of Active Record objects and also accepts a name, a symbol or a string that refers to the instance variable where the Active Record is stored. The options argument can accept two options:

• :url – the URL where the form is supposed to be submitted to. Normally, the URL is derived from the model in the first argument but we can override that by using this option. The expected value for this option is the same expected values for link_to and redirect_to, namely, either a string, a hash, or an object (i.e. this option also uses url_for).
• :html – you can pass a hash of HTML attributes to this option

Inside the block are model form helper counterparts to the non-model form helpers we used in search. There are some noticeable differences, though:

• They use symbols for their first parameter. This signifies that they refer to a specific field in the model provided in the form_for call.
• They are prefixed by an “f.”. When the block is called by form_for, form_for passes an object that refers to the model of the form. When we prefix a form helper with the “f”, we say that the field is a member of the form. We can do away with the f prefix, but doing that would require us to tell the form helpers what model they should refer to. e.g.:

  1 {linenos=off,lang="erb"}
  2     <%= text_field(:products, :name) %>
  

You may notice that we haven’t initialized the @product instance variable yet. Let’s do just that in the new action:

  def new
    @product = Product.new
  end

Opening http://localhost:3000/products/new will give us a blank form.

Product.new is the constructor of the Product class. We can even define the fields at this point passing a hash of “field name – value” pairs. Try replacing Product.new with Product.new(:name => "dummy name"). You should see the name field in the form populated by “dummy name”.

Saving the New Record

When we click on submit, the contents of the form are submitted and Rails converts the form into a single hash parameter.

This hash is now part of the params hash and can be accessed directly like any hash entry. Here’s a visual representation of params:

Here we can see that we could access the value “Cola” via params[:product][:name] or the whole product hash via params[:product].

Now the only thing left to do is code the logic that we wrote in pseudocode, namely, to create a record based on the submitted form, save that record, then redirect the user based on the results of the save.

The first part can be done by using Product’s constructor

  def create
    @product = Product.new(params[:product])
    
    # save Product
    # if save is successful
    #   show new Product
    # else 
    #   go back to current page and display error
  end

Recall that the constructor accepts a hash and fills out the fields based on that hash. Passing params[:product] (which is a hash) creates a new Product object based on the submitted form.

The saving and redirection can be done via the following code:

  def create
    @product = Product.new(params[:product])

    if @product.save
      flash[:notice] = "Product has been successfully created."
      redirect_to @product
    else 
      render :action => "new"
    end
  end

Here we called save, an instance method that saves the record to the database. This method returns true if the record passes validation and false otherwise.

On a successful save in our code, the user is redirected to the “show product” page of the newly created Product record. Try using the new product form now.

(To display the success notice in the show product page, add the following line from app/views/products/index.html.erb to show.html.erb:)

<p id="notice"><%= flash[:notice] %></p>

If the save fails, it calls the render method to render the view of the new action. By rendering the view of the new action, the user is presented a form that contains the data that he submitted along with the error messages that comes along with it. This is the reason why we initialize the @product variable in the new action instead of initializing it directly at new.html.erb.

Unfortunately, we can’t see this in action because we haven’t set validation rules for Product yet.

if expression then
  ...
end 

if expression then ... end 

if expression [then]
  ...
elsif expression [then]
  ...
else
  ...
end

unless expression [then]
  ...
else
  ...
end

return true if x > max_value

error_count += 1 unless form.is_valid?

redirect_to @product, :notice => "Product has been successfully created."

<p id="notice"><%= flash[:notice] %></p>
<p id="notice"><%= notice %></p>

redirect_to @product, :flash => { :notice => "Product has been successfully created." }

Basic Validation

Let’s add some basic validation to our Product model. Add the following line to app/models/product.rb:

class Product < ActiveRecord::Base
  validates_presence_of(:name, :description)
end

This method call to validates_presence_of tells Rails to check whether the specified fields are present when the object undergoes validation. In other words, it defines the mandatory fields for the model.

We also add the following lines to new.html.erb to display the error messages:

<h1>New Product</h1>
<%= form_for @product do |f| %>
  <% if @product.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(@product.errors.count, "error") %> prohibited this product from
        being saved:</h2>
      <ul>
      <% @product.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>
  <div class="field">
    <%= f.label :name %><br />
...

Try submitting a blank new product form now.

You are redirected to new.html.erb along with messages detailing the errors in your form. As you may have guessed, the error messages at the top are the work of the f.error_messages call.

Before we end this part, add a link to the “new product” page in the “list products” page (i.e. index.html.erb):

...
</table>

<p><%= link_to "Create a new Product", new_product_path %></p>

We’re done with creating new product records and we only have one more function to code.

class Product < ActiveRecord::Base
  validates_presence_of :name, :description
end

Editing a Record

Editing a record is not that different from creating a record. We still have two controller actions sharing one single view which contains the form; we just don’t create the record from scratch this time.

Rails Conventions

Here are the conventions for editing records:

• the controller action that prepares the editing form should be named edit. The view displaying the empty form also follows (edit.html.erb)
• the URL to the form should be in the form /[plural model]/[id]/edit, so in the Product case, this should be /products/:id/edit. This RESTful URL tells us that we are doing an action to a particular product resource.
• the controller action that processes the submitted form should be named update.
• the URL to the form processing action is similar to the one we used in showing and destroying a record :PUT /products/:id.

Routes and View

Insert the following new entries in routes.rb:

AlingnenaApp::Application.routes.draw do
  resources :debts
  match 'products' => 'products#index', :via => :get, :as => 'products'
  match 'products' => 'products#create', :via => :post
  match 'products/new' => 'products#new', :via => :get, :as => 'new_product'
  match 'products/search' => 'products#search', :via => :get, :as => 'search_products'
  match 'products/:id' => 'products#show', :via => :get, :as => 'product'
  match 'products/:id' => 'products#destroy', :via => :delete
  match 'products/:id' => 'products#update', :via => :put
  match 'products/:id/edit' => 'products#edit', :via => :get, :as => 'edit_product'
end

Create the view file for edit, app/views/products/edit.html.erb:

<h1>Edit Product</h1>
<%= form_for @product do |f| %>
  <% if @product.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize @product.errors.count, "error" %> prohibited this product from
        being saved:</h2>
      <ul>
      <% @product.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <div class="field">
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </div>
  <div class="field">
    <%= f.label :description %><br />
    <%= f.text_area :description %>
  </div>
  <div class="field">
    <%= f.label :cost %><br />
    <%= f.text_field :cost %>
  </p>
  <div class="field">
    <%= f.label :stock %><br />
    <%= f.text_field :stock %>
  </div>
  <div class="actions">
    <%= f.submit 'Update' %>
  </div>
<% end %>

<%= link_to 'Show', @product %> |
<%= link_to 'Back', products_path %>

We did not need to change the declaration for form_for, it already checks the model and determines which route to use based on conventions. If the model is new (i.e. create), it will use the products_path. Otherwise (i.e. update), it will use product_path.

For convenience, add the following links to show.html.erb

...
</p>

<%= link_to 'Edit this record', edit_product_path(@product) %> <br />
<%= link_to 'Delete this record', @product,
  :confirm => 'Are you sure?', :method => :delete %> <br />
<%= link_to 'Back to List of Products', products_path %>

and index.html.erb

...
  <% @products.each do |product| %>
    <tr>
      <td><%= product.name %></td>
      <td><%= product.description %></td>
      <td><%= number_to_currency product.cost, :unit => 'PhP' %></td>
      <td><%= product.stock %></td>
      <td><%= link_to 'Show', product_path(product.id) %></td>
      <td><%= link_to 'Edit', edit_product_path(product) %></td>
    </tr>
  <% end %>
...

New Controller Actions

Add the following actions to app/controllers/products_controller.rb:

  def edit
    @product = Product.find(params[:id])
  end

  def update
    @product = Product.find(params[:id])
    if @product.update_attributes(params[:product])
      redirect_to @product, :notice => 'Product was successfully updated.' 
    else
      render :action => "edit" 
    end
  end

Since we’re already familiar with how records are created, this code should be easy to understand. Instead of creating records with Product.new, we use Product.find to retrieve the record from the database. The @product.update_attributes() method is similar to save; it first updates the fields based on the hash then validates and saves the object.

And that’s it; we finally created a full table maintenance program without using rails generate scaffold. We also learned almost everything that goes on behind the scaffold generated code.

There are still a bunch of things we add to our maintenance program. We’ll spend the next chapter on those things in order to get them out of the way before the next lesson.

Rails Applications Without Scaffold (part 4: RESTFul Routes, Callbacks, Filters, and Layout)

In this chapter, we will be discussing new Rails features from the Model, Controller, and the View that can make our Product maintenance program better.

Reduce Route Entries with Resource-Based Routing

Creating a new route entry for typical routes sort of defeats the purpose of following Convention over Configuration. Fortunately, most of the routing in this program was only done for educational purposes; there is a shortcut for telling Rails that a certain resource follows the REST conventions.

AlingnenaApp::Application.routes.draw do
  resources :debts
  match 'products/search' => 'products#search', :via => :get, :as => 'search_products'
  resources :products
  
end

Using resources :products adds the following routes and helpers to the system:

You can define other routes under the resource by using the collection and member blocks. Use collection for routes that affect the entire collection. In our case, we can set the products search as a collection route:

AlingnenaApp::Application.routes.draw do
  resources :debts
  match 'products/search' => 'products#search', :via => :get, :as => 'search_products'
  resources :products do
    collection do
      get 'search'
    end
  end
  
end

Doing this will also create search_products_xxxx route helpers (we manually set that named route before).

For actions that only affect one resource, use the member option. For example, if we want to add a “suspend” action for suspending a specific product (i.e. PUT /products/:id/suspend), we can use:

AlingnenaApp::Application.routes.draw do
  resources :debts
  resources :products do 
    collection do
      get 'search'
    end
    member do
      put 'suspend'
    end
  end
 
end

The other options for resource-based routing will be discussed in a later chapter.

Perform Actions While A Model is Saved using Callbacks

Aling Nena has dozens, if not hundreds, of different products in stock. If she would encode all of them, she might not have time to enter detailed descriptions for each item. To help her in this task, we could just set the description to be the same as the product’s name every time she doesn’t enter a description.

At first glance, the solution to this problem would be in the controller, say, something like this:

 def create
    @product = Product.new(params[:product])

    if @product.description.blank?
      @product.description = @product.name
    end
...

However, if you would recall our discussion in MVC, most of the business logic must be placed inside the model instead of the controller. So how do we set the description without changing the controller?

For this, we need to understand how to use callbacks.

Callbacks

Callbacks are methods called by an Active Record object before and after the object is inserted, updated, or deleted from the database. Here is the list of callbacks performed in each of these operations:

Based on this table, the before_validation callback is called before the validation of both record creation and update. After that, the before_validation_on_create and before_validation_on_update are called in creation and update, respectively.

Registering Callbacks

Registering callbacks is similar to setting validations. Instead of providing fields, however, we provide symbols referring to method names.

# app/models/product.rb

class Product < ActiveRecord::Base
  validates_presence_of :name, :description

  before_validation :assign_default_description

  private

    def assign_default_description
      if description.blank?
        self.description = name
      end
    end
end

Here we set the description field of the record before the record is validated (thus preventing an error in description validation).

Note that we set the callback method to be private. This prevents the method from being called outside the object. Another thing to note is the use of self to denote that we are modifying the instance attribute; if we didn’t use self.description, Ruby will think we are simply setting a local variable description.

object == nil 

object.nil? 

Limiting User Access with Filters and Authentication

Aling Nena wants her customers to see the list of available products in her store. However, she doesn’t want them to create and edit the products, or worse, delete the products. In short, she wants to add an authentication mechanism in her site.

Controller Filters

Authentication is like validation; we want to validate whether the user has permission to do something in our application. Unlike validation, it is not done in the Model level but in the Controller level, with the help of the controller filters.

Controller filters are more like callbacks than validations. They are methods that we define to be executed before actions (using before_filter) or after actions (using after_filter). The syntax is also similar:

# app/controllers/products_controller.rb

class ProductsController < ApplicationController
  before_filter :check_if_aling_nena

  ...
  private

   def check_if_aling_nena
     #checking here
   end
end

In this case, the method check_if_aling_nena is called before every action in the Products controller. If we want to limit the actions where the filter is applied, we can use the :only option.

before_filter :check_if_aling_nena, :only => [:new, :create, :edit, :update, :destroy] 

It might make sense to use the :except option here, though.

before_filter :check_if_aling_nena, :except => [:index, :show, :search] 

One important thing about before_filter methods is that the processing will not continue to the action if the method renders or redirects. Here’s one way to test our new filter, by kicking everyone back to the list products page regardless of who they are:

   def check_if_aling_nena
     redirect_to products_path, :notice => "You must be Aling Nena to access this page."
   end

(You may want to change that flash message to :alert, just don’t forget to add the code to index that would display the message.)

HTTP Authentication

Having verified that the filter works, let’s now add the authentication.

Rails has built in methods that make applying basic HTTP authentication easy. Here’s the code to apply that authentication to our Product maintenance program (you can change the username and password as you like):

   def check_if_aling_nena
     authenticate_or_request_with_http_basic("Products Realm") do |username, password|
       username == "admin" and password == "sTr0NG_p4$swOrD"
     end
   end

You should see browser-specific pop-up prompting you for credentials:

Entering the credentials will let you proceed to the pages. Since HTTP authentication is supported by all browsers, the server knows if you already provided your credentials so you don’t have to re-enter it again when you enter the other actions in the program.

Pressing Cancel will redirect you to an error page:

HTTP Authentication is the most basic of all authentications available to Rails. For larger applications with many users, you’re better off with full-fledged authentication solutions like the Authlogic or Devise gems.

Layouts and Rendering in the View

Asset Tags

Static files in our web application are stored in the public folder. Since this folder is mapped directly to the application root, going to http://locahost:3000/ will open public/index.html.

By convention, stylesheets, images, and JavaScript files are stored in the public/stylesheets, public/images, and public/javascripts folder, respectively. Rails provides view helpers called asset tags for linking to these files.

We can use stylesheet_link_tag to link to CSS files under the public/stylesheets folder. The syntax is as follows:

stylesheet_link_tag( *sources, options = {} )

You can pass one or more stylesheets to the method:

<%= stylesheet_link_tag("main") %>

<%= stylesheet_link_tag("sidebar", "admin") %>

The code above creates the following links:

<link href="/stylesheets/main.css" media="screen" rel="stylesheet" type="text/css" />

<link href="/stylesheets/sidebar.css" media="screen" rel="stylesheet" type="text/css" />
<link href="/stylesheets/admin.css" media="screen" rel="stylesheet" type="text/css" />

You can also use relative paths:

<%= stylesheet_link_tag("red/main") %>

<link href="/stylesheets/red/main.css" media="screen" rel="stylesheet" type="text/css" />

You can also use absolute or external paths:

<%= stylesheet_link_tag("http://example.com/main") %>

<link href="http://example.com/main.css" media="screen" rel="stylesheet" type="text/css" />

The :all option creates links to all of the CSS files under public/stylesheets. Adding a :recursive => true option creates links for all CSS files in all subfolders of public/stylesheets.

<%= stylesheet_link_tag(:all) %>

<%= stylesheet_link_tag(:all, {:recursive => true}) %>

You can also override the link attributes by adding them as options. For example, you can change the media from screen to print using the following:

<%= stylesheet_link_tag("main", { :media => "print"}) %>

The asset tag for JavaScript is javascript_include_tag and it behaves the same way as the stylesheet_link_tag:

<%= javascript_include_tag(main) %>

=> <script type="text/javascript" src="/public/javascripts/main.js"></script>

The :all and :recursive option also work with javascript_include_tag.

For images, the asset tag is image_tag. The basic use is similar to the two previous asset tags. By default it appends .png to the file name if the extension isn’t specified.

<%= image_tag "banner" %>
=> <img src="/public/images/banner.png" />

<%= image_tag "profile.jpg" %>
=> <img src="/public/images/profile.jpg" />

In addition to the HTML attributes that you can set in the options hash parameter, image_tag has the following special options:

• :alt– If no alt text is given, the file name part of the source is used (capitalized and without the extension)
• :size – Supplied as “{Width}x{Height}”, so “30x45” becomes width=”30” and height=”45”. :size will be ignored if the value is not in the correct format.
• :mouseover – Set an alternate image to be used when the onmouseover event is fired, and sets the original image to be replaced onmouseout. This can be used to implement an easy image toggle that fires on onmouseover.

Layouts

We now know how to link to CSS files in our pages but having to add <%= stylesheet_link_tag "scaffold" %> (the CSS used in Debts) to all of our pages can be a hassle, not to mention that it violates the DRY (Don’t Repeat Yourself) principle that we’ve been following as we applied Convention over Configuration to our program. There must be a way for us to apply HTML code to all of our pages.

Thankfully, Rails already provides a way to do that through layouts.

Layouts, as you may have guessed, provide the general layout for our views. Rails combines the view and the layout when rendering the page to the user. An example of a layout is the default layout generated when we created our application, app/views/layouts/application.html.erb:

<!DOCTYPE html>
<html>
<head>
  <title>AlingnenaApp</title>
  <%= stylesheet_link_tag :all %>
  <%= javascript_include_tag :defaults %>
  <%= csrf_meta_tag %>
</head>
<body>

<%= yield %>

</body>
</html>

The yield section defines where the view will be inserted upon rendering. You can also use multiple yielding regions:

<html>
  <head>
  <%= yield :head %>
  </head>
  <body>
  <%= yield %>
  </body>
</html>

To render content in a named yield, you use the content_for method:

<% content_for :head do %>
  <title>A simple page</title>
<% end %>

<p>Hello, Rails!</p>

This would result in:

<html>
  <head>
  <title>A simple page</title>
  </head>
  <body>
  <p>Hello, Rails!</p>
  </body>
</html>

By default, Rails checks the app/views/layouts directory for a layout that matches the name of the controller. If the layout isn’t found, Rails will try app/views/layouts/application.html.erb.

There are two other ways to define layouts. First is through the controller:

class ProductsController < ApplicationController
  before_filter :check_if_aling_nena, :except => [:index, :show, :search]

  layout "main"
... 

This will apply app/views/layouts/main.html.erb to all actions in Products.

Layouts are shared downwards in the hierarchy, so applying

class ApplicationController < ActionController::Base
  protect_from_forgery

  layout "main"
... 

will set the layout of every controller to app/views/layouts/main.html.erb because all controllers (at least the ones generated by rails generate controller and scaffold) are subclasses of `ApplicationController.

Another way of setting the layout is through the render method. Before, the only option we discussed for render is :action, so now we introduce a new option, :layout, which lets you define the layout of a rendered view:

render :layout => "main", :action => "new" 

You can also remove a layout by setting it to `false. For example:

render :layout => false, :action => "new" 

When multiple layouts are applied to a view, more specific layouts always override more general ones. For example:

class ProductsController < ApplicationController
  layout "main"
  def show 
    @product = Product.find(params[:id])
    render :layout => false
  end
...

No layout is rendered for the show action above. (Recall that the :action option is automatically set by Rails according to the action name if it’s not defined.)

Partial Templates

When you look at app/views/products/new.html.erb and app/views/products/edit.html.erb, you will notice that both share almost the same code for the form. We can eliminate this redundancy by using partial templates, better known as partials.

Partials are fragments of pages that can be called by other pages. We use the render method to tell rails to render a partial inside a view. For example, if we call the following inside app/views/products/new.html.erb:

<%= render({:partial =>'form'})%>

The call will insert the contents of app/views/products/_form.html.erb at that line inside the view.

We can use the :locals option to pass local variables to the partial. For example, we can eliminate the redundancy between new and edit by modifying the views:

# new.html.erb

<h1>New Product</h1>

<%= render({:partial => "form", 
            :locals => { :product => @product, :button_label => "Create" } }) %>

<%= link_to 'Back', products_path %>

# edit.html.erb

<h1>Edit Product</h1>

<%= render({:partial => "form",
            :locals => { :product => @product, :button_label => "Update" } }) %>

<%= link_to 'Show Details', @product %> |
<%= link_to 'Back to List', products_path %>

and creating a new partial app/views/products/_form.html.erb:

<%= form_for product do |f| %>
  <% if product.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize product.errors.count, "error" %> prohibited this product from
        being saved:</h2>
      <ul>
      <% product.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <div class="field">
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </div>
  <div class="field">
    <%= f.label :description %><br />
    <%= f.text_area :description %>
  </div>
  <div class="field">
    <%= f.label :cost %><br />
    <%= f.text_field :cost %>
  </div>
  <div class="field">
    <%= f.label :stock %><br />
    <%= f.text_field :stock %>
  </div>
  <div class="actions">
    <%= f.submit button_label %>
  </div>
<% end %>

In this case, the product local variable was derived from the @product instance variables, while the button_label was supplied in the hash.

All partials have a local variable with the same name as the partial and you can pass an object to this by using the :object option. In other words, suppose we make a copy of the _form partial at _product_form.html.erb, and we replace the first line with:

<%= form_for product_form do |f| %>

We would be able to do this in edit.html.erb:

<%= render({:partial => "product_form",
            :object => @product,
            :locals => { :button_label => "Update" } }) %>

The instance variable is placed inside the product_form variable.

We can also use partials to render a collection of objects using the :collection option. For instance, we can replace the iteration inside app/views/products/index.html.erb with the following:

...
  <tr>
    <th>Name</th>
    <th>Description</th>
    <th>Cost</th>
    <th>Stock</th>
  </tr>
  <%= render({ :partial => "item", :collection => @products }) %>
</table>
...

And create a new partial, _item.html.erb:

    <tr>
      <td><%= item.name %></td>
      <td><%= item.description %></td>
      <td><%= number_to_currency item.cost, :unit => 'PhP' %></td>
      <td><%= item.stock %></td>
      <td><%= link_to 'Show', product_path(item.id) %></td>
      <td><%= link_to 'Edit', edit_product_path(item) %></td>
    </tr>

The page would still display as it was originally displayed. Each item in the array is placed in a local variable that shares the same name as the partial. In this case, the partial and variable name is item.

We can even define a spacer template for the collection:

<%= render({ :partial => "item", :collection => @products, :spacer_template => "hr" }) %>

Here’s a sample _hr.html.erb:

<tr><td colspan="7"><hr /></td></tr>

There is also a shorthand for partials. Assuming @product a single Product object the following code:

<%= render({ :partial => @product }) %>

will render _product.html.erb and pass @product as the value of the local variable product. Similarly, assuming @products is a collection of Product objects, the following code:

<%= render({ :partial => @products }) %>

will render the partial _product.html.erb for each Product object inside the collection, passing the object to the local variable product.

Using a collection with different object types can produce polymorphic results. For example, if employee1 and employee2 are Employee objects, while customer1 and customer2 are Customer objects, the following call:

<%= render({ :partial => [customer1, employee1, customer2, employee2] }) %>

will call the following partials, either _customer.html.erb

<p>Name: <%= customer.name %></p>

or _employee.html.erb:

<p>Name: <%= employee.name %></p>

<%= render :partial => "form", 
           :locals => { :product => @product, :button_label => "Update" } %>
<%= render :partial => "form", :product => @product, :button_label => "Update" %>

<%= render({ :partial => @products }) %>
<%= render @products %>

Associations

When you’re working with RDBMSs, you’re bound to encounter cases where you have to handle relationships between tables. One-to-many relationships are common, though you might see many-to-many and one-to-one relationships from time to time.

Does Rails support these relationships?

No and yes.

Rails does not support the various relationship implementations between database vendors. You will have to tweak your migrations to call specific DDL commands in order to set them up (this is outside the scope of this training course).

Rails, however, has its own database-agnostic way of handling entity relationships. In this chapter, we will discuss how to these various relationships are coded in Rails.

Migrations for Associations

If you would recall in our previous lesson, by default all tables in a Rails application use “id”, an auto-incrementing integer field, as their primary key. In the context of associations, Rails uses this convention to link tables in a system.

When generating the migration for a foreign key reference field, you can specify the field normally e.g.

$ rails generate migration Employee name:string department_id:integer 

Or you can make the abstraction clearer by using the :references data type:

$ rails generate migration Employee name:string department:references 

This migration will still generate the same field as the previous migration. Note the lack of _id in the :references argument.

Defining Associations in Models

Had you used rails generate scaffold or rails generate model instead of migration, you will notice that the model generated has a belongs_to call:

class Employee < ActiveRecord::Base
  belongs_to :department
end 

Again, another human-readable declaration in Rails: it simply tells Active Record that each Employee record belongs to a Department record.

belongs_to

For every belongs_to call inside the model, Active Record generates some instance methods for the class. In the Employee-Department case, these methods are

• employee.department – returns the Department object associated to the Employee. This is cached so if you want to reload the list, just passtrue to the method. Can also be used to assign a Department to the Employee e.g. employee.department = some_department
• employee.build_department(attribute_hash) – basically a shorthand for employee.department = Department.new(attribute_hash). Also returns the newly created Department.
• employee.create_department(attribute_hash) – same as build_department, the only difference is the new object is saved (assuming it passes validations, of course).

Even with these methods, using the department_id for defining associations is still valid. The following will work:

department = Department.find_by_name("Accounting") 
employee.department_id = department.id 

but it’s still better to use an approach with a clearer abstraction:

employee.department = Department.find_by_name("Accounting") 

not to mention coding the build_xxxx and create_xxxx methods manually will take at least 2 more lines of code than just calling those methods.

One-to-One Relationships

With the belong_to declaration in one model, we can define the nature of the association in the target table. Let’s start with the one-to-one association.

For this tutorial, we’re going to expand Aling Nena’s system by adding a Purchase entity whose records refer to a single purchase of items from a supplier. We’re going to have an Invoice record for each Purchase, and this one-to-one relationship will be the basis of this tutorial.

First, let’s setup the Purchase and Invoice entities with scaffold scripts:

$ rails generate scaffold purchase description:text delivered_at:date
$ rails generate scaffold invoice purchase:references reference_number:string
$ rake db:migrate

This should make working maintenance programs for each entity. When you look at the new and edit views of the Invoice program, however, you will see that it uses a text_field for the purchase. This is inappropriate: not only does it force the user to know the Purchase while editing the field, it also won’t work because the data types don’t match (text_field is String, while the purchase field requires a Purchase).

Drop Down List

A better approach would be to provide a drop-down field containing a list of available Purchases. The form helper for drop-down lists is collection_select

collection_select(object, field_name, collection, value_method, text_method, options = {},
                  html_options = {}) 
# or the form_for shortcut
f.collection_select(field_name, collection, value_method, text_method, options = {}, 
                    html_options = {})

The object, field_name, and options field are just the same as in our basic input field text_field, with the options separated from the html_options.

The collection is a list of items where the value and the text are derived from, while the value_method and text_method determines the names of the methods to call for the value and text. For example, we have the following list of Purchases:

Replacing the purchase field in app/views/invoices/_form.html.erb to

...
    </div>
  <% end %>
  <div class="field">
    <%= f.label :purchase %><br />
    <%= f.text_field :purchase %>
    <%= f.label :purchase_id, "Purchase" %><br />
    <%= f.collection_select :purchase_id, Purchase.all, :id, :description %>
  </div>
  <div class="field">
    <%= f.label :reference_number %><br />
    <%= f.text_field :reference_number %>
  </div>
...

will result in the following HTML code:

...  
  <div class="field">
    <label for="invoice_purchase_id">Purchase</label><br />
    <select id="invoice_purchase_id" name="invoice[purchase_id]">
      <option value="1">Cola delivery</option>
      <option value="2">Soap delivery</option>
      <option value="3">Candy delivery</option>
    </select>
  </div>
...

There are three available options in collection_select:

• :include_blank – adds a blank entry at the top of the list. Can be the text of the entry (e.g. “none”) or true (which will just put a blank entry).
• :prompt – just like include_blank, but has a different purpose: to prompt the user to select one item in the list. When set to true, the text used is “Please select”. Setting this option will not add validation for checking if the user chose a value from the list. Setting this option along with :include_blank will add 2 blank list entries in the list, one for each call with the prompt on top.
• :disabled – contains a list of items from collection that should be disabled from the list. In the case of collection_select, we can use a Proc to determine which should be disabled. For example, to disable all Purchases that would be delivered in the future, we can set:

<%= f.collection_select :purchase_id, Purchase.all, :id, :description, :prompt => true, 
  :disabled => lambda { |purchase| purchase.delivered_at > Date.today } %>

Custom Helpers

After creating the Invoice for the “Cola delivery”, we see a problem in the Show Invoice page:

What is displayed is the internal representation of the Purchase object. Sure, we can remedy this by replacing the code with:

<p>
  <b>Purchase:</b>
  <%= @invoice.purchase %>
  <%= @invoice.purchase.description %>
</p>

But what if we had created an Invoice without a Purchase?

We get Ruby’s equivalent to a Null Pointer Exception.

There are some ways to remedy this problem. The most obvious would be to make the field mandatory through validations. But for entities that allow that foreign key field to be empty, we need to directly address the problem.

One way would be to add a special method inside the model. For example:

class Invoice < ActiveRecord::Base
  belongs_to :purchase

  def display_purchase
    return purchase.description unless purchase.nil?
    "(no Purchase set)"
  end
end

Then just call @invoice.display_purchase from the view. This approach is legal and is actually the preferred approach For educational purposes, however, let’s move the logic to the view instead:

<p>
  <b>Purchase:</b>
  <% unless @invoice.purchase.nil? %>
    <%= @invoice.purchase.description %>
  <% else %>
    (no Purchase set)
  <% end %>
</p>

Our problem this time is that we’re adding 5 lines of processing code to our view for a simple task. If we do this a lot, our view would look cluttered and may bring back bad memories of old JSP, ASP, PHP code from older developers. We can take out this code from our views through the helper files.

The helper files are located at the app/helpers folder. These are modules where you can add methods that you would use in your views. One helper is created per controller if you generated them throughrails generate controller or scaffold. We can move our logic from the view into the helper by adding the following lines to app/helpers/invoices_helper.rb:

module InvoicesHelper
  def display_purchase(invoice)
    unless invoice.purchase.nil?
      invoice.purchase.description
    else
      "(no Purchase set)"
    end
  end
end

and just call the helper in our view:

<p>
  <b>Purchase:</b>
  <%= display_purchase(@invoice) %>
</p>

Due to the “helper :all” call in ApplicationController, all helper methods from all helpers are available to all views. The file scheme used is just for developers to classify the helpers according to the program they are used.

Helpers are usually used for generating markups. For instance, we want to have the Purchase field to have a link to the original purchase, we can use:

module InvoicesHelper
  def display_purchase(invoice)
    unless invoice.purchase.nil?
      link_to invoice.purchase.description, invoice.purchase
    else
      "(no Purchase set)"
    end
  end
end

You can’t do this inside the model, and this gives helpers an advantage over the model approach.

has_one

We’ve already associated Invoice with Purchase but not the other way around. In order for us to be able to call methods like @purchase.invoice, we must first declare the association in the Purchase model. Given that we’re using a one-to-one relationship, the association declaration will be:

class Purchase < ActiveRecord::Base
  has_one :invoice
end

With the has_one method declared, we can now call the following methods in Purchase:

• purchase.invoice, purchase.invoice=
• purchase.build_invoice, purchase.create_invoice

Yes, these are the same methods as the ones in the belong_to model.

You can provide options in the :has_one declaration. Here are a few:

• :dependent – provides the behavior when this model is deleted i.e. cascading delete options. Setting it to :nullify simply sets the foreign key reference in the other entity to NULL. Using :destroy will call the :destroy of the other entity, while using :delete will simply delete the related record via SQL.
• :validate – when set to true, validates the associated object upon save of this object. By default this is false.

Nested Routes and Singular Resources

One problem with our current Purchase-Invoice scheme is that you could assign one Purchase to two Invoices.

Calling @purchase.invoice on this will return only the first related Invoice.

The root cause of this problem is that we’re creating Invoices outside the context of the Purchase. Wouldn’t it make more sense to be able to go to http://localhost:3000/purchases/1/invoice/new to create the invoice for the first Purchase that what we’re currently doing right now?

We can do this with the help of 2 new routing concepts: the singular resource and nested resources.

The singular resource just like our typicalresources call, but instead of dealing with multiple records, it deals with only one object. For example, adding the singular resource route:

resource :platform 

assumes that we only have one Platform entity for the entire system (note we used resource instead of resources). The generated routes in this instance is:

To use this in the Purchase-Invoice relationship, we’ll have to set the Invoice as a singleton child of each Purchase entity by nesting aresource call under the resources call:

AlingnenaApp::Application.routes.draw do
  resources :purchases do
    resource :invoice
  end 
  resources :debts
  resources :products do
    collection do
      get 'search'
    end
  end
end

This will create the following additional routes:

We have to change the logic of our Invoice program to handle these changes. First, the controller:

class InvoicesController < ApplicationController
  def show
    # we'll integrate the Invoice details in the Show Purchase screen
    redirect_to purchase_path(params[:purchase_id])
  end

  def new
    @purchase = Purchase.find(params[:purchase_id])
    @invoice = @purchase.build_invoice
  end

  def edit
    @purchase = Purchase.find(params[:purchase_id])
    @invoice = @purchase.invoice
  end

  def create
    @purchase = Purchase.find(params[:purchase_id])
    @invoice = @purchase.build_invoice(params[:invoice])
    if @invoice.save
      redirect_to @purchase, :notice => 'Invoice was successfully created.'
    else
      render :action => "new"
    end
  end

  def update
    @purchase = Purchase.find(params[:purchase_id])
    @invoice = @purchase.invoice
    if @invoice.update_attributes(params[:invoice])
      redirect_to @purchase, :notice => 'Invoice was successfully updated.'
    else
      render :action => "edit"
    end
  end

  def destroy
    @purchase = Purchase.find(params[:purchase_id])
    @invoice = @purchase.invoice
    @invoice.destroy
    redirect_to @purchase
  end
end

In case you’ve forgotten how routes work, the :purchase_id parameter is derived from the URL.

Here’s the changes we’ll need for the views. Let’s modify Invoice’s views:

# app/views/invoices/new.html.erb

<h1>New Invoice</h1>

<%= render 'form', :purchase => @purchase, :invoice => @invoice  %>

<%= link_to 'Back', invoices_path %>

# app/views/invoices/edit.html.erb

<h1>Editing Invoice</h1>

<%= render 'form', :purchase => @purchase, :invoice => @invoice %>

<%= link_to 'Show', @invoice %> |
<%= link_to 'Back', invoices_path %>

# app/views/invoices/_form.html.erb

<%= form_for(invoice, :url => purchase_invoice_path(purchase)) do |f| %>
  <% if invoice.errors.any? %>
    <div id="error_explanation">
      <h2><%= pluralize(invoice.errors.count, "error") %> prohibited this invoice 
        from being saved:</h2>
      <ul>
      <% invoice.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>

  <p>
    <label>Purchase</label><br />
    <%= purchase.description %>
  </p>
  <p>
    <%= f.label :reference_number %><br />
    <%= f.text_field :reference_number %>
  </p>
  <p>
    <%= f.submit %>
  </p>
<% end %>

<%= link_to 'Back', purchase %>

Here’s Purchase’s app/views/purchases/show.html.erb:

<h1>Purchase Details</h1>
<p>
  <b>Description:</b>
  <%= @purchase.description %>
</p>
<p>
  <b>Delivered at:</b>
  <%= @purchase.delivered_at %>
</p>

<% display_invoice @purchase %>

<%= link_to 'Edit', edit_purchase_path(@purchase) %> |
<%= link_to 'Back', purchases_path %>

We used a scriptlet instead of an expression so that we could use theconcat method (similar to PHP’s print or Servlets’ out.println) in our helper to add multiple elements in the view. Here’s the helper method:

# app/helpers/purchases_helper.rb

module PurchasesHelper
  def display_invoice(purchase)
    unless purchase.invoice.nil?
      concat(raw "<p><b>Invoice Reference Number:</b>\n")
      concat(link_to @purchase.invoice.reference_number,
               edit_purchase_invoice_path(@purchase))
      concat(raw "</p>")
      concat(raw "<p>")
      concat(link_to "Delete Invoice", purchase_invoice_path(@purchase),
              :confirm => "Are you sure?", :method => :delete)
      concat(raw "</p>")
    else
      concat(raw "<p>")
      concat(link_to "Create Invoice", new_purchase_invoice_path(@purchase))
      concat(raw "</p>")
    end
  end
end