ASCIIcasts - Full Episode Feed

Routing in Rails 3

Fri, 05 Mar 2010 22:23:27 +0000

We’ll continue our look into Rails 3’s new features in this episode, this time concentrating on routing. Rails 3 has a new API for defining routes and some new features. To show how the new routing works we’ll create a new application called detour and create some routes for it.

rails detour

Once we’ve created the application we can open it up in a text editor to look at the config/routes.rb file. The default file contains some documentation and examples of the new API and is worth reading through. We’re going to replace the default contents with an example of some old routes and show their Rails 3 equivalents.

/config/routes.rb

Detour::Application.routes.draw do |map|
  map.resources :products, :member => { :detailed => :get }
  
  map.resources :forums, :collection => { :sortable => :get, :sort => :put } do |forums|
    forums.resources :topics
  end
  
  map.root :controller => "home", :action => "index"
  
  map.about "/about", :controller => "info", :action => "about"
end

The old-style routes that we’re going to convert.

We’ll start with the first route in the collection above:

map.resources :products, :member = { :detailed => :get }

This route has a products resource and a specific additional member action called detailed which is called via a GET request.

The first change to note in Rails 3’s routing is that we no longer deal with the map object, instead calling resources directly in the routes.draw block. :member and :collection actions inside resources are defined inside a block. The route can therefore be rewritten like this:

resources :products do
  get :detailed, :on => :member
end

Next we’ll look at a more complex route:

map.resources :forums, :collection => { :sortable => :get, :sort => :put } do |forums|
  forums.resources :topics
end

In this route we have a forum resource with two additional collection items and a nested topics resource. With the new API this route can be written like this:

resources :forums do
  collection do
    get :sortable
    put :sort
  end
  resources :topics
end

Again we use resources instead of map.resources and pass in a block. We have two collection actions in the route. While we could define those in the same way we did with the detailed action in the first route making use of the :on argument instead we’ll define a collection block (members can be treated the same way in a member block) and any routes defined inside the block will act on the collection of forums. In our block we’ve defined two new actions sortable as a GET request and sort as a PUT.

For the nested topics resource we just call resources again, nesting the topics resource inside forums.

The next route we’ll look at is the one that defines the controller and action that the root URL point to:

map.root :controller => "home", :action => "index"

Here we can just call root and use a :to argument to which we pass a string that contains the name of the controller and action separated by a hash.

root :to => "home#index"

This ability to specify a controller and action in a single string is a new feature of Rails 3. We can do something similar for a named route:

map.about "/about", :controller => "info", :action => "about"

With the Rails 3 API this can be rewritten like this:

match "/about" => "info#about", :as => :about

Without the :as argument the route above would just be a generic route. Adding :as makes it a named route so that we can use about_path or about_url in our application.

New Features

As you can see from the examples above it’s not difficult to convert routes from the old API to the new one but what really makes the new routing API interesting is the new features it provides and we’ll spend the rest of the episode covering some of them.

Optional Parameters

Optional parameters were supported in previous versions of Rails but the syntax was a little clumsy. Lets see how it’s done in Rails 3.

It will be easier to demonstrate optional parameters if our application has a controller so we’ll create an info controller with an about action. Note that in Rails 3 we can use rails g as a shortcut for rails generate.

rails g controller info about

We can start up our server with another new shortcut:

rails s

Now, if we visit http://localhost:3000/about we’ll see the info#about action as determined by the routes we wrote earlier.

With that working we want to provide a PDF version of this action but if we visit http://localhost:3000/about.pdf we’ll get a routing error as our application doesn’t know how to match the route.

In the routes file we can change the about route to accept a format parameter by adding a full stop and :format:

match "/about.:format" => "info#about", :as => :about

If we reload PDF view now the route will be matched but we’ll see a missing template error as our application doesn’t know how to render that action as a PDF.

It looks like we’ve fixed the problem but the format isn’t optional so when we go back to the default view for that page we’ll get a routing error. Fortunately it’s easy to make part of a route optional: all we need to do is wrap the optional part in parentheses, like this:

match "/about(.:format)" => "info#about", :as => :about

Now we can visit either http://localhost:3000/about or http://localhost:3000/about.pdf without seeing a routing error.

Next we’ll show you how to use more complex optional parameters. Let’s say that our application has a number of blog articles that we want to filter by specifying a year with an optional month (or month and day) in the URL.

We can do this by defining a route like this, directing any matching route to our info#about action. Note that we can nest parentheses when creating optional parameters.

match "/:year(/:month(/:day))" => "info#about"

In the view code we’ll add some debug code so that we can see what parameters are being passed in:

/app/views/info/about.html.erb

<h1>Info#about</h1>
<p>Find me in app/views/info/about.html.erb</p>
<%= debug params %>

Now if we specify a year in the URL it will be passed into the about action and likewise if we specify a year, month and day all three parameters are passed.

This route is fairly generic though and if we were to visit, say, http://localhost:3000/foo/bar this will also be passed through to the about action when we only want parameters that look like a date to be passed. We can do this with constraints.

Constraints

Constraints are available in Rails 2 where they’re known as requirements. We can pass a :constraints option to our route with a hash of the values and the constraints that each one should match. We’ll constrain the route so that it will only match if the the year parameter is four digits and the month and day parameters are two digits:

match "/:year(/:month(/:day))" => "info#about", :constraints => { :year => /\d{4}/, :month => /\d{2}/, :day => /\d{2}/ }

With this constraint in place when we visit the /foo/bar path again we get a routing error as the path doesn’t match the date constraints.

What we’ve done with constraints so far was possible with Rails 2’s requirements but with constraints in Rails 3 we can do much more. For example we can use a user_agent parameter to restrict a route to a specific browser, in this case Firefox.

match "/secret" => "info#about", :constraints => { :user_agent => /Firefox/ }

If we visit http:/localhost:3000/secret in Safari, Chrome or Opera we’ll see a routing error but if we visit in Firefox, or set another browser to identify itself as Firefox, then the user agent passed by the browser will match the constraint and we’ll see the page.

We can also add a constraint for something a little more useful, say the host:

match "/secret" => "info#about", :constraints => { :host => /localhost/ }

This constraint means that we can visit http://localhost:3000/secret and see the page but we’ll get a routing error if we try to visit by using the IP address instead ( http://127.0.0.1/secret ) even though the two addresses are equivalent. This can be used to restrict certain routes to a given subdomain. This ability is currently a little clunky but in a future version of Rails we’ll be able to pass a :subdomain option to perform this kind of constraint.

If we have a number of routes that match a certain constraint there can be a lot of duplication in the routes file. We can reduce this duplication by using the constraints method and putting the matching routes into a block.

constraints :host => /localhost/ do
  match "/secret" => "info#about"
  match "/topsecret" => "info#about"
end

There’s much more that can be done with the constraint option but we won’t cover it here.

Routing with Rack

There’s a lot more to routing in Rails 3 than we’ve had time to cover here, but we’ll be coming back to the topic of routing in future episodes. One last feature we’ll take a look at is how Rails 3 routing embraces Rack. Normally we pass a controller and action name to a route but we can also pass in a Rack application which is an extremely powerful feature. To demonstrate this we’ll create a route that points to a simple Rack application.

match "/hello" => proc { |env| [200, {}, "Hello Rack!"] }

If you aren’t familiar with Rack then either watch or read episode 151. All we’re doing above is passing a return code, an (empty) hash of headers and a simple body.

If we visit /hello in the browser now we’ll see “Hello Rack!” so that we know our Rack application is working and generating the response. This opens up a lot of power and flexibility in how you define routes and route them to different applications. It’s easy now to route to a Sinatra application for example.

Rails 3’s new routing features provide a number of exciting possibilities. Although we’ve only given an overview of the potential here we’ll be looking at certain parts of it in more detail in the future.

For more documentation there is more information about Rails 3 routing on Yehuda Katz’s blog and on RailsGuides.

Active Record Queries in Rails 3

Tue, 23 Feb 2010 19:55:05 +0000

Over the last two episodes we’ve shown you how to set up your computer for Rails 3 and create new Rails 3 applications. In this episode we’ll begin looking at some of its new features, starting with ActiveRecord which provides a new interface for performing database queries. Pratik Naik went into this subject in detail in a post on his blog recently which is well worth reading.

Some Basic Examples

To start we’ll show you a few examples of old ActiveRecord find calls and convert them into the new query format. For this we’ll be using a basic Rails application that has two models: Article and Comment that have a relationship whereby an Article has_many :comments.

The first find we’ll update returns the ten most recently published articles.

Article.find(:all, :order => "published_at desc", :limit => 10)

The basic approach to converting an ActiveRecord query to the new Rails 3 format is to look at the hash of options that’s being passed to find and to replace each item in the hash with an equivalent method. So, instead of the find call above we can use:

Article.order("published_at desc").limit(10)

As you can see the new syntax is easy to convert from the old Rails find but has a neater syntax.

The old hash options don’t always map exactly onto the new methods however as we’ll demonstrate in this next example.

Article.find(:all, :conditions => ["published_at <= ?", Time.now], :include => :comments)

There are only two real exceptions to the rule and conveniently the example above uses them both. The find above will get all of the articles that have a published date before the current time along with any associated comments. In Rails 3 this becomes:

Article.where("published_at <= ?", Time.now).includes(:comments)

Instead of :conditions we now use the where method, passing in the same arguments as we would to :conditions. The arguments can be passed as an array but it’s cleaner to pass them separately. For getting associated records :include gets pluralized to become the includes method. All of the other options we’d normally pass to find become methods with the same name as the option.

Our final example fetches the most recently published article.

Article.find(:first, :order => "published_at desc")

Using the Rails 3 syntax this becomes:

Article.order("published_at desc").first()

Note that we don’t call first until the end of the method chain.

As we’re fetching in descending order we could rewrite the line above as:

Article.order("published_at").last()

This will perform the same query but with slightly more concise code.

In Rails 3.0 we can use either the old find methods or the new Rails 3 syntax but in Rails 3.1 the old methods will be deprecated and from Rails 3.2 they will be removed completely. It’s well worth rewriting your finds as you migrate your applications to Rails 3 so that your applications will be compatible with future releases of Rails 3.

You might be wondering at this point just what the point of this new syntax is, especially as it will break a lot of existing Rails applications when they are upgraded. Well there is a purpose to this change and it lies in the power of lazy loading.

Lazy Loading

To demonstrate lazy loading we’ll use our application’s console. If we ask for all of the articles we’ll get an array returned as we’d expect and we’ll see that we have three articles in our database.

ruby-1.9.1-p378 > Article.all => [#<Article id: 1, name: "It's Ancient", published_at: nil, hidden: false, 
created_at: "2010-02-22 20:35:42", updated_at: "2010-02-22 20:35:42">, 
#<Article id: 2, name: "Can't See Me", published_at: nil, hidden: false, 
created_at: "2010-02-22 20:37:03", updated_at: "2010-02-22 20:37:03">, 
#<Article id: 3, name: "To the Future!", published_at: nil, hidden: false, 
created_at: "2010-02-22 20:38:17", updated_at: "2010-02-22 20:38:17">]

If we want to get all of the articles in alphabetical order we can do so by using the order method:

ruby-1.9.1-p378 > articles = Article.order("name")
 => #<ActiveRecord::Relation:0x00000101669b90 @table=#<Arel::Table:0x000001023e9af8 
@name="articles", @options={:engine=>#<Arel::Sql::Engine:0x000001023a15c8 @ar=ActiveRecord::Base,
@adapter_name="SQLite">}, @engine=#<Arel::Sql::Engine:0x000001023a15c8 @ar=ActiveRecord::Base,
@adapter_name="SQLite">, …

Instead of a list of articles being returned this time we have an ActiveRecord::Relation object. This object stores information about our find, but the database query hasn’t yet been made. This is what is meant by lazy loading in this context: the data isn’t loaded until it has to be. If we were to enumerate through the records with each or get all or just the first of the articles then the query will be made.

ruby-1.9.1-p378 > articles.first
 => #<Article id: 2, name: "Can't See Me", published_at: nil, hidden: false, 
created_at: "2010-02-22 20:37:03", updated_at: "2010-02-22 20:37:03">

Now let’s see how this applies to our application. We’ve generated a scaffold for the article model so we have an articles controller with the usual seven actions. The code for the index action uses Article.all to get all of the articles immediately:

/app/controllers/articles_controller.rb

def index
  @articles = Article.all

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

If we use use any of the find options on the articles, such as ordering by name then an ActiveRecord::Relation object will be returned instead and the query will not be performed in the controller. The database query will instead be performed in the view code when we enumerate through each Article.

/app/views/articles/index.html.erb

<% @articles.each do |article| %>
  <tr>
    <td><%= article.name %></td>
    <td><%= article.published_at %></td>
    <td><%= article.hidden %></td>
    <td><%= link_to 'Show', article %></td>
    <td><%= link_to 'Edit', edit_article_path(article) %></td>
    <td><%= link_to 'Destroy', article, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>

If we load the index page now the articles will be shown in alphabetical order.

The nice thing about this is that if you’re using fragment caching with the cache method in your view this will now work better as the database query will not be performed unless it is necessary.

The new query syntax makes it easier to build up find conditions. Let’s say we want to filter the articles so that only the hidden ones are shown if we have hidden=1 in the URL’s query string. We can do that by modifying the index action like this:

/app/controllers/articles_controller.rb

def index
  @articles = Article.order('name')
    
  if params[:hidden]
    @articles = @articles.where(:hidden =>(params[:hidden] == "1"))
  end

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

Now we check that the there is a hidden parameter passed and if there is we add a where method to the find that will show only the hidden articles if that hidden parameter has a value of 1. If we append that parameter to the URL and reload the page we’ll see just the hidden articles.

Likewise if we pass 0 we’ll see only the visible articles.

Being able to chain together methods like this is a nice way to be able to build up more complex database queries while knowing that the query won’t actually be executed until the data is needed.

Named Scopes

Next we’ll show you some of the changes to named scopes in Rails 3. Below is our Article model with two named scopes, one to fetch the visible articles and one to fetch the articles that have been published.

/app/models/article.rb

class Article < ActiveRecord::Base
  named_scope :visible, :conditions => ["hidden != ?", true]
  named_scope :published, lambda { {:conditions => ["published_at <= ?", Time.zone.now]} }
end

These named scopes are defined as we’d define them in a Rails 2 application but the Rails 3 approach is a little different. The first difference is that the method to define a named scope is no longer named_scope but just scope. Also we no longer pass the conditions as a hash but, as with find, we use now use methods. Like we did with the new find methods we use where instead of :conditions. In the Rails 3 syntax the named scopes will look like this:

/app/models/article.rb

class Article < ActiveRecord::Base
  scope :visible, where("hidden != ?", true)
  scope :published, lambda { where("published_at <= ?", Time.zone.now) }
end

Another new feature is the ability to build up scopes. If we want to create a scope called recent that will return the recently published visible articles ordered by their publish date we can do so by reusing the two scopes we already have.

scope :recent, visible.published.order("published_at desc")

What we’ve done in our new scope is chain together the two scopes we already have an add an order method to create a new scope and this chaining ability is a very powerful feature to have when creating scopes for our models.

We can try our new named scope in the console. If we call Article.recent an ActiveRecord::NamedScope::Scope object is returned. This is an object that behaves in a similar way to the ActiveRecord::Relation object we saw earlier.

ruby-1.9.1-p378 > Article.recent
 => #<ActiveRecord::NamedScope::Scope:0x0000010318bd08 @table=#<Arel::Table:0x00000102740ea8 
 @name="articles", @options={:engine=>#<Arel::Sql::Engine:0x00000102651900 @ar=ActiveRecord::Base>}, 
 @engine=#<Arel::Sql::Engine:0x00000102651900 @ar=ActiveRecord::Base>>, …

If we call all on the Scope object then we’ll see the matching article returned.

ruby-1.9.1-p378 > Article.recent.all
 => [#<Article id: 1, name: "It's Ancient", published_at: "2010-01-01", 
 hidden: false, created_at: "2010-02-22 20:35:42", updated_at: "2010-02-22 23:00:16">]

A Final Tip

We’ll round up this episode with a useful tip. If you have a Relation or Scope object and want to see the SQL query that it would run against the database you can call to_sql on it.

ruby-1.9.1-p378 > Article.recent.to_sql
 => "SELECT     \"articles\".* FROM       \"articles\" 
 WHERE     (hidden != 't') AND (published_at <= '2010-02-22 22:47:12.023289') 
 ORDER BY  published_at desc"

This shows the SQL that ActiveRecord will perform to return the recently published articles that are not hidden.

That’s it for this episode on using ActiveRecord queries in Rails 3. There are a lot of great additions that will make the code in your Rails controllers more concise and expressive. Any time spent playing with the new features will soon repay itself.

Bundler

Thu, 18 Feb 2010 21:30:05 +0000

In this episode we’ll continue our look at the new features of Rails 3. This time we’re going to take a look at bundler which is the new way to manage gem dependencies in Rails applications.

Bundler is currently being updated fairly often so before doing anything with it it’s worth making sure that you have the latest version by running

gem install bundler

Note that we’re not using sudo when we install the gem because we’re using a version of Ruby that we installed with rvm.

Using Bunder to Install Gems

In the previous episode when we tried to start up the web server for the application it complained about a missing sqlite3-ruby gem. We resolved this by manually installing the gem with gem install.

gem install sqlite3-ruby

We could instead do this through bundler as sqlite3-ruby is a bundler dependency for our application, i.e. it is listed in the application’s Gemfile. To do that we run bundle install which will go through the application’s gem dependencies and install them.

$ bundle install
Fetching source index from http://gemcutter.org
Resolving dependencies
Installing abstract (1.0.0) from system gems 
Installing actionmailer (3.0.0.beta) from system gems 
Installing actionpack (3.0.0.beta) from system gems 
Installing activemodel (3.0.0.beta) from system gems 
Installing activerecord (3.0.0.beta) from system gems 
Installing activeresource (3.0.0.beta) from system gems 
Installing activesupport (3.0.0.beta) from system gems 
Installing arel (0.2.1) from rubygems repository at http://gemcutter.org 
Installing builder (2.1.2) from system gems 
Installing bundler (0.9.5) from system gems 
Installing erubis (2.6.5) from system gems 
Installing i18n (0.3.3) from system gems 
Installing mail (2.1.2) from system gems 
Installing memcache-client (1.7.8) from system gems 
Installing mime-types (1.16) from system gems 
Installing rack (1.1.0) from system gems 
Installing rack-mount (0.4.7) from rubygems repository at http://gemcutter.org 
Installing rack-test (0.5.3) from system gems 
Installing rails (3.0.0.beta) from system gems 
Installing railties (3.0.0.beta) from system gems 
Installing rake (0.8.7) from system gems 
Installing sqlite3-ruby (1.2.5) from system gems 
Installing text-format (1.0.0) from system gems 
Installing text-hyphen (1.0.0) from system gems 
Installing thor (0.13.1) from rubygems repository at http://gemcutter.org 
Installing tzinfo (0.3.16) from system gems 
Your bundle is complete!

We can see from the output above that bundler has installed all of the gems that the application needs, including sqlite3-ruby. Had it not been already installed then bundler would have downloaded it from Gemcutter and installed it.

So, when in doubt, run bundle install. You should do this whenever you create a new Rails application or clone someone else’s application so that you ensure that you have the correct gems installed. You should also run it when you deploy an application so that the correct gems are installed on the server. You can even add it to your deployment recipe so that it always runs whenever your application is deployed.

One important thing to note is that you should never run sudo when running bundle install, even if you usually use sudo when installing gems.

Adding Gem Dependencies

Now that we know how to manage our gems how do we install and add new gem dependencies to our application? In earlier version of Rails we’d manage these in our application’s /config/environment.rb file, but in Rails 3 gem configuration belongs in a file called Gemfile in the application’s root directory. The default Gemfile looks like this:

# Edit this Gemfile to bundle your application's dependencies.
source 'http://gemcutter.org'


gem "rails", "3.0.0.beta"

## Bundle edge rails:
# gem "rails", :git => "git://github.com/rails/rails.git"

# ActiveRecord requires a database adapter. By default,
# Rails has selected sqlite3.
gem "sqlite3-ruby", :require => "sqlite3"

## Bundle the gems you use:
# gem "bj"
# gem "hpricot", "0.6"
# gem "sqlite3-ruby", :require => "sqlite3"
# gem "aws-s3", :require => "aws/s3"

## Bundle gems used only in certain environments:
# gem "rspec", :group => :test
# group :test do
#   gem "webrat"
# end

There are a couple of gems already included in the file, including rails and sqlite3-ruby. Note that the line that references the rails gem includes a version number. With any gem reference in this file we can specify a version number so that we can include a certain version of a gem. If we want to upgrade the Rails version at some point we can change the version here rather than in the environment.rb file.

If we want to use any additional gems in our application we can just add them to this file. For example, if we want to use will_paginate we can reference it like this:

gem "will_paginate", ">=2.3.12"

The second parameter is a version number and used here it will mean that bundler will install version 2.3.12 or any newer version that it finds. Once we’ve added the gem reference we can install it with bundle install, but before we do that we’ll demonstrate another bundle command: bundle check.

We can run bundle check to list the gems that our application depends on but which aren’t installed. If we run it for our application it will show that will_paginate gem that we’ve referenced but not yet installed.

$ bundle check
The following dependencies are missing
  * will_paginate (>= 2.3.12, runtime)We can install the missing gems by running bundle install again.

To see what other bundle commands are available we can run bundle help.

$ bundle help
Tasks:
  bundle check        # Checks if the dependencies listed in Gemfile are satisfied by currently installed gems
  bundle exec         # Run the command in context of the bundle
  bundle help [TASK]  # Describe available tasks or one specific task
  bundle init         # Generates a Gemfile into the current working directory
  bundle install      # Install the current environment to the system
  bundle lock         # Locks the bundle to the current set of dependencies, including all child dependencies.
  bundle pack         # Packs all the gems to vendor/cache
  bundle show         # Shows all gems that are part of the bundle.
  bundle unlock       # Unlock the bundle. This allows gem versions to be changed

Other Gemfile Options

We’ll go back to our Gemfile now to see what else we can do in it. One cool new feature is the ability to get a gem from a git repository. For example, if we want to live of the edge and use the latest version of Rails in our application we can point the Rails gem to its Git repository.

# Bundle edge rails:
gem "rails", :git => "git://github.com/rails/rails.git"

This is a powerful feature to have. If a gem doesn’t quite work as we want it to we can fork the project on Github, modify the code to suit and then point the gem dependency to point to our version.

We can also restrict gems to a certain environment. If we want to use RSpec for testing we can pass in a :group option to restrict it to the test environment.

gem "rspec", :group => :test

Alternatively, if we have a number of gems we want to restrict to one environment we can use group and pass it a block.

group :test do
  gem "webrat"
  get "rspec"
end

If we run bundle install now it will install all of the gems we’ve specified for each environment.

$ bundle install
Fetching source index from http://gemcutter.org
Resolving dependencies
...
Installing rspec (1.3.0) from rubygems repository at http://gemcutter.org 
...
Installing webrat (0.7.0) from rubygems repository at http://gemcutter.org 
Installing will_paginate (2.3.12) from system gems 
Your bundle is complete!

As you’ll see from the (truncated) output above we can see that that two gems we specified in our Gemfile have been installed.

If we want to install gems but exclude those from a certain environment we can use the --without option. To install the gems that aren’t in the test group we can run:

bundle install --without=test

This is useful when you’re installing your application on your production server and don’t want to install the gems that are only used in the test environment.

Locking Gems

Another useful command is bundle lock. This locks down the specific versions of the gems your application is using. After we run it our project will have a new file in it called Gemfile.lock. This file lists all of the gems that are installed for our application along with specific version that is used. After running bundle lock only the specific versions listed in the Gemfile.lock file will be installed when we run bundle install, even if there are never versions available.

You might be wondering when you’d want to use bundle lock. Well, it’s worth using whenever a project is used in other locations. If we’re working with other Rails developers on a project we can use bundle lock to ensure that everyone is using the same versions of the gems that the application uses. The same applies when the application is being deployed to production. As the application will be being deployed to a different server we’ll want to be sure that exactly the same versions are used on the production server as they are on our development machine.

If we do need to make changes to an application’s gems after running bundle lock we shouldn’t change the Gemfile.lock file directly. Instead we should update the Gemfile as we did before. Once we’ve made our changes to the Gemfile, however, running bundle install won’t update the application’s gems as the gemfile is locked. To update the gems we need to pass the --relock option.

bundle install --relock

This will unlock the gemfile, update the gems and then re-lock.

Packing Gems With An Application

That pretty much covers the basic bundler workflow and is enough to cover most of what you’ll need when working with bundler in your applications. One final bundler feature we’ll cover is bundle pack.

Bundler installs the gems in a .bundle directory under our home directory.

$ ls ~/.bundle
cache		doc		gems		ruby		specifications

This means that the gems aren’t bundled with our application and aren’t included in our project’s version control system. If we want to store the gems within our application we can run bundle pack.

bundle pack
Copying .gem files into vendor/cache
  * memcache-client-1.7.8.gem
  * rspec-1.3.0.gem
  * thor-0.13.3.gem
  * tzinfo-0.3.16.gem
  * builder-2.1.2.gem
  * nokogiri-1.4.1.gem
  * mime-types-1.16.gem
  * sqlite3-ruby-1.2.5.gem
  * i18n-0.3.3.gem
  * abstract-1.0.0.gem
  * erubis-2.6.5.gem
  * text-hyphen-1.0.0.gem
  * bundler-0.9.6.gem
  * rake-0.8.7.gem
  * will_paginate-2.3.12.gem
  * text-format-1.0.0.gem
  * rack-1.1.0.gem
  * rack-test-0.5.3.gem
  * webrat-0.7.0.gem
  * rack-mount-0.4.7.gem
  * activesupport-3.0.0.beta.gem
  * mail-2.1.2.gem
  * arel-0.2.1.gem
  * activemodel-3.0.0.beta.gem
  * actionpack-3.0.0.beta.gem
  * actionmailer-3.0.0.beta.gem
  * activerecord-3.0.0.beta.gem
  * activeresource-3.0.0.beta.gem
  * railties-3.0.0.beta.gem
  * rails-3.0.0.beta.gem

This will generate the .gem files your application that our application needs and copy them to its /vendor/cache directory, creating the directory if necessary. The gems will now be installed directly from these .gem files instead of being fetched remotely from, for example, Gemcutter.

This shouldn’t be something you’ll need very often but if you’re in a situation where you don’t want your production server to connect to Gemcutter to download the gems from there then this is a good way to go.

That’s it for this episode. I hope it gave you a good overview on how to use bundler to manage the gems in your applications. Bundler may take a little getting used to but in the long run it will save you from some of the problems that you may have had with gem dependencies in the past.

We’ll finish by encouraging you to visit railsplugins.org. You’re probably wondering which gems and plugins work with Rails 3 and this is the place to find out. On the site you can browse the plugins and see if they work with Rails 3 and Ruby 1.9.

If a gem you want to use in a Rails 3 application is listed as not working or untested then this is a great opportunity to raise issues or help to fix it. This way you can help to get involved in getting as many gems and plugins working with Rails 3.

Rails 3 Beta and RVM

Tue, 09 Feb 2010 19:39:52 +0000

What better way to celebrate episode 200 than with a first look at Rails 3? The first beta version of Rails 3.0 has just been released and in this episode we’ll show you how to get it installed and set up. Then over the next few episodes we’ll cover the new features in depth. Even if you don’t plan on upgrading any of your applications soon it’s still worth installing the beta so that you can get your feet wet with it and play with some of the new features.

Updating Ruby

Rails 3 needs Ruby 1.8.7 or later to run, so the first thing to do is to see which version you currently have by running ruby -v in a terminal window.

$ ruby -v
ruby 1.8.6 (2008-08-11 patchlevel 287) [universal-darwin9.0]

This machine is running Ruby 1.8.6 so we’ll need to upgrade Ruby before we can go any further. We could do this manually but instead we’re going to use rvm, the Ruby Version Manager. This allows us to install different versions of Ruby easily and switch between them with just a single command.

If you’re running Windows then rvm isn’t available and you will have to install Ruby manually. On Linux, OS X or other UNIX-based operating systems we can install rvm by following the instructions on the installation page and running the following command:

mkdir -p ~/.rvm/src/ && cd ~/.rvm/src && rm -rf ./rvm/ && git clone git://github.com/wayneeseguin/rvm.git && cd rvm && ./install

After the command has finished running we’ll be given some instructions to finish the installation off. These instructions will differ depending on whether we’re running bash or zsh. Once we’ve followed those instructions and made the relevant changes we’ll need to close and reopen the terminal. We can then run the rvm command to install any version of Ruby we want.

Rails 3.0 needs Ruby 1.8.7 to run but it will also work under 1.9.1 and as we’re feeling adventurous we’ll install that version instead. To do this we run:

$ rvm install 1.9.1

This will download, configure and install Ruby 1.9.1 which will take a few minutes to do and it will keep your lap warm while it does it if you’re installing on a laptop. When it finishes we can type rvm list to see which versions of Ruby we have installed.

noonoo:~ eifion$ rvm list

   ruby-1.9.1-p378 [ x86_64 ]
   system [ x86_64 i386 ppc ]

As we now have Ruby 1.9.1 as an installed version we can switch to it to make it the active version.

$ rvm 1.9.1
$ ruby -v
ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-darwin10.2.0]

The new Ruby version will only be active for as long as we have a terminal window open. If we close and reopen the terminal we’ll be back to the default version of Ruby. To make the new version ‘stick’ we can pass the --default parameter to rvm.

$ rvm 1.9.1 --default
$ ruby -v
ruby 1.9.1p378 (2010-01-10 revision 26273) [i386-darwin10.2.0]

Now we can open as many new shells as we like and 1.9.1 will be the Ruby version each time.

If at any time we want to revert to the system version of Ruby we can use rvm system, passing --default if we want to permanently revert to the system-installed Ruby.

Installing The Rails Beta

Now that we have a supported version of Ruby installed we can install the Rails 3 beta. To do so we need to run these two lines from the Ruby on Rails Weblog3 in the console.

gem install tzinfo builder memcache-client rack rack-test rack-mount erubis mail text-format thor bundler i18n
gem install rails --pre

Because we’re installing a pre-release version of Rails we have to install the prerequisites separately which is what the first line above will do for us. Note that we’re not prefixing the gem command with sudo. As we’re using rvm we don’t want to use sudo when installing gems so you’ll need to take care and remember that. The gems page on the rvm site has more details about this.

Once both commands have run we’ll have Rails 3.0 installed and we can start trying it out.

Using Rails 3.0

First we’ll make sure that Rails 3 has been installed by running rails -v.

$ rails -v
Rails 3.0.0.beta

If you see an error when you try this then you should close your terminal window and reopen it then try the command again. Once we know we have Rails 3.0 working we can create our first application. This will be a very simple application that will store game highscores and we’ll call it topscore. We create a Rails 3.0 application in the same way we always have:

rails topscore

But when we move to the application’s directory and try to start the server we’ll notice the first difference.

¸
$ script/server
-bash: script/server: No such file or directory

None of the commands under the script directory are there any more so how do we start the server? The answer is that we run them through the rails command like this:

rails server

When we run this now though we’ll get a huge error message for our troubles, but small stumbling blocks like this are to be expected in a beta release. If we look through the error message we’ll see an error about a missing sqlite3-ruby gem. As we already have that gem installed on our machine this might be a little confusing but each version of Ruby we have installed comes with it own basic set of RubyGems so any additional gems needed will have to be installed for each version. Therefore we’ll need to install the sqlite3-ruby gem for Ruby 1.9.1, again making sure not to prefix it with sudo.

gem install sqlite3-ruby

This time when we run rails server we’ll see a lot of output and a few warnings but the server will start. If we visit http://localhost:3000 with a browser we’ll see the default Rails page.

Now we can start building our application. We’ll start by generating the scaffolding for a Game model that will have a name attribute of type string.

rails generate scaffold game name:string

Again you’ll see a lot of output when we run the command but the command will work. Next we’ll migrate the database.

rake db:migrate

If we then visit the games page we’ll see the usual scaffold-generated pages you’ll no doubt have seen before in other Rails applications.

That’s as far as we’re going to take this application. In future episodes we’ll be covering the new features of Rails 3 in depth but in the mean time it’s worth reading the Rails 3.0 Release Notes for an overview of what has changed. There is also an extensive collection of links about Rails 3 on Ruby Inside.

As you will be working with beta software there is a chance that things won’t work quite correctly and you’ll come across bugs or problems. If you do come across an error that you know isn’t related to your code the first thing to do is to check which additional gems or plugins your application is using. There’s a good chance that one of these may be causing the problem as it may have not yet been upgraded to work with Rails 3 or Ruby 1.9. If you do track a problem to a specific gem or plugin then you should add an issue or ticket on that gem’s project page so that it can be addressed.

If you know that the problem is with Rails itself then you can submit a ticket at the Rails Lighthouse. If you do decide to submit an issue then it’s worth bearing the following tips in mind. Firstly you should search through the existing tickets and make sure that you’re not duplicating an existing issue. When you’re writing your ticket make sure to include instructions on how to reproduce the error along with the full error messages and stack trace that you get. Finally include the exact version of Ruby and Rails that you’re running along with the plugins and gems you have installed so that it is easier to duplicate the problem. Submitting good tickets will help them be noticed and make it easier to fix the problem.

Give Back To Open Source

As you’ve probably noticed this is episode 200 and to mark the 200th Railscast Ryan Bates is launching a campaign called “Give Back To Open Source”. A lot of work goes into open source software which is then made freely available for anyone to use so it makes sense to give something back when we can. Ryan’s challenge to you is to open up your largest Rails application and look at the various plugins and gems that it uses. If you look at each gem’s project page you’ll find that many of them accept donations and even a small contribution would be greatly appreciated and help to keep that gem in development.

Alternatively you could look at the issues list for the project and fork the project and fix a bug or assist with the documentation. It up to you do decide how you contribute but you’re encouraged to do so as this will help to keep the Rails community moving forward.

Mobile Devices

Thu, 04 Feb 2010 21:58:39 +0000

It’s becoming more and more common to browse websites with mobile devices such as smartphones. Compared to desktop and laptop machines these have small screens and more limited abilities and given this it’s important to check your web applications on these devices to see how they work.

The best way to do this is to test your application on an actual device. Obviously “localhost” won’t work on a mobile device so you’ll need to use either the IP address of the machine your application is running on or its local domain name, assuming that your device is on the same local network. For example the machine that the application we’ll be using in this episode runs on is called noonoo so we can visit it from any other machine on the network by visiting http://noonoo.local:3000/.

If you don’t have access to a physical device you might be able to download a simulator for the device you want to test your web application on. If you want to test on an iPhone then a simulator is available from Apple’s Developer site. Likewise an emulator is provided as part of the Palm Pré SDK.

For testing on the iPhone another alternative is iPhoney. This provides an almost exact emulation of an iPhone but isn’t as accurate as the simulator, although it is a much smaller download than the iPhone SDK. If you’re using it to test a site that will have different behaviour for mobile devices then you’ll need to remember to set the correct user agent from the iPhoney menu so that the correct content is shown.

Our application running on iPhoney.

This application’s appearance could definitely be improved for display on a mobile device and we’re going to spend the rest of the episode doing this.

To start we’ll add a stylesheet in our application’s layout file that will only be included if the application is being viewed on a mobile device.

/app/views/products/_fields.html.erb

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html>
    <head>
      <title><%= h(yield(:title) || "Untitled") %></title>
      <%= stylesheet_link_tag 'application' %>
      <%= stylesheet_link_tag 'mobile' if mobile_device? %>
      <%= yield(:head) %>
    </head>
    <body>
    <!-- content omitted -->
    </body>
  </html>

The new mobile stylesheet will only be included if a method called mobile_device? returns true, and we’ll have to write this method. We could make use of the media attribute that the link element has to restrict the devices that would make use of the stylesheet, but mobile browsers can interpret this attribute in different ways. By using our own method to determine whether to include the stylesheet or not we can control which devices will include it by reading the user agent string sent by the browser.

Our next task is to write the mobile_device? method. We’ll put this in in the application controller so that the controllers can have access to this method.

/app/controllers/application_controller.rb

  class ApplicationController < ActionController::Base
    helper :all
    protect_from_forgery

    private
    def mobile_device?
      request.user_agent =~ /Mobile|webOS/
    end
    helper_method :mobile_device?
  end

Inside the method we check the request’s user agent to see if it contains either the word “Mobile”, which will match iPhone and Android devices or “webOS” which will match the Palm Pré. You can, of course, customise the regular expression to target whichever devices you want to show the mobile stylesheet. Finally we mark the method as a helper method so that we can access it from our views. If you want to be able to target a specific device there is a comprehensive list of mobile device agent ids available.

Now that we’ve written the helper method we’ll create the mobile stylesheet that mobile devices will use.

/public/stylesheets/mobile.css

  body {
    background-color: #FFF;
  }

  #container {
    width: 90%;
    min-width: none;
    margin: 0 auto;
    background-color: #FFF;
    padding: 0;
    border: none;
    margin-top: 20px;
  }

To see how the page looks with the mobile stylesheet we can make use of Safari’s user agent swapping feature. Under the Develop > User Agent menu is a list of user agent strings that can be selected, including several for various versions of Mobile Safari. If we pick one of these and look at our application again we’ll see the page with the mobile stylesheet applied.

Swapping Between Sites

Now that we have our mobile_device? helper method we can use it to alter the behaviour of the site depending on the device that is viewing it. One thing we’ll add is a link that will allow users to swap between the full and mobile versions of the site. To do this we’ll modify our application’s layout file by adding the following code at the top of the body.

/app/views/layouts/application.html.erb

  <p>
    <% if mobile_device? %>
      <%= link_to "Full Site", :mobile => 0 %>
    <% else %>
      <%= link_to "Mobile Site", :mobile => 1 %>
    <% end %>
  </p>

This code will show a link to the full site if we’re currently looking at the mobile one and vice versa. The link will redirect to the page that’s currently being viewed with a query string parameter called mobile that will determine which version of the site to show.

In our application controller we can set up a before_filter that will set a session variable so that once the link has been clicked that version will continue to be seen as the user navigates through the site. The before_filter will set a session variable if there is a mobile parameter in the query string. We’ll also modify our mobile_device? method so that it will check to see if that session variable exists and, if it does, decide which version of the site to show depending on its value. If the session variable hasn’t been set we’ll decide based on the user string.

/app/controllers/application_controller.rb

  class ApplicationController < ActionController::Base
    helper :all
    protect_from_forgery
    before_filter :prepare_for_mobile

    private
    def mobile_device?
      if session[:mobile_param]
        session[:mobile_param] == "1"
      else
        request.user_agent =~ /Mobile|webOS/
      end
    end
    helper_method :mobile_device?

    def prepare_for_mobile
      session[:mobile_param] = params[:mobile] if params[:mobile]
    end
  end

If we reload the page now there’ll be a link to the full version of the site and if we click that link we’ll see the full version even though we’re viewing the page with a user agent string that contains the word “mobile”.

This preference will persist so that clicking any of the links above will keep us on the full version of the application.

Separate Views For Mobile Devices

What we’ve done so far will work for the cases where we want to fine-tune the application for mobile devices, but what if we have grander plans and want to change the application so that it looks and behaves more like a native application when viewed on a mobile device? To do this we’ll need to change pretty much every view in our application. How would we go about doing that?

The trick to doing this is to create a new MIME type in our application and Rails provides a file for doing just that at /config/initializers/mime_types.rb. The file contains a commented-out example for providing a new iphone type which we can modify to create a new mobile one. This gives us an alternative HTML format for mobile devices.

/config/initializers/mime_types.rb

  # Be sure to restart your server when you modify this file.

  # Add new mime types for use in respond_to blocks:
  # Mime::Type.register "text/richtext", :rtf
  # Mime::Type.register_alias "text/html", :iphone
  Mime::Type.register_alias "text/html", :mobile

We still need to set that MIME type, however and to do so we need to go back to the before_filter in our application controller and set the format to :mobile if the mobile version of the site is being viewed.

/app/controllers/application_controller.rb

  def prepare_for_mobile
    session[:mobile_param] = params[:mobile] if params[:mobile]
    format :mobile if mobile_device?
  end

Now that the MIME type is set we can use it in our controllers’ actions to change the behaviour of each action depending on that type by using respond_to, as we’ll demonstrate in the index action of the projects controller.

/app/controllers/projects_controller.rb

  def index
    @projects = Project.all
    respond_to do |format|
      format.html
      format.mobile
    end
  end

The respond_to block isn’t necessary, however, if we’re just providing an alternative view based on the format. In that case we just need to provide a new template with the name of the format in it where you would normally have html. For the index view above we’ll create a file called /app/views/projects/index.mobile.erb and to start with we’ll just put some text in the file.

/app/views/projects/index.mobile.erb

  This is a mobile version!

If we visit the mobile version of that page now we’ll see the mobile view rendered.

Now that we have this in place we can create a UI that will fell much more like a native mobile application. There are a couple of libraries that we can use to make this easier: iui and jQTouch and we’ll be using jQTouch here. jQTouch makes it a lot easier to create a web application that looks and behaves like a native iPhone app.

After we’ve downloaded and unzipped jQTouch it will have a folder structure like this:

To make jQTouch easier to work with we’re going to move the extensions and themes folders into the jqtouch folder and then drag that folder into the our application’s public folder.

Next we’ll create a new layout file for the mobile version of our application.

/app/views/layouts/application.mobile.erb

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  <html>
    <head>
      <title><%= h(yield(:title) || "Untitled") %></title>
      <%= stylesheet_link_tag "/jqtouch/jqtouch.min.css", "/jqtouch/themes/apple/theme.min.css" %>
      <%= javascript_include_tag "/jqtouch/jquery.1.3.2.min.js", "/jqtouch/jqtouch.min.js", "mobile" %>
      <%= yield(:head) %>
    </head>
    <body>
      <div class="current">
        <%- if show_title? -%>
        <div class="toolbar">
          <%= link_to "Back", nil, :class => "back" unless current_page? root_path %>
          <h1><%=h yield(:title) %></h1>
          <%= yield(:toolbar) %>
        </div>
        <%- end -%>

        <% unless flash.empty? %>
          <div class="info">
          <%- flash.each do |name, msg| -%>
            <%= content_tag :div, msg, :id => "flash_#{name}" %>
          <%- end -%>
          </div>
        <% end %>

        <%= yield %>
      </div>
    </body>
  </html>

In this layout file we include a couple of the CSS files that jQTouch provides along with references to jQuery and the jQTouch JavaScript. There is also a reference to a mobile.js file that we’ll create. In the layout the content of the page is wrapped in a div with a class of current. If the page should show a title then we’ll show it wrapped in another div with the class toolbar. Likewise if there is any flash text to show it will be displayed in another div, this time with an info class. Below that we yield to whatever is in the current template.

Next we’ll need to create the new mobile.js file. All we need to put in it is a call to the jQTouch initializer.

/public/javascripts/mobile.js

  $.jQTouch({});

The initialiser function takes a hash of options but we won’t be setting any of them here. When we reload the mobile projects page again we’ll see the jQTouch styles applied, but the page will look fairly ugly as we don’t have any content in the page’s template.

If we go back to the page’s mobile view code we can replace the placeholder code with some code that will list all of the projects and a count of the number of tasks that each one has and a link to create a new project.

/app/views/projects/index.mobile.erb

  <% title "Projects" %>
  <ul>
    <% for project in @projects %>
    <li class="arrow">
      <%= link_to h(project.name), project %>
      <small class="counter"><%= project.tasks.size %></small>
    </li>
    <% end %>
  </ul>
  <ul><li class="arrow"><%= link_to "New Project", new_project_path %></li></ul>

Reloading the page again we’ll see a nice interface that looks a lot like a native mobile application.

Obviously the interface will be rather narrower when viewed on an actual iPhone, but it works just as well on a desktop browser.

Every view file in our application will need a mobile version too. There’s too much code to list here, but you can download the files from Ryan Bates’ Github page. Once we’ve done that we’ll have a fully functional mobile application that looks like a native application.

While the mobile version of our site now looks a lot better we’ve lost the ability to swap to the full version of the site. We’ll add a button on the righthand side of the top toolbar to reenable this.

The toolbar is defined in the mobile layout file and adding new controls to it is easy as the jQTouch elements are defined with HTML tags. We can add a new button by creating a new link within the toolbar div and giving it a class of button.

/app/views/layouts/application.mobile.erb

  <div class="toolbar">
    <%= link_to "Back", nil, :class => "back" unless current_page? root_path %>
    <h1><%=h yield(:title) %></h1>
    <%= link_to "Full Site", root_url(:mobile => 0), :class => "button", :rel => "external" %>
     <%= yield(:toolbar) %>
  </div>

We also need to provide a rel attribute with a value of external so that jQTouch will treat the link as a link to another site. If we don’t do this it will make an AJAX request which isn’t what we want.

When we reload the page one last time we’ll have a button on each page now that will take us back to the full version.

Edit Multiple Individually

Thu, 28 Jan 2010 20:41:25 +0000

In episode 165 [watch, read], we created an application that could edit multiple records simultaneously. Each record on the index page had a checkbox against it so that we could choose which items we wanted to edit and then update the fields for those items.

If we select the three products above then click “edit checked” we can then update the category, name or price for those products, for example putting them all into the “groceries” category.

The obvious restriction is that any changes we make are applied to all of the checked products, so in this episode we’ll write a similar application that will show a separate set of fields for each checked product so that we can update multiple products on a single form, each with their own set of values.

Adding The Checkboxes

We’ll start with a basic scaffolding for listing products. The scaffolding code gives us the ability to edit products individually, but of course that’s not what we want to do. As we did last time we’re going to add a checkbox against each item so that we can choose the items we want to edit. The first change we’re going to make therefore will be to the products index view.

/app/views/products/index.html.erb

<h1>Products</h1>
<% form_tag edit_individual_products_path do %>
  <table>
    <thead>
      <tr>
        <th></th>
        <th>&nbsp;</th>
        <th>Name</th>
        <th>Category</th>
        <th>Price</th>
      </tr>
    </thead>
    <tbody>
      <% for product in @products %>
      <tr>
        <td><%= check_box_tag "product_ids[]", product.id %></td>
        <td><%= product.name %></td>
        <td><%= product.category.name %></td>
        <td><%= number_to_currency product.price, :unit => "&pound;" %></td>
        <td><%= link_to "Edit", edit_product_path(product) %></td>
        <td><%= link_to "Destroy", product_path(product), :confirm => "Are you sure?", :method => :delete %></td>
      </tr>
      <% end %>
    </tbody>
  </table>
  <p><%= submit_tag "Edit Checked" %></p>
<% end %>
<p><%= link_to "New Product", new_product_path %></p>

To add the checkboxes we have made a number of changes to the scaffolded code. Firstly we’ve wrapped the table in a form using form_tag.

<% form_tag edit_individual_products_path do %>
  <!-- table -->
<% end %>

The form will be submitted to a new action in the products controller called edit_individual that we’ll write shortly. In the table itself we’ll add a new th element in the header then, in the table’s body, a new cell to hold the checkbox, which we’ll declare with

<%= check_box_tag "product_ids[]", product.id %>

The name we pass to check_box_tag is product_ids[], the empty square brackets mean that we can pass multiple product ids as an array for all of the checked boxes. We also pass the product’s id as a value for each checkbox.

Finally we add a submit tag so that we can submit the form.

<%= submit_tag "Edit Checked" %>

The form submits to new action called edit_individual so the next thing we’ll need to do is write that action in the products controller, along with another one called update_individual that the edit_individual action will submit to when we update the selected products.

/app/controllers/products_controller.rb

def edit_individual

end

def update_individual

end

As we’re adding actions to a RESTful resource we’ll also need to make a change to the routes file.

/config/routes.rb

ActionController::Routing::Routes.draw do |map|
  map.resources :products, :collection => { :edit_individual => :post, :update_individual => :put }
  map.resources :categories
  map.root :products
end

We modify the products resource in routes.rb, adding a :collection argument with the two new actions. :edit_individual will be a POST request as we’re submitting to it through a form. We’re just fetching information so a GET request would be ideal but as we’re submitting multiple ids a POST is necessary. We’ll be updating records in :update_individual so this will be a PUT request.

If we reload the index page now we’ll see checkboxes against each product and a button that we can click to edit those products.

We’ve not written the edit_individual template yet so we’ll see an error if we were to submit the form now. Before we create the template we’ll modify the edit_individual action so that it fetches all of the products with ids that match the array of product_ids from the checked checkboxes that are passed in.

/app/controllers/products_controller.rb

def edit_individual
  @products = Product.find(params[:product_ids])
end

Now on to the edit_individual view code. We give the page a title and then create a form, but should we use form_for or form_tag here? Well, form_for is meant to be used when editing a single model, but here we’re editing a number of models at once so we’ll use form_tag. We’ll pass it the URL to the update action and specify the method as PUT.

Inside the form we’ll loop through the list of products and use fields_for to generate the fields for each product. We do this by passing products[] and the product to fields_for. This will insert the product’s id into the empty square brackets so that each product is passed as a separate parameter. We’ll need to put the form fields themselves in next, but for now we’ll just print each product’s name. Finally we add a submit_tag.

/app/views/products/edit_individual.html.erb

<% title "Edit Products" %>

<% form_tag update_individual_products_path :method => :put do %>
  <% for product in @products %>
    <% fields_for "products[]", product do |f| %>
      <h2><%= h product.name %></h2>
    <% end %>
  <% end %>
  <p><%= submit_tag "Submit" %></p>
<% end %>

So, if we check the checkboxes for our three products and click “Edit Checked” we’ll be taken to the new edit_individual page and we’ll see the three products listed.

Along with the product’s name we want to show form fields for each product’s attributes. As these fields are also shown in the product’s new and edit actions the form itself is usually separated out into a partial. This partial contains a form_for tag which wraps the form elements for a product. We want to reuse the fields without the surrounding form_for so we’ll extract the fields into another partial that we can use both in the form and in the multiple edit page.

We’ll put the form fields into a new partial called _fields.html.erb.

/app/views/products/_fields.html.erb

<%= f.error_messages %>
<p>
    <%= f.label :name %>
    <%= f.text_field :name %>
</p>
<p>
  <%= f.label :price %>
  <%= f.text_field :price %>
</p>
<p>
  <%= f.label :category_id %>
  <%= f.collection_select :category_id, Category.all, :id, :name %>
</p>
<p>
  <%= f.check_box :discontinued %>
  <%= f.label :discontinued %>
</p>

We can then call this new partial from the _form partial, passing in the f variable.

/app/views/products/_form.html.erb

<% form_for @product do |f| %>
<%= render :partial => 'fields', :f => f %>
<p><%= form.submit "Submit" %></p>
<% end %>

Back in the edit_individual view code we can call this partial so that the fields for each product will be rendered.

/app/views/products/edit_individual.html.erb

<% content_for :title do %>
  Edit Individual
<% end %>

<% form_tag update_individual_products_path, :method => :put do %>
  <% for product in @products %>
    <% fields_for "products[]", product do |f| %>
      <h2><%= h product.name %></h2>
      <%= render "fields", :f => f %>
    <% end %>
  <% end %>
  <p><%= submit_tag "Submit" %></p>
<% end %>

When we reload the page now we’ll see the form fields for each of the selected products with their values filled in.

If we look at the appropriate part of the page’s source code we can see that the form fields have interesting names. Each name begins with products then has the product’s id and its field name in square brackets. This means that the products’ values will be sent as a hash.

<p>
  <label for="products_3_name">Name</label>
  <input id="products_3_name" name="products[3][name]" size="30" type="text" value="Stereolab T-Shirt" />
</p>
<p>
  <label for="products_3_price">Price</label>
  <input id="products_3_price" name="products[3][price]" size="30" type="text" value="12.49" />
</p>

We can use that products parameter in the update_individual action to update all of the products when the form is submitted. We need to update multiple products simultaneously and there’s an ActiveRecord method called update that will do just that for us. update takes two arguments: the first one is either a single id or an array of ids and the second is a hash of values. To update our products we can pass in the keys and values from our products parameter. After updating the products we’ll create a flash message and then redirect to the products index page.

/app/controllers/products_controller.rb

def update_individual
  Product.update(params[:products].keys, params[:products].values)
  flash[:notice] = "Products updated"
  redirect_to products_url
end

All of our products are currently in the “Groceries” category which is clearly wrong. We’ll change the categories of the t-shirt and DVD player and reduce their prices a little and submit the form. When we do we’ll be directed to the index page where we can see the updated products.

This means that our form works as we want it to and we can update a number of products at once.

Validations

If someone tries to enter invalid values on the new form we want to display any errors in a useful way. The Product model currently doesn’t have any validations so we’ll add one to ensure that the price is numeric.

/app/models/product.rb

class Product < ActiveRecord::Base
  belongs_to :category
  validates_numericality_of :price  
end

In the products controller we now need to handle validation in the update_individual action. The update method will ignore validation errors and will move on to the next record if it comes across an invalid one. All is not lost, however, as update will return an array of all of the products that it tried to update and we can use that to determine which products were invalid.

One way to get the invalid products would be to use the reject method on the array and, in reject’s block, call valid? on each product to filter out the valid ones.

Product.update(params[:products].keys, params[:products].values).reject { |p| p.valid? }

The problem with this approach is that it will run the validation for each product again. A more efficient way to do this would be to reject the products with an empty errors array. We’ll assign this array of invalid products to a variable and check to see if it’s empty. If it is we’ll redirect to the index page as before, otherwise we’ll re-render the edit_individual form to show the errors for those invalid products.

/app/controllers/products_controller.rb

def update_individual
  @products = Product.update(params[:products].keys, params[:products].values).reject { |p| p.errors.empty? }
  if @products.empty? 
    flash[:notice] = "Products updated"
    redirect_to products_url
  else
    render :action => 'edit_individual'
  end
end

If we try to edit the t-shirt and DVD player again but set an invalid value for the DVD player’s price we’ll now be returned to the edit page and shown the form again but with just the DVD player on it this time and with the validation error shown.

The title of the error message panel is currently showing the name as “products[]”, but this is easy to fix. The error messages are generated in the fields partial using the error_messages method. This takes an :object_name parameter that we can use to set the name that will be displayed.

/app/views/products/_fields.html.erb

<%= f.error_messages :object_name => "product" %>

With that done the error message will now say “product” instead of “products[]”.

One More Thing

The functionality we were after is now pretty much complete, but to finish off this episode we’ll add one more thing to make the application more useful. If we want to change a single attribute on a number of products, for example to update the price, the edit form will become cumbersome. What we’re going to do is allow the users to select a single attribute from a list so that they can then update one attribute on a number of products without having to navigate through a long form.

To do this we’ll add a pop-up menu next to the “edit checked” button on the products index page that will allow us to choose which field to edit. We can do that by adding the following line immediately before the submit_tag in the products index view.

/app/views/products/index.html.erb

  <p><%= select_tag :field, options_for_select([["All Fields", ""], ["Name", "name"], ["Price", "price"], ["Category", "category_id"], ["Discontinued", "discontinued"]])%></p>

Now we’ll be able to choose to edit all of the fields or just a single field for each selected product. To restrict the fields that are shown we’ll have to update the fields partial so that only the selected field is shown.

/app/views/products/_fields.html.erb

<%= f.error_messages, :object_name => "product" %>
<% if params[:field].blank? || params[:field] == "name" %>
<p>
    <%= f.label :name %>
    <%= f.text_field :name %>
</p>
<% end %>
<% if params[:field].blank? || params[:field] == "price" %>
<p>
  <%= f.label :price %>
  <%= f.text_field :price %>
</p>
<% end %>
<% if params[:field].blank? || params[:field] == "category_id" %>
<p>
  <%= f.label :category_id %>
  <%= f.collection_select :category_id, Category.all, :id, :name %>
</p>
<% end %>
<% if params[:field].blank? || params[:field] == "discontinued" %>
<p>
  <%= f.check_box :discontinued %>
  <%= f.label :discontinued %>
</p>
<% end %>

What we’ve done above is alter the partial so that it reads the :field attribute from the new pop-up menu on the index form and only shows each field if the attribute is blank (i.e. if the user has selected “All Fields”) or matches the name of the field. This isn’t the tidiest code there is and could be cleaned up by making use of Formtastic but it will work for us for now.

If we select two of the products from the index page now and choose “price” from the pop-up menu then the edit form will just display the price fields for those two products.

And that’s it for this episode. Editing multiple records in a single form is fairly straightforward if you make the right use of fields_for and this is a useful technique that can be applied in a number of situations.

Nested Model Form Part 2

Fri, 22 Jan 2010 23:13:17 +0000

In the previous episode we showed you how to create a form that could handle multiple nested models. In the application we’ve created for this we have a Survey model each Survey having many Questions and each Question many Answers.

In the Survey and Question models we’ve used accepts_nested_attributes_for to allow us to create, edit and destroy nested records through a single model.

As our application currently stands if we want to remove a question or an answer we have to use a checkbox. Also we have no way of adding new questions or answers through the form. In this episode we’ll fix these problems by using JavaScript to alter the form so that we can use links to create and destroy models dynamically.

The JavaScript we’ll write involves some DOM manipulation so we’ll use the Prototype library to make this easier. To add the Prototype code to our application we’ll add the following line to the <head> section of our application’s layout file.

/app/views/layouts/application.html.erb

<%= javascript_include_tag :defaults, :cache => true %>

If you prefer using jQuery then you can do so and we’ll show the equivalent jQuery code at the end of the episode.

Adding Links to Remove Answers

We’ll tackle the easiest part first: replacing the checkboxes we use to remove questions and answers with links. Let’s look at the answers first.

The code that renders each answer is held in a partial called answer_fields and looks like this:

/app/views/surveys/_answer_fields.html.erb

<p>
  <%= f.label :content, "Answer" %>
  <%= f.text_field :content %>
  <%= f.check_box :_destroy %>
  <%= f.label :_destroy, "Remove" %>
</p>

In the code above is the _destroy checkbox that we check when we want an answer to be destroyed. We’re going to replace it with a hidden field whose value will be set when the “remove” link is clicked. This way we can still mark an answer for deletion.

We’ll replace the label in the code above with a link and make use of Rails’ link_to_function to create a link that fires a JavaScript function when clicked. With the hidden field and the link the partial code will now look like this:

/app/views/surveys/_answer_fields.html.erb

<p class="fields">
  <%= f.label :content, "Answer" %>
  <%= f.text_field :content %>
  <%= f.hidden_field :_destroy %>
  <%= link_to_function "remove", "remove_fields(this)" %>
</p>

When the “remove” link next to an answer is clicked it will fire a JavaScript function called remove_fields, passing in the link as an argument so that we can use it as a reference element to find the other elements related to the answer. There’s no direct way get at all those fields so we’ve added a class name to the enclosing paragraph element so that we can find them more easily.

Next we’ll need to write that remove_fields function. We’ll do this in the application.js file as this is one of the files that is automatically included on our pages because we’ve included the JavaScript :defaults.

/public/javascripts/application.js

function remove_fields(link) {
	$(link).previous("input[type=hidden]").value = "1";
	$(link).up(".fields").hide();
}

This function performs two actions. First it uses Prototype’s previous function to find the first previous hidden field relative to the link that called the function which is the _destroy field and sets its value to 1 so that the answer will be marked as deleted. It then uses up to work its way up the DOM tree from the link until it finds an element with a class of fields, which is the class name we gave to the paragraph element that wraps the answers fields, and hides it so that the answer is hidden.

If we reload the survey page now we’ll see a link against each answer.

If we click some of the links the value of the _destroy hidden field will be set to 1 for those answers so that they are marked to be deleted and the their form fields are hidden.

Note though that we’re not using AJAX to post back updated form values when the link is clicked so that although we’re hiding the removed answers immediately the database won’t be updated until we submit the form. When we do submit the form the answers will be removed and we’ll see so on the survey’s show page.

Removing Questions

Now that we can remove answers through links we’ll move on to the questions. The way to remove a question is basically the same as the way we remove an answer and so we can reuse some of the code we wrote earlier.

As we did with the answers we’re going to replace a checkbox and a label with a hidden field and a link so we’ll take that part of the code from the answer_fields partial and put it in a new helper method called link_to_remove_fields, passing in the text we want to appear in the link and the form variable f.

/app/views/surveys/_answer_fields.html.erb

<p class="fields">
  <%= f.label :content, "Answer" %>
  <%= f.text_field :content %>
  <%= link_to_remove_fields "remove", f %>
</p>

We’ll now write that method in the application_helper file.

/app/helpers/application_helper.rb

# Methods added to this helper will be available to all templates in the application.
module ApplicationHelper
  def link_to_remove_fields(name, f)
    f.hidden_field(:_destroy) + link_to_function(name, "remove_fields(this)")
  end
end

The methods that create form fields return strings, so we can concatenate the HTML generated by f.hidden_field and link_to_function methods and return them to the partial.

We can use our new method in the question_fields partial too.

/app/views/surveys/_question_fields.html.erb

<div class="fields">
  <p>
    <%= f.label :content, "Question" %>
    <%= link_to_remove_fields "remove", f%><br />
    <%= f.text_area :content, :rows => 3 %><br />
  </p>
  <% f.fields_for :answers do |builder| %>
    <%= render 'answer_fields', :f => builder %>
  <% end %>
</div>

As our JavaScript remove_fields function looks for an element with a class of fields when hiding a question or answer we’ve wrapped the whole partial in a div element with that class name so that when the “remove” link for a question is clicked the question will be hidden along with its answers.

If we look at the edit page for a survey now and click the a question’s “remove” link the question will be removed along with its answers and when we submit the form the question and its answers will be removed from the survey.

Adding Questions and Answers

Now for the difficult part: adding new questions and answers. We want links on the form that will create new form fields dynamically when they are clicked. What makes this difficult is that the JavaScript will need to have access to a blank set of fields so that it can create a new question or answer when a link is clicked.

To do this we’ll write a new method in the application helper called link_to_add_fields. We’ll be able to use this method whenever we need to show a link to add the fields for a new question or answer on the form. The code for the method will look like this:

/app/helpers/application_helper.rb

def link_to_add_fields(name, f, association)
  new_object = f.object.class.reflect_on_association(association).klass.new
  fields = f.fields_for(association, new_object, :child_index => "new_#{association}") do |builder|
    render(association.to_s.singularize + "_fields", :f => builder)
  end
  link_to_function(name, h("add_fields(this, \"#{association}\", \"#{escape_javascript(fields)}\")"))
end

The method takes three arguments: name, which will be the link’s text; f, the form builder object and association, which in this case will be either “questions” or “answers”.

The first line of the method creates a new instance of that new association class, i.e. a new Question or Answer. This means that we have a template object that we can use to create the new form fields.

The second part of the code builds a string of the form fields for that object so that we can insert them into the javascript function that will add them to the form when a link is clicked. It does this by calling the appropriate partial code, passing in the form builder. The only really new thing here is the :child_index we set. We do this so that we have something to refer to for creating the fields for the new question or answer. In the JavaScript we’ll replace the name of this with a unique value which will be based on the current time. That way, every time we create a new question or answer it will have a unique index so that it can be identified when we submit the form.

Finally we use the link_to_function method again, passing in the name of the link and a call to a JavaScript function called add_fields to which we pass the link, the name of the association and a string containing the escaped form fields.

Now we can go back to the JavaScript and write the add_fields function.

/public/javascripts/application.js

function add_fields(link, association, content) {
  var new_id = new Date().getTime();
  var regexp = new RegExp("new_" + association, "g");
  $(link).up().insert({
	before: content.replace(regexp, new_id)
  });
}

This function takes the three arguments we mentioned earlier: the link that was clicked, the name of the association and a string containing the HTML for the form fields. The first thing this function does is create a new id for the form elements. If we create multiple new questions or answers we don’t want them to have the same index value as they will be considered the same model when they’re inserted. We use the current time to make the id unique and then use a regular expression to replace the “new_question” or “new_answer” string in the form fields with that new unique id. That done we insert the string of form fields into the appropriate place in the DOM.

That’s the difficult part over. All we need to do now is add the links themselves. In the question_fields partial we’ll add a link to add a new answer using link_to_add_fields, passing in :answers as the name of the association as a question has many answers.

/app/views/surveys/_question_fields.html.erb

<div class="fields">
  <p>
    <%= f.label :content, "Question" %>
    <%= link_to_remove_fields "remove", f %><br />
    <%= f.text_area :content, :rows => 3 %><br />
  </p>
  <% f.fields_for :answers do |builder| %>
    <%= render 'answer_fields', :f => builder %>
  <% end %>
  <p><%= link_to_add_fields "Add Answer", f, :answers %></p>
</div>

We can then to do a similar thing in the survey form to add an “Add Question” link.

/app/views/surveys/_form.html.erb

<% form_for @survey do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <% f.fields_for :questions do |builder| %>
    <%= render 'question_fields', :f => builder %>
  <% end %>
  <p><%= link_to_add_fields "Add Question", f, :questions %>
  <p><%= f.submit "Submit" %></p>
<% end %>

If we reload the survey page now we’ll see the links for adding a new question or answer and when we click one of them a new field will appear on the form.

A new, blank answer field appears on the form when we click the “Add Answer” link.

If we fill in the new answer field above with “jQuery” and submit the form then the new answer will be added.

So, we’ve reached our goal and now have a form on which we can dynamically add or remove fields and have the database updated appropriately when the form is submitted.

Alternate jQuery Code

The JavaScript code we’ve used in this episode works with the Prototype library. If you prefer using jQuery, the code should look like this:

function remove_fields(link) {
	$(link).prev("input[type=hidden]").val("1");
	$(link).closest(".fields").hide();
}

function add_fields(link, association, content) {
	var new_id = new Date().getTime();
	var regexp = new RegExp("new_" + association, "g");
	$(link).parent().before(content.replace(regexp, new_id));
}

This code is very similar to the Prototype code we’ve been writing.

Some of you reading this might be a little upset that the JavaScript we’ve use isn’t unobtrusive. While an unobtrusive solution is always preferable there isn’t really one for our problem that was simple enough to present in this episode. Ryan Bates is working on a plugin called nested_form that will make use of jQuery to handle nested forms in an unobtrusive way. This plugin is still in early development so if you think you’ll need something like this keep checking there to see how it is coming along.

Nested Model Form Part 1

Thu, 14 Jan 2010 22:26:59 +0000

Back in 2007 a series of episodes covered the creation of complex forms that could manage multiple models in a single form. That series is now rather out of date so beginning with this episode we’ll show you the more modern techniques for handling forms with multiple models.

One thing that makes a big difference in our approach to handling this problem is the accepts_nested_attributes_for method which was added in Rails 2.3. We’ll be using it throughout this series so you’ll need to be running the latest version of Rails to make use of this technique in your own applications.

The documentation for accepts_nested_attributes_for is worth reading and shows how to use it with nested attributes in a single update call but it less clear on how we would get this working in the view itself, so we’ll focus on this.

Our Survey Application

Let’s first take a look at the application we want to build over the course of this series, which is an application for making surveys. The application will have a complex form for creating and editing surveys that lets us enter a survey’s name along with a number of questions, each with multiple answers. The form will also have links to allow us to dynamically add and remove questions and answers from a survey.

The complex form for creating and editing surveys.

What we have here is a deeply-nested association in which a survey has many questions and a question many answers. In the previous series on complex forms it was not possible to have create deeply nested forms like this but with Rails 2.3 we can.

Getting Started

We’re going to create our survey application from scratch, so we’ll start by creating a new Rails application called surveysays.

rails surveysays

To make writing the application easier we’ll use two of Ryan Bates’ nifty generators. We’ll use the nifty layout generator first to create a layout for the application.

script/generate nifty_layout

Our application will have three models: Survey, Question and Answer. We’ll start with the Survey model and use the nifty scaffold generator to create a scaffold to go with it. Survey will have just one attribute called name.

script/generate nifty_scaffold survey name:string

Next we’ll run the migrations to create the surveys table in the database.

rake db:migrate

If we look at the application now we’ll have scaffold files to allow us to list, create and edit surveys and a basic survey form that we can build on.

What we want on the form are fields that will allow us to add questions and answers when we create a new survey. The first step we’ll take is to generate the Question model. This will have a survey_id field and a content field to hold the question’s text.

script/generate model question survey_id:integer content:text

Having done that we’ll migrate the database again to create the questions table.

rake db:migrate

Next we’ll set up the relationship between Survey and Question in their model files.

/app/models/question.rb

class Question < ActiveRecord::Base
  belongs_to :survey
end

/app/models/survey.rb

class Survey < ActiveRecord::Base
  has_many :questions, :dependent => :destroy
end

Note that in Survey we’ve used :dependent => :destroy so that when we delete a survey all of its questions are deleted too.

In the Survey model we’re going to use accepts_nested_attributes_for so that we can manage questions through Survey. By using this we can create, update and destroy questions when we update a survey’s attributes.

/app/models/survey.rb

  class Survey < ActiveRecord::Base
    has_many :questions, :dependent => :destroy
    accepts_nested_attributes_for :questions
  end

Creating The Form

Having set up the Survey and Question models we’ll move on to the survey form. What we want to do here is add fields for each of the survey’s questions to the form. We can use the fields_for method to manage associated fields in a form, passing it the name of the associated model and then loop through all of the associated question records and create a form builder for each of them. The builder will render a label and textarea for each question.

/app/views/survey/_form.html.erb

<% form_for @survey do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <% f.fields_for :questions do |builder| %>
  <p>
    <%= builder.label :content, "Question" %><br />
    <%= builder.text_area :content, :rows => 3 %>
  </p>
  <% end %>
  <p><%= f.submit "Submit" %></p>
<% end %>

When we reload the form now it will look like it did before. This is because a new survey won’t have any questions associated with it and therefore none of the question fields will be shown. Ultimately we want to have an “Add Question” link on the form but for now we’ll just create some questions in the SurveyController’s new action.

/app/controllers/surveys_controller.rb

def new
  @survey = Survey.new
  3.times { @survey.questions.build }
end

This will add three questions to a new survey that we’ll see in the form when we reload the page. We can now fill in the name and the first two questions and submit a new survey.

When we submit the survey a new Survey record will be created but we won’t see its questions as we’re not displaying them on the page. To fix this we can modify the show view for Survey to show a survey’s questions.

/app/views/survey/show.html.erb

<% title "Survey" %>

<p>
  <strong>Name:</strong>
  <%=h @survey.name %>
</p>

<ol>
  <% for question in @survey.questions %>
  <li><%= h question.content %></li>
  <% end %>
</ol>

<p>
  <%= link_to "Edit", edit_survey_path(@survey) %> |
  <%= link_to "Destroy", @survey, :confirm => 'Are you sure?', :method => :delete %> |
  <%= link_to "View All", surveys_path %>
</p>

When we reload the survey’s page we’ll see the questions listed which shows that when we added the survey its questions were saved too.

We can also edit a survey and if we change any of the questions they will be updated when we submit the form.

On the page above we have three questions listed even though we only entered values for the first two. It would be better if blank questions were automatically removed. The accepts_nested_attributes_for method has a reject_if option that we can use to do this. The method accepts a lambda which has a hash of attributes passed to it and we can use that hash to reject a question if its content is blank.

/app/models/survey.rb

class Survey < ActiveRecord::Base
  has_many :questions, :dependent => :destroy
  accepts_nested_attributes_for :questions, :reject_if => lambda { |a| a[:content].blank? }
end

If we create a new survey now with only two of question fields filled in only two questions will be created and we won’t see a blank question in the list.

What if we want to delete existing questions when we’re editing a survey? In the final application we want to use a link to delete questions but for now we’re going to take the easier option and use a checkbox. In the survey form partial we’ll add a checkbox and a label to go with it.

/app/views/survey/_form.html.erb

<% form_for @survey do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <% f.fields_for :questions do |builder| %>
  <p>
    <%= builder.label :content, "Question" %><br />
    <%= builder.text_area :content, :rows => 3 %>
    <%= builder.check_box :_destroy %>
    <%= builder.label :_destroy, "Remove Question" %>
  </p>
  <% end %>
  <p><%= f.submit "Submit" %></p>
<% end %>

The trick here is the attribute name for the checkbox: _destroy. When this has a value of true, i.e. when the checkbox is checked, the record will be removed when the form is submitted.

In order to make this work we need to enable it in accepts_nested_attributes_for in the Survey model by adding :allow_destroy => true.

/apps/models/survey.rb

class Survey < ActiveRecord::Base
  has_many :questions, :dependent => :destroy
  accepts_nested_attributes_for :questions, :reject_if => lambda { |a| a[:content].blank? }, :allow_destroy => true
end

When we reload the page now we’ll have a “Remove Question” checkbox against each question.

And if we check the “Remove Question” checkbox against one of the questions and submit the form that question will be removed.

Adding Answers

We now have the questions set up as we want them but not the answers. We’ll start on that now by creating the Answer model and setting up the nesting. First we’ll generate the model.

script/generate model answer question_id:integer content:string

Then migrate the database again.

rake db:migrate

Next we’ll set up the relationship between Answer and Question. Answer will belong_to Question.

/app/models/answer.rb

class Answer < ActiveRecord::Base
  belongs_to :question
end

For Question we’ll need to use accepts_nested_attributes_for as we did in the Survey model.

/app/models/question.rb

class Question < ActiveRecord::Base
  belongs_to :survey
  has_many :answers, :dependent => :destroy
  accepts_nested_attributes_for :answers, :reject_if => lambda { |a| a[:content].blank? }, :allow_destroy => true
end

In the form we’ll need to add fields for answers but the form view code will become cluttered if we add another nested model to it. Later on we’ll want to add questions on the form via a link with JavaScript so for both these reasons we’ll move the form code that renders each question into a partial called question_fields.

After doing this the form view will look like this.

/app/views/surveys/_form.html.erb

<% form_for @survey do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <% f.fields_for :questions do |builder| %>
    <%= render 'question_fields', :f => builder %>
  <% end %>
  <p><%= f.submit "Submit" %></p>
<% end %>

Note that we’re just passing the name of the partial as a string to render, making use of the new short form that was introduced in Rails 2.3. We also pass the builder to the partial with a name of f. In the new question_fields partial we can then use that f variable to render the form elements for a Question.

/app/views/surveys/_question_fields.html.erb

<p>
  <%= f.label :content, "Question" %><br />
  <%= f.text_area :content, :rows => 3 %><br />
  <%= f.check_box :_destroy %>
  <%= f.label :_destroy, "Remove Question" %>
</p>

We can handle the answer fields in a similar way and put them in their own partial file. In the _question_fields partial we’ll loop through the answers for the question and render a new partial called _answer_fields.

/app/views/surveys/_question_fields.html.erb

<p>
  <%= f.label :content, "Question" %><br />
  <%= f.text_area :content, :rows => 3 %><br />
  <%= f.check_box :_destroy %>
  <%= f.label :_destroy, "Remove Question" %>
</p>
<% f.fields_for :answers do |builder| %>
  <%= render 'answer_fields', :f => builder %>
<% end %>

In our new _answer_fields partial we’ll put the code to render an Answer.

/app/views/survey/_answer_fields.html.erb

<p>
  <%= f.label :content, "Answer" %>
  <%= f.text_field :content %>
  <%= f.check_box :_destroy %>
  <%= f.label :_destroy, "Remove" %>
</p>

So that we can see the answer fields on the form we’ll modify the SurveyController’s new action so that the three new questions that are created each create four answers.

/app/controllers/survey_controller.rb

def new
  @survey = Survey.new
  3.times do
    question = @survey.questions.build
    4.times { question.answers.build }
  end
end

Now, when we create a survey we have three questions each with four answers.

When we fill in the fields and submit the form the answers won’t be shown but we can easily fix that. In the section of the show view for a survey that renders each question we’ll add some code to render each question’s answers.

/app/views/survey/show.html.erb

<ol>
  <% for question in @survey.questions %>
  <li><%= h question.content %></li>
  <ul>
    <% for answer in question.answers %>
      <li><%= h answer.content %></li>
    <% end %>
  </ul>
  <% end %>
</ol>

If we reload the survey’s page now it will show the questions and the answers.

We aren’t quite done yet as we want to be able to add or remove questions or answers on the form dynamically via links. We’ll cover this in the next episode.

Favourite Web Apps in 2009

Tue, 05 Jan 2010 17:07:53 +0000

This week’s episode will be a little different from normal in that we’re going to show you some of the best web applications for Rails developers in 2009. All of the following applications will help you improve your Rails apps in some way or other. Let’s jump straight in with the first one.

Github

The first app on the list should require no introduction: Github. If you’re a programmer then you really should be using it. Github has several features that are less well-known but still useful, for example Gists which are handy ways to share code snippets. Github’s help section is also worth taking a look as it contains a wealth of articles to help you get the most from Git and Github.

Gemcutter

The second app in our list is Gemcutter which is the ultimate place to host your RubyGems. Gemcutter was covered back in episode 183 [watch, read], but since then it has become even easier to use. Previously you had to call the gem tumble command to install gems from Gemcutter but this is no longer necessary as the gem hosting on RubyForge now points to Gemcutter making it the best place to install Gems from.

What makes Gemcutter so valuable is the ease with which it allows you to publish your own gems. It takes just the three steps listed in the screenshot above. The only potentially tricky part is creating a gemspec file but that can be made easier by using another gem’s gemspec file as a template. A good example is the gemspec file for Ryan Bates’ CanCan gem.

Gem::Specification.new do |s|
  s.name = "cancan"
  s.summary = "Simple authorization solution for Rails."
  s.description = "Simple authorization solution for Rails which is completely decoupled from the user's roles. All permissions are stored in a single location for convenience."
  s.homepage = "http://github.com/ryanb/cancan"
  
  s.version = "1.0.2"
  s.date = "2009-12-30"
  
  s.authors = ["Ryan Bates"]
  s.email = "ryan@railscasts.com"
  
  s.require_paths = ["lib"]
  s.files = Dir["lib/**/*"] + Dir["spec/**/*"] + ["LICENSE", "README.rdoc", "Rakefile", "CHANGELOG.rdoc", "init.rb"]
  s.extra_rdoc_files = ["README.rdoc", "CHANGELOG.rdoc", "LICENSE"]
  
  s.has_rdoc = true
  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "CanCan", "--main", "README.rdoc"]
  
  s.rubygems_version = "1.3.4"
  s.required_rubygems_version = Gem::Requirement.new(">= 1.2")
end

A gemspec file like the one above can be edited to suit your own project. The file is easy to change directly whenever you create a new version of your gem and you can then build and push to release the new version.

Caliper

Next up is Caliper. You might remember that back in episode 166 [ watch, read] we covered the metric_fu gem. Caliper is basically an online version of metric_fu and is a great way to gather metric information about any Rails application that is hosted in a Git repository. To use it you just need to enter the URL of the repository and within a few seconds it will return all of the metric information for that project.

You can view information about test/code ratios, code smells and many other details about your Rails applications so that you can help improve your code or use it to examine other projects you’re interested in. If you find a gem or plugin you want to use you can run it through Caliper to find out how large the codebase is and how well it has been designed and written.

Rdoc.info

Another useful site is rdoc.info. If you’re looking for documentation for a given Ruby project on Github, try this site and look for the project you’re interested in. If it’s not listed you can add it and the RDocs will be generated and made available.

RunCodeRun

Another great application is RunCodeRun, which is a simple continuous integration server. Just point it at an application in a Github repository and it will run that app’s tests and report back on whether they pass or fail. RunCodeRun is free for public repositories and is well worth trying out. Once it has run the tests you can browse the projects and see which ones pass or fail.

RunCodeRun uses your application’s default rake task to run the tests. This means that you can alter this task to do whatever you want it to. In your application’s Rakefile you could point it to the :spec and :features tasks so that the Rspec and Cucumber features are run.

task :default => [:spec, :features]

The Ruby Toolbox

The Ruby Toolbox is a great resource. Often when you’re developing a new Rails application you’re left wondering which gem or plugin to use for a certain task. The Ruby Toolbox is an excellent way to find out which gems or plugins are available for handling different categories of task. For example if your application requires versioning you can find a list of the available projects and how to use them.

New Relic

Another application that you should be using in any production Rails applications you have is NewRelic RPM. This is a immensely useful application for finding performance issues in your applications to ensure that it’s running smoothly and to help keep it that way. Even the free version, RPM Lite, provides enough information to enable to find the bottlenecks in your application and to monitor how well it is running.

Learnivore

If you’re a fan of screencasts then Learnivore is a great site. There are a large number of both free and paid screencasts aggregated there including Railscasts. Learnivore is a resource well worth checking out.

Finally Ryan kindly mentioned ASCIIcasts as one of his favourite sites but as you’re already here you already know all there is to know about it.

MongoDB and MongoMapper

Wed, 30 Dec 2009 12:43:47 +0000

MongoDB is a document-based database engine which works differently from traditional relational databases such as MySQL in that it is schema-free. This episode will cover the basics of using MongoDB with the MongoMapper gem to create a simple Rails application. Many Rails developers first heard about MongoDB after a posting by John Nunemaker on his excellent RailsTips blog showing seven features of MongoMapper and MongoDB that contrast it with traditional relational databases. This post is well worth reading if you think you might be interested in using MongoDB.

One feature mentioned in the blog posting and one that makes MongoDB interesting is that you don’t need to use migrations as it’s basically a schema-less database engine. Each row is its own document which can have its own set of attributes different from the other rows in the database. As there is no fixed schema we can define one on the fly if we want to.

Installing MongoDB and MongoMapper

To create our application we’ll first need to install MongoDB. Downloads for various platforms can be found on the download page on the MongoDB site. If you’re using OS X there’s a great article on how to install and configure MongoDB on Chris Kampmeier’s site. This article includes a handy plist file that will allow you to create a LaunchDemon so that MongoDB will run automatically on startup. The article makes a reference to an old version of MongoDB so make sure that you install the latest version instead (1.2.0 at the time of writing). Once MongoDB is installed and configured you can visit http://localhost:28017/ to see if it’s working.

Creating a Rails Application With MongoDB

Now that we have MongoDB installed and running we can start creating a Rails application that will work with it. We’ll create a new Rails application from scratch for this episode called todo.

rails todo

We’ll be using the MongoMapper gem to enable our app to talk to MongoDB. To do this we need to add the following line in the config block of /config/environment.rb.

/config/environment.rb

config.gem "mongo_mapper"

We also need to set up some additional configuration which we’ll do inside an initializer file. In the /config/initializers directory we’ll create a new file that we’ll call mongo_config.rb. In this file we just need to add one line to tell MongoMapper which database to use.

/config/initializers/mongo_config.rb

MongoMapper.database = "todo-#{Rails.env}"

By passing the current environment as part of the database name we’ll create different databases for our development, test and production environments. If we were to move this application into production there’d be more we’d need to do for authentication and so on but for the purposes of this demonstration what we have is fine.

The final step in setting up our application is to run the following command to make sure that the MongoMapper gem is installed.

sudo rake gems:install

Building Our Application

Now we can start building our application. This is a simple todo list app which will have a Project model and where a Project will have many Tasks. To make the writing of the application easier we’ll use Ryan Bates’ Nifty Generators, but note that the application could be written without them.

The first thing we’ll do is create a layout for our application which we can do by running

script/generate nifty_layout

Next we’ll generate the Project model and a scaffold to go with it. Project will have only one field, name, and as we’re not generating a normal model ActiveRecord model with a schema we’ll pass --skip-migration so that no migration file is generated.

script/generate nifty_scaffold project name:string --skip-migration

This will generate a model file, controller and views for us. The generated Project model will be an ActiveRecord one so we’ll have to change it to work with MongoMapper.

/app/models/project.rb

class Project < ActiveRecord::Base
  attr_accessible :name
end

The generated code for the Project model.

All we have to do here is stop our class inheriting from ActiveRecord::Base and include MongoMapper::Document instead.

To define the model’s attributes we use a key method. We pass this the name of the attribute, in this case :name, and also a type which should be a Ruby class. For our :name attribute this will be a String. Our model will now look like this:

/app/models/project.rb

class Project
  include MongoMapper::Document

  key :name, String
end

With the changes we’ve made to the model we can now run our application and use it to create, update and list projects as we would with an application based on a relational database and ActiveRecord, only instead it’s using MongoMapper and MongoDB.

In terms of its interface MongoMapper works in a similar way to ActiveRecord. We can perform finds and create, update and destroy records just like we normally would. It even supports validations in the same way as ActiveRecord so we could add

/app/models/project.rb

validates_presence_of :name

to our Project model and we would no longer be able to create a project with a blank name. With MongoMapper there’s a better way to add validations by moving them inline. To make the name attribute required we can add :required => true to the key method’s parameters.

/app/models/project.rb

class Project
  include MongoMapper::Document

  key :name, String, :required => true
end

Adding validation to the Project model.

Adding More Attributes

As MongoDB is a schema-less database we can easily add or alter attributes in a model without needing to run any migrations. If we want to add a priority attribute to our Project we can just add it into the model.

/app/models/project.rb

class Project
  include MongoMapper::Document

  key :name, String, :required => true
  key :priority, Integer
end

We can interact with this new attribute just as we would with an ActiveRecord one. So, in the Project form partial we can add a select menu that will allow us to select a priority when we create or update a project.

/app/views/projects/_form.html.erb

<% form_for @project do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </p>
  <p>
    <%= f.label :priority %><br />
    <%= f.select :priority, [1,2,3,4,5] %>
  </p>
  <p><%= f.submit "Submit" %></p>
<% end %>

We can then modify the show view so that we can display a project’s priority.

/app/views/projects/show.html.erb

<% title "Project" %>
<p>
  <strong>Name:</strong>
  <%=h @project.name %>
</p>
<p>
  <strong>Priority:</strong>
  <%=h @project.priority %>
</p>
<p>
  <%= link_to "Edit", edit_project_path(@project) %> |
  <%= link_to "Destroy", @project, :confirm => 'Are you sure?', :method => :delete %> |
  <%= link_to "View All", projects_path %>
</p>

When we visit the New Project page now we’ll see the priority select menu and when we create a new project its priority will be shown.

As we created a project before we added the priority attribute you might be wondering what priority it will have assigned to it. If we look at that project we’ll see that the priority is blank. As a priority value doesn’t exist for that for that document in MongoDB it will have a nil value.

Associations

In our Todo application we also want to have a Task model; each Project will have many Tasks. We’ll generate the scaffolding for this as we did before for Project. Note that the project_id is a string where we’d usually use an integer.

script/generate nifty_scaffold task project_id:string name:string completed:boolean --skip-migration

As with the Project model we’ll need to modify the model file to work with MongoMapper, by replacing the ActiveRecord-specific code.

/app/models/Task.rb

class Task
  include MongoMapper::Document
  
  key :project_id, ObjectId
  key :name, String
  key :completed, Boolean
  
  belongs_to :project
end

Again we’ve included MongoMapper::Document and used the key method to define the model’s attributes. You might have expected the project_id to have a type of Integer, but MongoDB uses ObjectId to store ids.

We define Task’s relationship with Project as we would with ActiveRecord by using belongs_to. In Project you might expect to use has_many :tasks, but for MongoMapper we instead use many.

/app/models/project.rb

class Project
  include MongoMapper::Document

  key :name, String, :required => true
  key :priority, Integer
  
  many :tasks
end

We can now run the application and use the scaffold-generated controller and views to create new tasks. Entering a project’s id on the new task form will be tricky though as the scaffold will have generated a text box for the project_id field. This is because we defined it as a string field when we created the scaffold. We’ll modify the view so that it uses a select menu allowing to choose from any of the existing projects. Just like we would with an ActiveRecord form we can use collection_select to create a select menu that lists all of the projects.

/app/views/tasks/_form.html.erb

<% form_for @task do |f| %>
  <%= f.error_messages %>
  <p>
    <%= f.label :project_id %><br />
    <%= f.collection_select :project_id, Project.all, :id, :name %>
  </p>
  <!-- Rest of form... -->

Now we’ll have an easy way to select a project when we’re creating a new task.

After we’ve created a new task we’ll be taken to that task’s page which will show the project’s id. It would be better if we could show the project’s name instead. We can do this by replacing @task.project_id in the show view with @task.project.name.

/app/views/tasks/show.html.erb

<% title "Task" %>

<p>
  <strong>Project:</strong>
  <%=h @task.project.name %>
</p>
<!-- Rest of form -->

The form will now show the name from the associated project, just as it would with an ActiveRecord-based form.

Finds in MongoDB

We’ll finish off this episode by showing a few techniques for using finding Mongo models in the console. In some ways it behaves very much like ActiveRecord. For example we can find all of the projects with Project.all

>> Project.all
=> [#<Project name: "Yardwork", _id: 4b39d8c9a175750357000001, priority: nil>, #<Project name: "Housework", _id: 4b39fbd1a175750357000002, priority: 3>]

We can also find a project by its id…

>> Project.find('4b39d8c9a175750357000001')
=> #<Project name: "Yardwork", _id: 4b39d8c9a175750357000001, priority: nil>

…or supply options to all to find records in a given order.

>> Project.all(:order => "name DESC")
=> [#<Project name: "Yardwork", _id: 4b39d8c9a175750357000001, priority: nil>, #<Project name: "Housework", _id: 4b39fbd1a175750357000002, priority: 3>]

As with ActiveRecord we can pass conditions to find. This differs from ActiveRecord in that the conditions are passed inline so we would find all of the projects with a priority of 3 with:

>> Project.all(:priority => 3)
=> [#<Project name: "Housework", _id: 4b39fbd1a175750357000002, priority: 3>]

What about more complex conditions? As Mongo isn’t based on SQL we can’t just pass a SQL string into the conditions. Instead it has its own language for creating more complex conditions. MongoMapper provides a convenient way to get around this by passing a method to a symbol. For example to get all of the projects that have a priority of two or greater we can use:

>> Project.all(:priority.gte => 2)
=> [#<Project name: "Housework", _id: 4b39fbd1a175750357000002, priority: 3>]

We can also use in, passing it an array of values to find, say, projects with a priority of 2 or 3.

>> Project.all(:priority.in => [2,3])
=> [#<Project name: "Housework", _id: 4b39fbd1a175750357000002, priority: 3>]

Documentation is a little sparse on the find conditions right now, but you can find out more about them by reading though the appropriate test file on Github.

That’s it for this episode. We’ve only covered the basics of MongoDB and MongoMapper so you’re encouraged to do your own research if you want to take it any further. There is a mailing list you can join and you can follow MongoDB on Twitter.

The big question you need to ask yourself is should you use MongoDB over a traditional relational database? It’s really up to you to decide whether you think MongoDB and MongoMapper are suitable for your Rails projects, but you’re encouraged to give MongoDB a try to see if it’s a good fit for your projects. In the long term it seems that document databases will play a bigger role in building Rails applications.