But the answers are spread out and distributed randomly. Plus, I can only see “The program ‘______’ is currently not installed. You can install it by typing: sudo apt-get install ______” so many times before I lose interest and put off the task.

So, to prevent future headaches and help all of us out, I put together a how-to that can take a new Rails system from zero to code in a few minutes (depending on network speed) instead of half a day. With no further ado,

Setting up an Ubuntu box for Rails Development (including virtual machines)

Update everything

$ sudo aptitude update && sudo aptitude dist-upgrade

Install necessary packages

$ sudo aptitude install build-essential vim \
  vim-runtime git-core subversion libsqlite3-dev

We have projects in git (the newer ones) and svn, so we have to be able to switch fluidly between the two.

And I’m not trying to start a flame war, but Vim is the first choice for Rails development. You don’t have to take my word for it; Jamis Buck, Tim Pope, and Adam Lowe all say the same. I recommend the NERDTree, FuzzyFinderTextMate, BufExplorer, and rails.vim plugins if nothing else.

Install ruby

$ sudo aptitude install ruby1.8 ruby rdoc ruby1.8-dev \
  libpgsql-ruby1.8 libmysql-ruby1.8 irb libopenssl-ruby

Get rubygems from source. http://docs.rubygems.org/

$ wget http://rubyforge.org/frs/download.php/60718/rubygems-1.3.5.tgz

$ tar xzvf rubygems-1.3.5.tgz

$ cd rubygems-1.3.5

$ sudo ruby setup.rb

$ sudo ln -s /usr/bin/gem1.8 /usr/bin/gem

$ sudo gem update --system

Update ~/.gemrc (at least the :sources: chunk)

---
gem: --no-ri --no-rdoc
:benchmark: false
:verbose: true
:backtrace: false
:update_sources: true
:sources:
- http://gemcutter.org
- http://gems.rubyforge.org/
- http://gems.github.com

Install and setup Passenger (optional)

$ sudo apt-get install apache2-prefork-dev

$ sudo gem install passenger

$ sudo passenger-install-apache2-module

and follow the instructions passenger gives you. Most folks in the office run some form of an Apache-Passenger stack for development purposes. I can explain how that setup works in a future post.

Install geminstaller

$ sudo gem install geminstaller

Almost all of our legacy projects use geminstaller to manage gem dependencies. In the future, new projects will be moving to Bundler, but legacy projects matter and upgrading subsystems is not always justified.

“If it ain’t broke, don’t fix it” and the corollary: “because you probably won’t be able to bill it to the client” both apply.

Install common packages (optional, may be required by projects)

$ sudo aptitude install imagemagick

$ sudo gem install utility_belt open_gem redgreen

The first (imagemagick) is used by the Paperclip gem to manage files attached to Rails models. The second are tools that make Rails development more manageable on the command line. I highly recommend them. Besides, I’ve been sneaking redgreen in as a test dependency on our projects, so if you’re a developer here you’ll have to install it anyways.

Create an ssh key (follow instructions)

$ ssh-keygen

EXAMPLE PROJECT

All the stuff above won’t let you test-code-deploy without hassles, so here’s a sample run through of what the last mile of project-specific setup looks like.

Get the project. SVN, Git, whatever. Go to it.

$ svn co rails-project

$ cd rails-project

Run geminstaller

$ sudo geminstaller                                 # normal

$ sudo geminstaller -c config/test/geminstaller.yml # test env

Install necessary aptitude packages

$ sudo aptitude install texlive-latex-base

Don’t ask.

Create the test database

Mysql:

$ rake RAILS_ENV=test db:create

Postgres (using your username or DB username in place of “username”):

$ sudo -u postgres psql

postgres=# CREATE USER username SUPERUSER;

postgres=# CREATE DATABASE username OWNER username;

If you get an error regarding PGconn.quote_ident (Rails 2.3.x on Ubuntu 8.04) patch activerecord-2.3.4/lib/active_record/connection_adapters/postgresql_adapter.rb and add the following:

def PGconn.quote_ident(name)
  %("#{name}")
end

immediately after the “class PGresult” definition at the top of the file. Once that’s all done, the following:

$ rake RAILS_ENV=test db:create

$ rake RAILS_ENV=test db:schema:load

$ rake RAILS_ENV=test test

should work.

go have fun, write code, blow our minds

So that’s how we roll. Awkward requirements will still crop up as we pick up new projects (or very old projects) so you’ll always need a bit of apt/gem fu to get you through the day. Leave questions here or drop me a line at adam@smartlogicsolutions.com or http://twitter.com/abachman.

require 'lib/some_rake_file' # or require 'lib/some_rake_file.rake'

=> rake aborted!
no such file to load — /home/your_project/lib/some_rake_file

Rake assumes the ‘require’d files end in .rb, so it won’t find your .rake files. You need to import rake files:

import 'lib/some_rake_file'

This is fine for individual files, but I wanted to include all files that end in .rake in my tasks dir:

Dir.glob('tasks/*.rake').each { |r| import r }

…and there you go. While dead simple, this exemplifies an important distinction between require and import that I found to be poorly documented. Keep your rake tasks organized and remember that Rake isn’t just for rails apps!

Slow-Actions is great tool for determining the slow areas of a rails application. Since it is built on a rails log parser, it can be used for many other things. For example, here is some standard output from slow-actions when you want to know the speed of different user sessions within a specific date range:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01
           Cost    Average Max
+ ece0e17b48a5fe0fc766fa42f199fb66 (51 entries, 58% Error)
| Total:   2883.262 732.948 3100.00
| Render:  0.00000 0.00000 0.00000
| DB:      55.8220 14.1900 99.0000 

+ e1181ad94b34b41aff2a74ee62d5fb57 (10 entries, 30% Error)
| Total:   1563.912 676.276 1426.00
| Render:  0.00000 0.00000 0.00000
| DB:      14.5350 6.28500 19.0000 

+ 867bc340e6d65e673f29c57189feaf2b (133 entries, 0% Error)
| Total:   1083.138 221.450 386.000
| Render:  0.00000 0.00000 0.00000
| DB:      44.2030 9.03700 90.0000 

Etc...

Now, if we grep for “entries” we get a line for each session:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01 | grep entries
+ ece0e17b48a5fe0fc766fa42f199fb66 (51 entries, 58% Error)
+ e1181ad94b34b41aff2a74ee62d5fb57 (10 entries, 30% Error)
+ 867bc340e6d65e673f29c57189feaf2b (133 entries, 0% Error)
+ 99b39c7a9af55fc01056b5f127dc4c98 (75 entries, 0% Error)
+ 6ee15c4f3bc804ac68e9e868d9c3f7e6 (14 entries, 0% Error)
+ 80928c25c83590c4f89b91f8d4c8896d (9 entries, 0% Error)
+ c78cfa1cb086b3f473015b212ca3da11 (12 entries, 0% Error)
+ 48cd02cf6544493077c84eb16821bda2 (3 entries, 66% Error)
+ ac027817dcf87d473efb54cd737b2a80 (2 entries, 0% Error)
+ dff2ca2678852b06bbb6c7ca0a85b0a9 (1 entries, 0% Error)
+ 08ed3bc031c23bd3b2572ef7ce60d066 (1 entries, 0% Error)

Pipe that to word count, and we have the number of unique sessions within a specified time period:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01 | grep entries | wc -l
11

On a 54m log file, that takes only 0.761s!

Not long ago I stumbled upon Peter Boling’s plugin implementation of sanitize_email. I’ve since forked it, turned it into a gem, and continued to apply maintenance commits to it as rails has marched forward through versions 2.2 and 2.3.

The primary value sanitize_email provides is that it allows you to reroute all email without having to alter any application code. It’s environment-specific and doesn’t introduce any production/deployment dependencies.

Installation

To install, simply execute:

  $> sudo gem install sanitize_email

Use Cases

There are three primary use cases for sanitize_email.

Working Locally with Production Data

Scenario: you have a mechanism for recreating your production environment in your development environment (capistrano-extensions provides this capability for MySQL databases). You want to pull down the production data to troubleshoot a live email issue. Using sanitize_email, we can set up our dev environment to override all email envelopes so that email actually goes to an inbox of your choice.

Re-routing Email on a Staging or QA Server

During initial development of a new email feature, it’s imperative that the client/stakeholder be able to review all emails being generated. sanitize_email makes it dead simple to specify that your staging environment route all email generated to a specific email address without having to change any application code.

Testing Email from a Hot Production Server

You can install sanitize_email on your production server, and then utilize it from the console to give you more freedom when poking and prodding your application. You can trigger any email you need to without fear that it will go to a real live email address.

Sample Usage of sanitize_email

sanitize_email uses ActionMailer::Base.local_environments to specify in which environments to override the SMTP envelope. Note that a set of defaults can be configured in an initializer file, and then overridden in specific environment files for further control.

    # Settings for sanitize_email gem.  These can be overridden in individual config/%env%/environment.rb files.
    require 'sanitize_email'
    ActionMailer::Base.sanitized_recipients = "john@smartlogicsolutions.com"
    ActionMailer::Base.sanitized_bcc = nil
    ActionMailer::Base.sanitized_cc = nil

    # These are the environments whose outgoing email BCC, CC and recipients fields will be overridden!
    # All environments not listed will be treated as normal.
    ActionMailer::Base.local_environments = %w( development test staging )

Closing Notes

The functionality provided by sanitize_email is truly very basic, and admittedly a little static. You can only set a single override for any given environment, which doesn’t lend itself to a QA/review team that consists of more than a single person. I have been working on rails-caddy which is a tool for bringing a lot of QA goodness to the browser. One feature it provides is an integration with sanitize_email, allowing these overridden email addresses to be set on a per session basis, which in turn allows several individuals to work on a staging server at the same time and each receive the email that their own actions triggered. It’s still in its early stages (pre 0.1.0 release), but it’s something we’re using on several apps already.

Related Links

RDoc | Source on GitHub

  sudo gem install environmentalist

The only substantial change in this release is that we moved the loading of postboot.rb to the bottom of the boot.rb file as opposed to the top of config/environment.rb. This was necessary because common db rake tasks like db:create and db:drop stopped loading the environment in 2.3.2.

As a recap, environmentalist provides an executable that converts a rails app’s config structure. The basic idea is that environments themselves are now first-class citizens, allowing you to create several environments (e.g. staging, prodtest, demo, etc.) in a clean, organized fashion. Each environment is given its own folder where it can store its own set of configuration files (think mongrel configs, apache configs, etc.) without polluting the top-level config/ directory.

Let me be the first to admit that there’s no one right way to do things. In fact, I’m writing this post particularly because I have a few objections to how this functionality is ultimately exposed, and I’d like to hear arguments from those who disagree. In other words, let me acknowledge the possibility that I am the misguided one.

Review of Nested Object Forms

As a quick review, we can now prepare our models for nested object mass assignment:

class Person < ActiveRecord::Base
 
  validates_presence_of :name
 
  has_many :children
  accepts_nested_attributes_for :children
    # can also be used on has_one etc.. associations
 
end
 
class Child < ActiveRecord::Base
  belongs_to :person
end

We specify which nested relationships can be passed in via mass assignment using the accepts_nested_attributes_for() function. Continuing the example, we can now execute the following to actually save a person and two children at the same time:

person = Person.create!(:name => 'George', :children_attributes => {"new_1" => {:name => 'Amy'}, "new_2" => {:name => 'Stephanie'}})

For full disclosure, my console session from start to finish:

john-mbp:playground john$ rails -v
Rails 2.3.0
john-mbp:playground john$ rails anewapp
...
...
john-mbp:playground john$ cd anewapp/
john-mbp:anewapp john$ ruby script/generate model person name:string
...
john-mbp:anewapp john$ ruby script/generate model child name:string person_id:integer
...
 
# edit app/models/person.rb as above
# edit app/models.child.rb as above
 
john-mbp:anewapp john$ rake db:migrate
(in /Users/john/playground/anewapp)
==  CreatePeople: migrating ===================================================
-- create_table(:people)
   -> 0.0044s
==  CreatePeople: migrated (0.0046s) ==========================================
 
==  CreateChildren: migrating =================================================
-- create_table(:children)
   -> 0.0041s
==  CreateChildren: migrated (0.0045s) ========================================
 
john-mbp:anewapp john$ ruby script/console 
Loading development environment (Rails 2.3.0)
>> person = Person.create!(:name => 'George', :children_attributes => {"new_1" => {:name => 'Amy'}, "new_2" => {:name => 'Stephanie'}})
=> #<Person id: 1, name: "George", created_at: "2009-02-24 00:49:21", updated_at: "2009-02-24 00:49:21">
>> person.children
=> [#<Child id: 1, name: "Amy", person_id: 1, created_at: "2009-02-24 00:49:21", updated_at: "2009-02-24 00:49:21">, #<Child id: 2, name: "Stephanie", person_id: 1, created_at: "2009-02-24 00:49:21", updated_at: "2009-02-24 00:49:21">]
>> person.children.size
=> 2

Pretty cool, huh? I agree. I think this is fantastic, and with the integration with fields_for, it will really ease a lot of the pain that previously existed with multi-model forms.

This said, I’ve got a few major bones to pick with how it’s implemented.

So What’s Wrong?

The primary issue is the fact that this functionality is statically defined (in that you can’t turn it on/off in specific scenarios). Why is this an issue? Well, this is a potentially dangerous functionality to expose everywhere. Let’s say that you wanted to take advantage of this new feature to allow administrators to create new accounts that came pre-loaded with a complementary $X credit to their accounts. So you built a form for admins to fill out that included a fields_for :credits to achieve this single-form implementation of an account with credits. Now, in order to avail of this, I need to turn on the nested mass assignment.

class Person < ActiveRecord::Base
  has_many :credits
  accepts_nested_attributes_for :credits
end
 
class Credit < ActiveRecord::Base
  belongs_to :person
end

Wait….I’ve just turned this feature on globally…..I can’t just make it available at the controller level? But isn’t the controller where I define authorization, who can edit/update/create what? Precisely.

So….unless I want to go old school and rewrite this all by hand, anytime I want to render a person form (e.g. on an “Edit My Profile” link for authenticated users), I need to recall that I’ve exposed myself to a possible POST data hack (anyone who understands this feature in rails will know how to handcraft the POST data). This is a fairly ridiculous thing to expect on a project of any nontrivial size.

However, there’s another way around this issue. Rather than rewriting all of the multi-model form stuff by hand, I could simply ward off the extra parameters at the controller level, e.g.

class ProfileController < ApplicationController
  before_filter :remove_nested_params
 
  def update
    @user = User.find(current_user.id)
    @user.update_attributes!(params[:user])
    redirect_to profile_path
  rescue
    render :action => 'edit'
  end
 
  protected
    def remove_nested_params
      params[:user].delete(:credits)
    end
end

This works fine in isolation or for a one-off, but again, this is a piece of information that is going to be lost as the project trudges along. Your team will forget this, and someone is going to forget to “close the hole” when adding that new “quick edit profile” form that only shows their email address and display name.

Counter Suggestions

I would advocate any solution where this behavior was pushed out to controllers. That said, I don’t have an airtight procedure planned out. I will, however, leave you with a few suggestions.

We could implement it around_filter style where the feature is enabled/disabled in an around_filter. The primary benefit of this approach would be that the majority of the code could probably stay put in ActiveRecord. We’d just need to expose hooks to turn it on/off. Then we could define a controller-level meta-function (e.g. filter_parameter_logging) that could set which actions to apply the behavior on, or which models can be nested. The syntax could look like:

class ProfileController < ApplicationController
  allow_nested_assignment_for User, [:children], :only => [:update]
end

I’ll be perfectly honest in that I don’t love this suggestion. It incorrectly scopes this authorization tweak to the whole action and any before/after filters that execute in between it (still leaving holes, albeit smaller) as opposed to scoping it directly to the single save! action that we really want to special-case. If we perhaps exposed a separate save_with_nested() function, then we could isolate the scope down to the specific call. Needless to say, I doubt this is a course of action rails would take, and it’s not one I would advocate.

Another alternative would be to keep the functionality as is, but then allow you to override or extend it at the controller level (a la my initial suggestion). This would allow developers to avail of the benefits in the less-risky areas, and then conditionally avail of them in more risky areas by simply turning it on for specific controller/action combos. In this case, we’d define a basic harmless nested assignment baseline in the model, and the more risky nested assignment in those controllers where we wanted to isolate it, e.g.

class Person < ActiveRecord::Base
  has_many :children
  has_many :credits
  accepts_nested_attributes_for :children
end
 
class Admin::PeopleController < ActiveRecord::Base
  allow_nested_assignment_for User, :credits, :only => [:create, :update]
end

The primary benefit of an approach like this is that it aligns properly to a developer’s train of thought. When you go to add a trivial feature, you don’t think “I need to close that gap my unrelated nontrivial feature added for me.” However, when you go to add a nontrival feature (like allowing an admin to auto-create credits in their new account form), you do think “what do I need to differently?” In the former case, the developer thinks his new feature is trivial, and doesn’t expect to have do anything exceptional for it. In the latter case, the developer thinks his new feature is nontrivial, and will think about it from a “what extra work does that mean for me?” standpoint.

Closing Thoughts

One of the biggest things that worries me is that no one is talking about this. The whole community requested this feature, and at this point it has received quite a bit of fanfare. But there are some clear ways to accidentally screw yourself that just aren’t being mentioned as caveats.

To be entirely blunt, I just feel like this is plugin material at this point. Though I commend rails for opening up its feature set to a community vote, I fear that we may have misstepped with this feature in particular. I’m very curious to hear what others think. (Be gentle with the flame)

The Problem

First, let’s dive into the error itself. This error message occurs when you call to_sym on an empty string:

john-mbp:trunk john$ irb
>> "".to_sym
ArgumentError: interning empty string
	from (irb):1:in `to_sym'
	from (irb):1

Now that we know what’s up, let’s dig into my stack trace.

The cause of this bug is the fact that my newest build added an aasm_state column to the School model, but my migration did not properly default schools to a particular state. As such, when an instance of the model was asked for its state, the AASM codebase raised an error. And this occurred on every page because I was rendering a link to a school in a common layout.

The Solution

After the fact, in SQL:

UPDATE schools SET aasm_state = 'active';

Or better yet, before the fact, in my migration:

def self.up
  add_column :schools, :aasm_state, :string
  School.reset_column_information
  School.update_all("aasm_state", "active")
end

The Lesson

Don’t forget that there’s a difference between a migration for a yet-to-be-deployed application and a live running application. Live apps require you to take into account that data already exists.

Expected response to be a <:redirect>, but was <500>
<"No HTTP_REFERER was set in the request to this action, so
redirect_to :back could not be called successfully. If this
is a test, make sure to specify
request.env[\"HTTP_REFERER\"].">

What a lovely error message to send me on a goose chase trying to set HTTP_REFERER directly on the @request as instructed.

Did Not Work

@request.env["HTTP_REFERER"] = '/'
post upload_path, { :file => fixture_file_upload("worddoc.docx", "application/msword") },
  { :html => {:multipart => true} }
assert_redirected_to '/', 'index'

This continued to spit out the same error. I finally stumbled across a post back from 2006 that held the answer. The HTTP_REFERER is not set the same way in an integration test:

Success!

post upload_path, { :file => fixture_file_upload("worddoc.docx", "application/msword") },
  { :html => {:multipart => true}, :referer => '/' }
assert_redirected_to '/', 'index'

Hope that saves anyone else some time if you encounter this error.

This past weekend I released v0.1.0 of the Timecop gem. Timecop makes it dead simple to travel through or freeze time for the sake of creating a predictable and ultimately testable scenario.

The gem is derived from a plugin I wrote a while back to achieve more or less the same functionality for an extremely time-sensitive application. My goals for the gem included:

1. Drop-in-ability: The primary goal is to allow your app to continue to use Time.now, Date.today and DateTime.now as normal within your application. No overloading of functions with optional arguments (a la today=Date.today) just so you can write test cases.
2. Environment independence: I wanted the gem to work (a) w/ rails (ActiveSupport actually), (b) w/ plain ruby when the ‘date’ library has been loaded, and (c) w/ plain ruby when the ‘date’ library had not been loaded.
3. Library independence: I could have utilized mocha to achieve the mocking functionality found under the hood, but because I wanted this to work with plain vanilla ruby, libraries like mocha are out.
4. Short-term time travel: I wanted to expose the ability to temporarily change the concept of “now.” This is particularly helpful when writing tests where time needs to pass.
5. Long-range time travel: I wanted to expose the ability to change the concept of “now” for an indeterminate period of time. This is particularly helpful when setting up a rails test environment along with the test data.
6. Nested time travel: I wanted to provide the ability to nest traveling, allowing the state to be kept within each block (we’ll see an example later).

The gem is hosted on RubyForge and can be installed by simply running:

sudo gem install timecop

Using Timecop

The most basic example is to utilize this within a test. Consider the following test case:

require 'timecop'
require 'test/unit'
 
class MyTestCase < Test::Unit::TestCase
  def test_mortgage_due_in_30_days
    john = User.find(1)
    john.sign_mortgage!
    assert !john.mortgage_payment_due?
    Timecop.travel(Time.now + 30.days) do
      assert john.mortgage_payment_due?
    end
  end
end

What’s nice about this API is that the #travel function will take several different object types. You can pass a Time instance, a Date instance, a DateTime instance, or individual time parameters (the same arguments Time.local()) takes. Also, if you’re a big fan of the chronic gem, then you can easily combine these two:

Timecop.travel(Chronic.parse('this tuesday 5:00')) do
  # test-fu
end

For some applications, you may find it useful to completely re-base the concept of “now” for your test environment. Whenever time-sensitivity is a major priority for your application (e.g. an ordering and delivery system, or any system that encapsulates the concept of “availability” at a particularly fine-grained level) , you may find it useful to “root” your test data at a particular point in time, allowing you to write very specific tests that don’t fall victim to the unstoppable march of real time.

To achieve a static date for your entire test environment, you can simply drop the following into config/environments/test.rb (or config/test/environment.rb if you use environmentalist):

# Setting "now" to May 15, 2008 10:00:00 AM
Timecop.travel(Time.local(2008, 5, 15, 10, 0, 0))

This will cause your whole application to run at a static time. As mentioned previously, this is particularly important for creating static test cases. You may think that you can achieve this by always using relative times, but this proves much more difficult than initially perceived. For example, let’s consider the following scenario, which is an extension of the mortgage example beforehand. Let’s say the business rule is that a mortgage payment is due every month on the same date as the lease is signed, except for when that day falls on a weekend, in which case the payment would be due the following Monday. As such, it’s extremely crucial for us to write a test case where we know the date in the next month falls on a weekend, and a separate test case where the date in the next month falls on a weekday. As such, there are certain months where the following test (not using Timecop) would fail:

require 'test/unit'
 
class MyTestCase < Test::Unit::TestCase
  def test_mortgage_due_in_30_days
    john = User.find(1)
    john.sign_mortgage!
    assert !john.mortgage_payment_due?
    assert john.mortgage_payment_due?(Chronic.parse("1 month from now"))
  end
end

Furthermore, you’ll notice I had to pass a date to the mortgage_payment_due? function, essentially requiring me to change the signature of that function to take an optional date argument. Basically, in order to test my application, I’ve had to go ahead and change my actual code! Something clearly smells here. Another option would be to use mocha to mock Time.now. However, mocha has its own limitations with its inability to unmock. Lastly, specifically mocking Time.now would leave us high and dry if our implementation decided to start using DateTime.now for comparison in lieu of Time.now.

Another feature that I want to illustrate is the ability to nest #travel commands. The following assertions will all pass:

   # this test is taken directly from the test/test_timecop.rb
  def test_recursive_travel
    t = Time.local(2008, 10, 10, 10, 10, 10)
    Timecop.travel(2008, 10, 10, 10, 10, 10) do 
      assert_equal t, Time.now
      t2 = Time.local(2008, 9, 9, 9, 9, 9)
      Timecop.travel(2008, 9, 9, 9, 9, 9) do
        assert_equal t2, Time.now
      end
      assert_equal t, Time.now
    end
    assert_nil Time.send(:mock_time)
  end

Lastly, Timecop handles the scenario where exceptions are raised within the blocks passed to the #travel function.

  # this test is taken directly from the test/test_timecop.rb
  def test_exception_thrown_in_travel_block_properly_resets_time
    t = Time.local(2008, 10, 10, 10, 10, 10)
    begin
      Timecop.travel(t) do
        assert_equal t, Time.now
        raise "blah exception"
      end
    rescue
      assert_not_equal t, Time.now
      assert_nil Time.send(:mock_time)
    end
  end

Timecop is useful both in small and large consumption. Just as mocha can be helpful to give you a quick mock here and there, Timecop can help guide you very easily through testing the few time-sensitive parts of your application. And for those unique applications where everything is time-sensitive, Timecop gives you a very simple way to stabilize your concept of now.

The Options Hash

The most obvious way to change the output is to use the options hash outlined in the docs. A short list of options you might want to explore is:

• except => [:attr1, :attr2] — excludes attributes in array from output
• only => [:attr1, :attr2] — output contains only the specified attributes
• include => [:assoc1, :assoc2] — calls to_xml on the given first level association and nests it in the output
• methods => [:meth1, :meth2] — adds a tag to output in the format <method-name>[method output]</method-name>

Usage is incredibly simple:

  # grab xml for a record and its child
  my_record.to_xml(:include => :child)
 
  # same, but only output the ids and names (assuming both have these attributes)
  my_record.to_xml(:only => [:id, :name], :include => :child)

Behold, the Builder

A fantastic feature of to_xml that Ryan blogged about last year is that it yields the builder, thus allowing you to add arbitrary tags into the output. What’s more is you can pass the builder into another object’s to_xml method inside the outer block and produced nested xml.

For example:

  # Arbitrarily insert a tag
  my_record.to_xml do |xml|
    xml.some_tag some_value   #=> <some_tag>some_value</some_tag>
  end
 
  # I want to get xml for my record and all its children
  my_record.to_xml do |xml|
    my_record.children.each{|child| child.to_xml(:builder => xml, :skip_instruct => true)}
  end

You can nest as deep as you want without overriding a model’s own to_xml method:

  output = my_record.to_xml do |xml|
    my_record.children.each do |child|
      child.to_xml(:builder => xml, :skip_instruct => true) do |fxml|
        child.grandchild.to_xml(:builder => fxml, :skip_instruct => true)
      end
    end
  end

deep_xml: Model methods that utilize (but do not overwrite) to_xml

I chose to write methods in the models that handled including the children’s xml such that a single call to my_record.full_xml would produce nested xml automatically. Notice how the builder is being passed to the children, it’s important!

  class ParentClass < ActiveRecord::Base
    has_many :children
 
    def deep_xml(builder=nil)
      to_xml(:builder => builder) do |xml|
        children.each{|child| child.deep_xml(xml)}
      end
    end
  end
 
  class Child < ActiveRecord::Base
    belongs_to :parent
    has_one :grandchild
 
    def deep_xml(builder=nil)
      to_xml(:builder => builder, :skip_instruct => true) do |xml|
        grandchild.to_xml(:builder => xml, :skip_instruct => true)
      end
    end
  end
 
  class Grandchild < ActiveRecord::Base
    belongs_to :child
  end
 
# Now the call is simple:
Parent.firstdeep_xml #=> custom xml for a parent that includes its 
                        #   children and their grandchildren (1 each in this case)

There’s not much to it, but I found this solution to be nice shorthand that cleaned up ugly nested to_xml blocks I was writing over and over. I call my_record.deep_xml from any layer of the family tree and return a nice drill down of data to the leaf children. It’s great if you’re working with a complicated database and need to be able to present your data in xml.

If you are so inclined…

If you really need to, you can just overwrite the to_xml method in the model. While fine to do if you know you’ll always want that one specific template, I avoid it as much as possible and won’t cover it since examples are all over the blogosphere. Why not just make a separate function to avoid producing unexpected results for someone else who joins your project later on?