Today, we’ll follow modified steps, as recommended by Matt Wynne who suggested refactoring to remove duplication as an extremely important step:

  1. Describe a feature
  2. Execute the feature and Watch it fail
  3. Write the code to make it pass
  4. Refactor
  5. Go to step 2

Also, since we’re using the generate scaffold command, we should remove unused code when refactoring as suggested in the original Four Days on Rails tutorial. I’ll also be using RCov to look at how much the feature description covers the code. I think this is a helpful way of digging into what the scaffold command actually did. This tutorial picks up where day 3 finished. You can skip day 1 or 2, if you already have installed Ruby on Rails and know a little bit about it.

Today we will:

  1. Install RCov
  2. Look at Code Coverage
  3. Write more scenarios
    1. Create
    2. Edit
    3. Delete
  4. Refactor to remove duplication
  5. Review what we learned

 


 

Install RCov

Elaborating slightly on the nice instructions on the cucumber wiki, Aslak recommends that you use spicycode’s RCov instead of the ‘official’ one, “as it currently segfaults too much for most people’s taste.”

gem sources -a http://gems.github.com
gem uninstall rcov
gem install spicycode-rcov

Second, you’ll need to open up the cucumber generated task file and set the rcov config option (add one line in bold).

in todolist/lib/tasks/cucumber.rake


$:.unshift(RAILS_ROOT + '/vendor/plugins/cucumber/lib')
require 'cucumber/rake/task'
Cucumber::Rake::Task.new(:features) do |t|
  t.cucumber_opts = "--format pretty"
  t.rcov = true
end
task :features => 'db:test:prepare'

Look at Code Coverage

Now when you run:

rake features

And you point your browser at: http://localhost/todolist/coverage/

You’ll see:

We can see that we don’t have complete coverage in two files: webrat.rb and tasks_controller.rb The first doesn’t matter, since it is part of the test framework (in fact there ought to be some way to exclude that), but we need to be concerned that half of our generated controller code is untested. By clicking on the filename, we can see the detailed coverage where the lines of code that are not covered are highlighted in red:

It is unsurprising that we’re covering just 40% of this file, since we’ve written just a single of scenario so far.

More Scenarios

Let’s look at what isn’t getting covered.

  • show
  • new
  • edit
  • update (called from edit)
  • destroy
  • create (called from new)

Create

To create a task, we can leverage quite a bit of webrat, plus a step we wrote before. Add the following scenario to the feature file:

in features/tasklist.feature

Scenario: Add a Task
When I go to the tasks page
When I follow "New task"
When I fill in "description" with "go shopping"
And I press "Create"
Then I should see "Task was successfully created."
And I should see "go shopping"

then run

rake features

You’ll see that all of the new steps that I just wrote for the “add a Task” scenario magically worked. What just happened? You can see from the output of “rake features” that the first step was already defined in tasklist_steps.rb (see day 3), but each of the others is defined in webrat_steps.rb. With a little practice you’ll learn the webrat lingo, and it’ll save you a bunch of time. Pretty cool, huh?

Now if we go back to look at our code coverage (http://localhost/todolist/coverage/), the tasks_controller.rb coverage is at 64.7%.

Clicking on the file, we can see the lines of code that are now tested. We’ve covered new and half of create. (Not quite sure what would cause that error condition, but we’ll move on for now.)

Edit

Now we’ll do some behavior-driven development, since the auto-generated task list and edit workflow isn’t exactly what I wanted. This is what I see after adding the “go shopping” task manually:

I don’t really need the “show” link (since my task only has its description as data and that’s shown in the list and since I’m removing that, I can just make the description itself as a link. So I want to add two scenarios to support my intended edit behavior:

  • Clicking on the description link allows edit
  • After Editing I return to the task list
Scenario: Clicking on description link allows edit
Given that I have created a task "go shopping"
When I go to the tasks page
When I follow "Go Shopping"
Then I should see "Editing Task"

As expected, the new scenario fails. Time to write the code! The list of tasks can be found in app/views/tasks/index.html.erb

As you can see that I’ve modified line 10 to link the description to the edit task page. Note that (h task.description) needs to be enclosed in parens. We want to keep the h, just to make sure that the description is properly escaped, in case it has special characters like ‘<'. I also removed show and edit links. Now, when I run 'rake features' all of my steps pass. Yay!

But wait! I still have the “show” method in my controller. What’s up with that? If I look at my coverage report, it shows that it is being called. In my controller, both create and update redirect to @task (which is the “show” page), like I did in day 2, I’ll modify those to redirect to index instead.

in app/controllers/task_controller.rb

change:

format.html { redirect_to(@task) }

to:

format.html { redirect_to :action => "index" }

and remove the show method

Rerun ‘rake features’ just to make sure all is good. And you can now see that the tasks_controller code coverage is at 62%. We’re calling edit, but not yet update… on to the next scenario.

Scenario: After Editing I return to the task list
Given that I have created a task "go shopping"
When I go to the tasks page
When I follow "Go Shopping"
And I fill in "description" with "buy bagels"
And I press "Update"
Then I should see "Task was successfully updated."
And I should see "Listing tasks"
And I should see "buy bagels"

When I run “rake features” the scenario passes. (Yay!) I don’t know how to hit the error condition in update either, but I’ll leave that for another day.

Delete

I left delete for last since it is a bit trickier. With the design of the app, there is a “destroy” link for each task in the list, so I have to figure out which one to click.

I found this handy step definition in an example by Aslak:

When /^I delete the (d+)(?:st|nd|rd|th) lorry$/ do |pos|
visit lorries_url
within("table > tr:nth-child(#{pos.to_i+1})") do
click_link "Destroy"
end
end

When I first looked at that I thought > tr:nth-child was some wild new Ruby syntax, but the kind folk on the RSpec list answered my question by pointing me to the CSS selector doc. I had forgotten that > was a CSS selector since I had never actually used that selector before. That hint combined with a previous thread and some digging around to brush up my Ruby and Rail skills led me to a solution. Here is my scenario for delete:

Scenario: Delete a Task
Given that I have created a task "task 1"
When I go to the tasks page
And I click "delete" for "task 1"
Then I should see "Listing tasks"
And I should not see "task 1"

To make this work, I can define a unique DOM id for each of my table row, then I can find the id for “task 1” and then click the link inside that table row.

1) Define a unique DOM id for each table row

In app/views/tasks/index.html.erb, we have some Ruby code which iterates through the list of tasks (@tasks) and for each ‘task’ there is a table row. To add a unique id for the table row, I insert a snippet of ruby code within <% … %> which evaluates to a unique string. In this case I use the string “task” plus to id of the task itself, generating task4, task5 or whatever.


<% for task in @tasks %>
  <tr id="<%="task"+task.id.to_s%>">

2) Find the id for “task 1”

Given the description of a task, I need to find its id. In the ActiveRecord::Base API docs, it describes some handy syntax for finding by attribute value. “Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects by simple queries without turning to SQL. They work by appending the name of an attribute to find_by_, find_last_by_, or find_all_by_.” Since the attribute I have is “description,” I can call

task = Task.find_by_description(desc)

to get the task object where the description attribute matches the given parameter.

3) Click the link inside the table row

Putting it all together I can create a step definition like this:

When /^I click "delete" for "(.*)"$/ do |desc|
task = Task.find_by_description(desc)
within("table > tr#task"+task.id.to_s) do
click_link "Destroy"
end
end

I run “rake features” and all is good. The only thing left to do is to rename the “Destroy” link to be “delete” as I described it and fix up the step to have a more general definition:

When /^I click "(.*)" for "(.*)"$/ do |link, desc|
task = Task.find_by_description(desc)
within("table > tr#task"+task.id.to_s) do
click_link link
end
end

I run “rake features” and see that 26 steps passed. Woo hoo! Code coverage shows 83.8% of the controller file (everything but those pesky error conditions.)

Refactor to Remove Duplication

Now that the feature description roughly covers the functionality of our app, I sought to take Matt’s advice and look at the code and see if we need to remove some duplication.
I looked first at the controller and found something odd:

in app/controllers/tasks_controllers.rb:

class TasksController  @tasks }
end
end

# GET /tasks/new
# GET /tasks/new.xml
def new
@task = Task.new

respond_to do |format|
format.html # new.html.erb
format.xml  { render :xml => @task }
end
end

# GET /tasks/1/edit
def edit
@task = Task.find(params[:id])
end

The index and new methods repeat code, but the edit method, which I would expect to contain the same repeated 4 lines omits the code. In fact, if I remove those lines in index and new, the app works fine.

class TasksController < ApplicationController
# GET /tasks
# GET /tasks.xml
def index
@tasks = Task.find(:all)
end

# GET /tasks/new
# GET /tasks/new.xml
def new
@task = Task.new
end

# GET /tasks/1/edit
def edit
@task = Task.find(params[:id])
end

When I run ‘rake features’ all the steps pass and poking at the application also yields success. What’s going on? There must be something happening by default. At first I couldn’t figure out where ApplicationController was defined, but an answer to my question on the Rails list pointed out that ApplicationController is one of the classes created by generate scaffold (defined in app/controllers/application.rb). Looking at the code (and comments) we can see that it simply sets some defaults for any controller in the application. ApplicationController is a subclass of ActionController::Base, which we can look up in the Rails API Doc. The doc explains that “Actions, by default, render a template in the app/views directory corresponding to the name of the controller and action after executing code in the action.” I suppose the extra code is in there to facilitate modifying it, in case we wanted the action to do something special.

What did we learn?

Today we learned about:

  • installing and using RCov
  • cucumber steps that can be quickly defined using webrat
  • dynamic-attribute finders: find_by
  • adding a unique DOM id to more easily test the app

We also learned that you need to understand code in order to refactor it, but, of course, we already knew that :)

There ends day 4, but I still haven’t completed all of the features of the Four Days on Rails tutorial. Topics yet to learn:

  • Adding attributes and other models: do I scaffold again or just write code?
  • Associated Models
  • Pagination
  • Updating multiple records

Now that we have learned some basic Ruby syntax and gained some understanding about what the Rails generate scaffold script does, it is high time we started using a more modern approach to coding. In fact, if you recall at the end of day 2, I realized with horror that we had actually modified code and added features without developing the tests first. This defied everything I had ever heard about good coding practices from the Ruby crowd and I set off to mend my ways.

Rick Denatale describes the process of test-driven/behavior-driven development as:

  1. Write the test/spec
  2. Ensure that it FAILS
  3. Write the code to make it pass
  4. Goto step 1

After reading a bit about test- and behavior-driven development, I decided to use a relatively new framework called cucumber which uses natural language to describe features.

Today we will:

  1. Install cucumber
  2. Set up the application
  3. Describe a feature
  4. Execute the feature and Watch it fail
  5. Write the code to make it pass
  6. Review what we learned

 


 

h1 {font-size: 150%}
h1,h2 {font-style: bold}
img
{
border:2px solid silver;
margin:0px 0px 15px 20px;
}
blockquote, pre.code {
border: solid 1px #aaa;
padding: 6px;
background-color: #eee;
color: inherit;
overflow:auto;
margin: 10px 0px;
}

Install Cucumber

Based on these install instructions

sudo gem install rspec rspec-rails cucumber webrat

important: Cucumber 0.1.12 and up depends on Webrat 0.3.2.1 or higher, which as of this writing is not yet officially released to Rubyforge’s gem repository. In the meanwhile, install Bryan Helkamp’s snapshot gem:

gem sources -a http://gems.github.com
sudo gem install brynary-webrat

The plugins’ dependencies must be installed separately:

gem install term-ansicolor treetop diff-lcs nokogiri

 

Setup the Application

First we’ll create the Rails “to do list” application:

cd $webroot
rails -d mysql todolist
cd todolist
rake db:create:all
rake db:migrate

Now we’ll set up cucumber for the project

ruby script/generate cucumber
create  features/step_definitions
create  features/step_definitions/webrat_steps.rb
create  features/support
create  features/support/env.rb
exists  lib/tasks
create  lib/tasks/cucumber.rake
create  script/cucumber

Just to make sure that everything is installed correctly:

rake features

If that runs without errors you are ready to rock.

 

Describe a Feature

In the features directory that was auto-created for us with the cucumber script, we create a .feature file which starts with a description of the feature. The first section that describes the feature appears to be purely documentation; however the “scenario” sections will each become part of the executable feature definition. For starters we’ll do something simple.

features/tasklist.feature

Feature: Tasks
In order to keep track of tasks
People should be able to
Create a list of tasks

Scenario: List Tasks
Given that I have created a task "task 1"
When I go to the tasks page
Then I should see "task 1"

We know we haven’t written any executable steps, but we’ll execute it anyhow:

Note that one of the steps is already defined in webrat. Isn’t that cool? When we set up cucumber for the project, it automatically includes step_definitions/webrat_steps.rb which defines some common steps. As you get the hang of this, you reuse certain word patterns which map to specific tests. But we’re getting ahead of ourselves. We need to dive into the creation of “steps” which make up our executable spec. Cucumber gives a some handy snippets to get us started (in the output of “rake features” above). We’ll paste these into a new file that we’ll create in the “features/step_definitions” directory:

features/step_definitions/tasklist_steps.rb

Given /^that I have created a task "(.*)"$/ do |desc|
Task.create!(:description => desc)
end

When /^I go to the tasks page$/ do
visit "/tasks"
end

Note that I touched up the first step to include a regular expression. This means I could add Given that I have created a task "foo" to another scenario and it would match this step.

Short aside on task creation syntax

To create the task, I’m calling my Task model directly (since I’m new to Rails, I looked up the ActiveRecord::Base syntax in the Rails Framework API docs). In my first pass I wrote:

task = Task.new(:description => desc);
task.save

However, Aslak Helles√ły kindly pointed out that it would fail silently with that syntax, and instead I should call task.save! or the even simpler Task.create!(:description => desc). I had missed create! in the documentation, since it is part of ActiveRecord::Validations. The API doc is a little confusing on this point, but looking at the source shows that ActiveRecord::Validations is included as a module. Pat Maddox notes that he uses the bang version (.save!) in tests, and the non-bang version (.save) in production code since validation errors aren’t exceptional.

Back to Step 3

Looking in features/step_definitions/webrat_steps.rb, you can see the definition of our third step:

Then /^I should see "(.*)"$/ do |text|
response.body.should =~ /#{text}/m
end

Ok, now we have a simple spec. Is it time to write the code? No!

Execute the Feature and Watch it Fail


As expected, we see errors on our first step, since we have not yet written any code for the application.

Write the code to make it pass

Now, at last it is time to write code

$ ./script/generate scaffold Task description:string
$ rake db:migrate

Run the spec again..

It passes, yay!

What did we learn?

When we first set up our app, to setup cucumber:

ruby script/generate cucumber

To describe our feature, we create two files:

  • features/xxx.feature
  • features/step_definitions/xxx_steps.rb

To run the feature description:

rake features

In Day 1 with Rails, we built a simple application that let us manage a list of categories using the powerful generate scaffold script. Today, we’ll look under the hood and learn about the code that was created for us, so that we can modify the application to do just what we want (or, rather, what the tutorial Four Days on Rails tutorial did, as I continue to update that tutorial for Rails 2.)

You’ll get the most out of Day 2, if you already know Ruby or you first read chapters 0-3 of the humble little Ruby book or some other introduction to the language. Or, of course, you can just wing it.

You also should know about the MVC (Model View Controller) design pattern. Although if you don’t know MVC already, you’ll get the hang of it soon, at least from the Rails perspective. The Getting Started Guide has a nice intro to MVC and elaborates on how Rails applies this venerated pattern:

2.1.1. Models A model represents the information (data) of the application and the rules to manipulate that data. In the case of Rails, models are primarily used for managing the rules of interaction with a corresponding database table. In most cases, one table in your database will correspond to one model in your application. The bulk of your application’s business logic will be concentrated in the models.

2.1.2. Views Views represent the user interface of your application. In Rails, views are often HTML files with embedded Ruby code that performs tasks related solely to the presentation of the data. Views handle the job of providing data to the web browser or other tool that is used to make requests from your application.

2.1.3. Controllers Controllers provide the “glue” between models and views. In Rails, controllers are responsible for processing the incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for presentation.

In today’s tutorial, we will learn about:

  1. The Model
  2. The Controller
  3. Views
  4. Tailoring the Generated Scaffold Code
  5. Review what we learned

h1 {font-size: 150%}
h1,h2 {font-style: bold}
img
{
border:2px solid silver;
margin:0px 0px 15px 20px;
}
blockquote, pre.code {
border: solid 1px #aaa;
padding: 6px;
background-color: #eee;
color: inherit;
overflow:auto;
margin: 10px 0px;
}

 


 

h1 {font-size: 150%}
h1,h2 {font-style: bold}
img
{
border:2px solid silver;
margin:0px 0px 15px 20px;
}

The Model

The definition of the model is in one of the files generated by scaffold:

app/models/category.rb
class Category < ActiveRecord::Base
end

This is a Ruby file that declare a class named Category that inherits from class ActiveRecord::Base. To define a class in Ruby, you place the class keyword at the beginning of a line, followed by the class name and a < and the class it inherits from.

Active Record is one of the “gems” installed with Rails. Looking in the Ruby on Rails api documentation for ActiveRecord::Base in the Classes section shows all of the methods, attributes, exceptions and other parts available in class ActiveRecord::Base.

An instance of the class Category could be called anything but the Rails convention is to use a variable named category or @category. The :: symbol is the Ruby scope operator. In ActiveRecord::Base it means that you are referring to the Base of ActiveRecord and not some other base.

note: I’ve adapted this nice explanation from Fairleads along with language note from the humble little ruby book)

We will customize our Model by adding code here.

Validation

Let’s say we want to make it so that each category appears once and only once in the category list. If you try that now, you’ll notice that the application allows a duplicate entry. Go ahead and delete the duplicate. We’ll make sure it isn’t allowed in the future, by adding validation to the model.

Rails gives you a lot of error handling for free (almost). To demonstrate this, add some validation rules to the empty category model:

app/models/category.rb

class Category  1..20
validates_uniqueness_of :title, :message => "already exists"
end

These entries will give automatic checking that:

  • validates_length_of: the field is not blank and not too long
  • validates_uniqueness_of: duplicate values are trapped. I don’t like the default Rails error message – ‘xxx has already been taken’ – so I provide my own. Note: This is a general feature of Rails – try the defaults first; if you don’t like anything, overwrite it.

Documentation: ActiveRecord::Validations::ClassMethods

To try this out, now try to insert a duplicate record. This time, Rails will you prevent you from creating a duplicate record (see below). The style is a bit in your face — it’s not the most subtle of user interfaces. However, what do you expect for free?

The Controller

Let’s look at the code behind the controller. The controller is where the programming logic for the application
lies. It interacts with the user using views, and with the database through models. You should be able to read the
controller and see how the application hangs together.

Some methods of the controller along with the class definition produced by the scaffold script are listed below:

app/controllers/categories_controller.rb

class CategoriesController  @categories }
   end
end

# GET /categories/1
# GET /categories/1.xml
def show
   @category = Category.find(params[:id])

   respond_to do |format|
      format.html # show.html.erb
      format.xml  { render :xml => @category }
   end
end
:
:
# DELETE /categories/1
# DELETE /categories/1.xml
def destroy
   @category = Category.find(params[:id])
   @category.destroy

   respond_to do |format|
      format.html { redirect_to(categories_url) }
      format.xml  { head :ok }
   end
end
end

Note that just like the model, the controller is simply a ruby class file. Each method in the class defines an action. Actions, by default, render a template in the app/views directory corresponding to the name of the controller and action after executing code in the action. For example, the index action in our Categories controller renders a list of categories; however, note that unlike index, the destroy action will not render a template. After performing its main purpose (calling destroy on the category object that the user selected), it initiates a redirect instead.

Note: there is quite a bit of Ruby magic going on in the generated controller file with exactly how the respond_to block works. Perhaps I’ll dive into that once I’ve got the basics down.

Views

Views are where the user interface is defined. Rails can render the final HTML page presented to the user from three components:

  • Layout. A layout provides common code used by all actions, typically the start and end of the HTML sent to the
    browser.
  • Template A Template provides code specific to an action, e.g. ‘List’ code, ‘Edit’ code, etc.
  • Partial A Partial provides common code which can be used in used in multiple actions.

If you look at the view files generated by the scaffold command, you will see that they are .erb files. I’m not sure what ‘erb’ stands for, but they have replaced .rhtml files in previous versions of Rails. These files are a mix of html markup with snippets of ruby code in them.

  • app/views/
    • categories/
      • index.html.erb
      • show.html.erb
      • new.html.erb
      • edit.html.erb
    • layouts/
      • categories.html.erb

Layout

Rails Naming conventions: if there is a template in appviewslayouts with the same name as the current controller then it will be automatically set as that controller’s layout unless explicitly told otherwise.


apps/layouts/categories.html.erb

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
   <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
   <title>Categories: <%= controller.action_name %></title>
   <%= stylesheet_link_tag 'scaffold' %>
</head>
<body>

<p style="color: green"><%= flash[:notice] %></p>

<%= yield %>

</body>
</html>

This is mostly HTML, plus a few bits of Ruby code embedded within tags. This layout will be called by
the rendering process regardless of the action being run. It contains the standard HTML tags – the
<html><head>...</head><body>...</body></html> that will appear on every page.

The Ruby bits in bold are translated into HTML during the Rails rendering process as follows:

  • action_name is an ActionController method which returns the name of the action the controller is processing (e.g. ‘Edit’) – this puts an appropriate title on the page, depending on the action being run.
    Documentation: ActionController::Base
  • stylesheet_link_tag is a Rails helper – a lazy way of generating code. There are a lot of these ‘helpers’ within Rails. This one simply generates the following HTML: <link href="/stylesheets/scaffold.css" media="screen" rel="Stylesheet" type="text/css" />
    Documentation: ActionView::Helpers::AssetTagHelper
  • flash Rails provides a technique for passing ‘flash’ messages back to the user – e.g. an ‘Update Successful’ message which displays on the next screen and then disappears. These can be picked up easily when included in the layout (adding it to the Layout means it will appear on any screen). (The flash message will, of course, only appear when the previous screen sends such a message.
    Documentation: ActionController::Flash
  • yield is the key to what happens next. It allows a single standard layout to have dynamic content inserted at rendering time based on the action being performed (e.g. ‘edit’, ‘new’, ‘list’). In Ruby the yield command will execute a block of code that is passed as an argument. In this case, the code will insert dynamic content from a Template with the same name – see below.
    Documentation: see Ruby language docs.

Templates

Rails naming convention: templates are held in appviews’controller”action’.erb.html. The basic list action is perhaps easiest to understand. This is the default action for the controller and is therefore the ‘index’ template


app/views/categories/index.erb.html

<h1>Listing categories</h1>

<table>

   <tr>

      <th>Title</th>

   </tr>

<% for category in @categories %>

   <tr>

      <td><%=h category.title %></td>

      <td><%= link_to 'Show', category %></td>

      <td><%= link_to 'Edit', edit_category_path(category) %></td>

   <td><%= link_to 'Destroy', category, :confirm => 'Are you sure?', :method => :delete %></td>

</tr>

<% end %>

</table>

<br />

<%= link_to 'New category', new_category_path %>

Below are some notes about the more interesting bits of code highlighted (bold) above

  • for … in … end This is some simple Ruby code to loop through the items in the array @categories. The enclosed table rows are rendered for each category in the list.
  • h automatically ‘escapes’ HTML code. One of the problems with allowing users to input data which is then displayed on the screen is that they could accidentally (or maliciously) type in code which could break the system when it was displayed. For example, think what would happen if a user typed in </table> as a Category. To guard against this, it is good practice to ‘HTML escape’ any data which has been provided by users. This means that e.g. </table> is rendered as &lt;/table&gt; which is harmless. Rails makes this really simple – just add an ‘h’ as shown
  • confirm is a useful optional parameter for the link_to helper — it generates a Javascript pop-up box which forces the user to confirm the Destroy before actioning the link.
  • link_to simply creates a link — the most fundamental part of HTML… <a href="/categories/2">Show</a>
    Documentation: ActionView::Helpers::UrlHelper

The ‘new’ action template created by the scaffold script is given below:

app/views/categories/new.erb.html

<h1>New category</h1>

<% form_for(@category) do |f| %>

  <%= f.error_messages %>

  <p>

    <%= f.label :title %><br />

    <%= f.text_field :title %>

  </p>

  <p>

    <%= f.submit "Create" %>

  </p>

<% end %>

<%= link_to 'Back', categories_path %>

form_for is part of the Rails FormHelper class. The 'new' form is defined with the block of Ruby code between do and end. Form helpers are designed to make working with models much easier compared to using just standard HTML elements by providing a set of methods for creating forms based on your models. This helper generates the HTML for forms, providing a method for each sort of input (e.g., text, password, select, and so on). When the form is submitted, the form inputs will be bundled into the params object and passed back to the controller. The form that is generated can be seen here:

<form action="/categories" class="new_category" id="new_category" method="post"><div style="margin:0;padding:0">

 <p>

 <label for="category_title">Title</label><br />

 <input id="category_title" name="category[title]" size="30" type="text" />

 </p>

 <p>

 <input id="category_submit" name="commit" type="submit" value="Create" />

 </p>

</form>

Documentation: ActionView::Helpers::FormHelper

Tailoring the Generated Scaffold Code

The code generated by the Scaffold script is perfectly usable 'out of the box', and is robust once you have added enough validation into your data model. However, if that's all there was to developing Rails applications, then all the Rails apps would be boring. Now that we understand a little bit of what's going on, we can start to tailor the application to do exactly what we want.

Modifying the Controller

In a list view, as we can see on the mail page, I would expect the records to be displayed in alphabetical order. This requires a minor change to
the controller:

appcontrollerscategories_controller.rb (excerpt)

# GET /categories

  # GET /categories.xml

  def index

    @categories = Category.find(:all, :order=>'title')

    respond_to do |format|

      format.html # index.html.erb

      format.xml  { render :xml => @categories }

    end

  end

Remember that Category is an ActiveRecord, so you can look up the find method on ActiveRecord::Base and see all the nifty options.

Documentation: ActiveRecord::Base.find

In this application, the show screen is unnecessary - all the fields fit comfortably on a single row on the screen.
So, def show can disappear, and let's go straight back to the list screen (categories index) after an 'Edit':


(excerpt)

(excerpt)

 # POST /categories

  # POST /categories.xml

  def create

    @category = Category.new(params[:category])

    respond_to do |format|

      if @category.save

        flash[:notice] = 'Category was successfully created.'

        format.html { redirect_to :action => "index"  }

        format.xml  { render :xml => @category, :status => :created, :location => @category }

      else

        format.html { render :action => "new" }

        format.xml  { render :xml => @category.errors, :status => :unprocessable_entity }

      end

    end

  end

  # PUT /categories/1

  # PUT /categories/1.xml

  def update

    @category = Category.find(params[:id])

    respond_to do |format|

      if @category.update_attributes(params[:category])

        flash[:notice] = 'Category was successfully updated.'

        format.html { redirect_to :action => "index" }

        format.xml  { head :ok }

      else

        format.html { render :action => "edit" }

        format.xml  { render :xml => @category.errors, :status => :unprocessable_entity }

      end

    end

  end

The flash message will be picked up and displayed on the next screen to be displayed - in this case, the list screen.

Sharing Variables between the Template and Layout

Below you can see that I've moved the <h1>...</h1> heading text out of the Template into the Layout so that we can keep the formatting consitent across pages. As each template will have a different heading, I need to set the value of the variable @heading in the Template. Rails is quite ok with this - Template variables are available to Layouts at rendering
time.


appviewslayoutscategories.html.erb (exceprt)

<head>

  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />

  <title>Categories: <%= controller.action_name %></title>

  <%= stylesheet_link_tag 'scaffold' %>

</head>

<body>

<h1><%=@heading %></h1>

...


app/views/categories/index.html.erb (excerpt)

<% @heading = "Categories" %>

       

<table>

  <tr>

    <th>Title</th>

  </tr>

 

<% for category in @categories %>

  <tr>

    <td><%=h category.title %></td>

    <td><%= category["created_at"].strftime("%I:%M %p %d-%b-%y") %></td>    

    <td><%= category["updated_at"].strftime("%I:%M %p %d-%b-%y") %></td>

    <td><%= link_to 'Edit', edit_category_path(category) %></td>

    <td><%= link_to 'Destroy', category, :confirm => 'Are you sure?', :method => :delete %></td>

  </tr>

<% end %>

</table>

Since we removed the 'show' action above, I've also removed the link in the categories list view. Then I added created_at and updated_at, which if you recall from Day 1, were auto-generated for us as part of the scaffold.

Instead of the default date format (e.g. Sat Dec 13 23:26:19 UTC 2008), we're using a Ruby method strftime() to format the date and time fields (e.g. 11:26 PM 13-Dec-08)

Ruby Documentation: class Time

Partial Templates

You may have noticed that edit and new are almost idential. The scaffold does not assume that will be your design, so it doesn't prematurely optimize; however, in this app the new and edit pages share almost all of the same elements. Rails can allow these templates to share code by using a "partial" template. Create a new file called _category (all partial templates begin with an '_' per Rails convention) and insert the shared code:


app/views/categories/_category.html.erb

<% form_for(@category) do |f| %>

  <%= f.error_messages %>

  <p>

    <%= f.label :title %><br />

    <%= f.text_field :title %>

  </p>

  <p>

    <%= f.submit button_name %>

  </p>

<% end %>

<%= link_to 'Back', categories_path %>

This makes the edit and new templates very short and sweet. Note the use of the variable button_name, which you can see in action below.


app/views/categories/edit.html.erb (that's the whole thing!)

<% @heading = "Edit Category" %>

<%= render :partial => @category,

  :locals => { :button_name => "Update"} %>


app/views/categories/new.html.erb

<% @heading = "New Category" %>

<%= render :partial => @category,

  :locals => { :button_name => "Create"} %>

Now we have a nicely modular webapp following the DRY principle without that unsightly repeated code. We also understand much of the code that defines our little app.

What did we learn?

We learned about the following files that were created by the generate scaffold script:

  • app/models/category.rb
  • app/controllers/categories_controller.rb
  • app/view/layouts/categories.html.erb
  • app/view/categories/
    • index.html.erb
    • show.html.erb
    • edit.html.erb
    • new.html.erb

We also learned how to create a partial template: _category.html.erb.

I learned more of the Ruby language and how to navigate the Ruby API docs, and I hope you did too. This tutorial got a bit long and required quite a bit of changes from the old one. Please comment if you find any errors and I'll fix up up for posterity.

Notably absent from this tutorial has been the famous unit testing that I hear all good Ruby developers swear by. Perhaps I'll need to go offscript and read up on that for Day 3.

Stay tuned.