Customize the Error Reporting for ActiveRecord Forms

When a form in your Rails application is used to edit (or create) an ActiveRecord instance, ActionView uses the ActiveRecordHelper module to create the HTML input field tags. In the event of an error, your input field is wrapped inside a DIV with class=”fieldWithErrors”. This isn’t so bad, but you’re left with few options for customizing the look of your forms when there is an error. For example, what if you wanted to put the error text associated with a field right next to the field?

One way to do this is by putting additional markup in your forms. Something like:

<% if object.errors.on(:some_field) %>
  <span class="error"><%= object.errors.on(:some_field) %></span>
<% end %>
... rest of field markup ...

That works, but you have to repeat the fields at least twice: once for the potential error condition, and once for the field itself.

You could write up a new form helper that includes the boilerplate error markup, but that falls apart as soon as you want to put in a set of checkbox or radio button controls. Maybe you only want one error message for the entire group, which is almost certainly true for radio buttons.

Another alternative that I don’t see widely acknowledged is to override the standard Proc used by the ActiveRecordHelper for errors: ActionView::Base.field_errro_proc. Here’s an example:

ActionView::Base.field_error_proc = Proc.new do |html_tag, instance|
  error_text = ""
  errors = instance.object.errors.on(instance.method_name)
  if errors
    errors.to_a.each do |error|
      error_text << "<p class=\"error\">#{error}</p>"
    end
  end
  "<div class=\"errors\">#{error_text}</div>#{html_tag}"
end

The Proc instance is passed the HTML tag (already built into a string) and an instance of InstanceTag. The latter is the class used by many of the ActionView helpers for building HTML tags that correspond to a particular piece of data in an object. InstanceTag keeps a reference back to that object and method, and you can make use of it in your custom field_error_proc, as shown above.

One little annoyance you don’t see until you start down this path is that the method that builds checkboxes always includes a hidden field with the same name. This is done to ensure that some value for that field is always sent to the server when the form is submitted. The trouble is that the hidden field gets no special treatment from ActiveRecordHelper: field_error_proc is called twice, once for the checkbox field and once for the hidden field, and custom error messaging, as shown above, gets rendered twice. This can be fixed by overriding InstanceTag#tag:

def tag(name, options)
  if object.respond_to?(:errors) && object.errors.respond_to?(:on)
    suppress_errors = (name == "input" && options["type"] == "hidden")
    error_wrapping(tag_without_error_wrapping(name, options),
                   object.errors.on(@method_name) && !suppress_errors)
  else
    tag_without_error_wrapping(name, options)
  end
end

Sparkline graphs using data: URIs

A while back, I ran across sparkline graphs, created by Edward Tufte for displaying data visually in a very compact space, usually inline with text. Google uses these extensively in their Analytics product, and it seemed like a great fit for representing data on the ZingLists administrative dashboard.

There are two easily found implementations of sparkline graphs for Ruby: Sparklines and Bumpspark. Bumpspark is nice because the graphs use data: URIs and don’t require any extra parts server-side, but the Sparklines plugin offers far more drawing options.

Why not the best of both? Here is a modified sparkline_tag method for Sparklines, which accepts a new option, :inline_data. When true, it emits a data: URI instead of a reference back to your server. I like this for several reasons: it loads faster, it doesn’t require a new controller, and it doesn’t require a new route if you’ve done away with the generic /:controller/:action/:id and are using RESTful routes.

require 'base64'
 
  def sparkline_tag(results = [], options = {})
    tag_options = { :class => (options[:class] || 'sparkline'),
                    :alt => "Sparkline Graph" }
    if options.delete(:inline_data)
      tag_options.merge!(:src => "data:image/png;base64,#{Base64.encode64(Sparklines.plot(results, options)).gsub("\n", "")}")
    else
      url = { :controller => 'sparklines', :results => results.join(',') }
      tag_options.merge!(:src => url_for(url.merge(options)))
    end
    tag(:img, tag_options)
  end

Update: When I emailed this to Geoff (who maintains Sparklines), he reminded me that IE doesn’t support data: URIs, so :inline_data isn’t useful if your pages need to display in IE.

Inheritance in ActiveRecord, without STI

One of the few times Rails let me down while developing ZingLists was how it deals with class inheritance in ActiveRecord. Actually, unless you want Single-Table Inheritance semantics, you may as well pretend it doesn’t exist, because I couldn’t find a clean way to do it.

Here was my particular problem:

Out of the box, Rails likes to construct URLs that usually end with a numeric ID when you’re dealing with resources. There is a method, to_param, that the URL helpers call when they want to turn an object into an ID suitable for a URL.

Conventional wisdom says that Google likes URLs that are meaningful. A string of numbers at the end doesn’t mean anything, which is why you often see URLs ending with a snippet from the page title. Blogs often do this (just look at the top of this page, if you’re not reading from the index).

So, to get nice URLs, modify to_param. But what if you only want to do it some of the time? Inheritance usually solves this problem: customize in the derived class. But ActiveRecord forces STI on you if you do this, and maybe you don’t want that.

In ZingLists, I have a single table, lists, that contains all of the lists in the system, whether they are private lists for a member or lists that a member has published to the community. It pretty much has to be this way, since publishing a list does not fix it in time. The member may (and probably will) continue to use it for themselves, and if they add to it, I’d like those changes to be available in the public view immediately, with no extra work.

I want public list URLs to be nice for Google, but don’t have any desire to junk up private list URLs, too. How to solve this problem?

Duck Typing. The URL helpers don’t care what kind of class you hand them, as long as it responds to to_param:

class PublicList
  def initialize(list)
    @list = list
  end
 
  def to_param
    "#{@list.id}-#{@list.name[0..29].tr_s(" ", "-").gsub(/[^-a-z0-9]+/i, "")}"
  end
end

Now, when I want to create a pretty URL for Google’s benefit, I just have to instantiate a wrapper around the real object:

public_list_path(PublicList.new(list))

(Wishful thinking: What would be really neat is a facility where you can get STI-like semantics, but provide your own definition of how to differentiate between the types of object, rather than have it hard-coded to a column called “type” that contains a string representation of the class to instantiate.)

Easier time zone handling in Rails

Update: with the release of Rails 2.1, much of this article is now obsolete.

The application I’m working on at the moment deals with a lot of dates and times, and its userbase could span many different time zones. Dealing with time zones and converting from one zone to another is tedious work, but there are some things you can do to make your life simpler.

First, always think in UTC. If not for daylight saving time, you could probably ignore this rule, but thanks to DST, you can’t. DST takes a relatively simple add or subtract and turns it into a tangle of what-ifs. Some zones don’t observe any daylight saving time rules. The zones that do may change when DST starts and stops from year to year.

Thinking in UTC means storing your times in UTC in the database, without exception. Rails gives you only a little help in this area, with ActiveRecord::Base.default_timezone. It only helps you with created_at/on and updated_at/on. It won’t touch your other timestamp fields.

Bugs often come about by missing little details, and forgetting to get a Time instance in UTC instead of localtime is just the sort of thing I know I’d do eventually. Ruby makes fixing this once easy. Reopen the Time class, and change the behavior of Time.now. Put this in your environment.rb:

class Time
  def self.now_utc
    return now_local.utc
  end
 
  class << self
    alias_method :now_local, :now
    alias_method :now, :now_utc
  end
end

I think this gets you 90% of the way home. The remaining 10% is handling display issues, and Jamis Buck’s TzTime helps immensely with this part. Set TzTime’s zone at the start of each request to the zone of the user making the request, then make life even easier by ensuring you always use a helper for displaying dates and times. Mine looks like this:

def datetime(object, options = {})
  return "argument is a #{object.class}, not a Date or Time" unless object.is_a?(Date) || object.is_a?(Time)
 
  format = if object.is_a?(Date) || options[:date_only] then "%b %d, %Y"
           elsif options[:time_only] then "%I:%M %p"
           else "%b %d, %Y %I:%M %p"
           end
 
  object = TzTime.zone.utc_to_local(object) if object.is_a?(Time) && object.utc?
  return object.strftime(format)
end

To date, I’ve only found one gotcha, and while it was aggravating to find, it was easy to fix. The TMail that ships in Rails 1.2 (as part of ActionMailer) has a nasty habit of ignoring the @sent_on instance variable when sending mail via SMTP. It will always set this header, contrary to what ActionMailer’s RDoc tells you. Unfortunately, it sets the header using Time.now, which returns UTC with the above modification, but marks the time in the local zone. End result: if your localtime is behind UTC, the mail looks like it’s sent in the future. To fix, put this in environment.rb:

class TMail::Mail
  def add_date
  end
end

With this change, TMail will never add a Date: header, allowing the MTA to add it itself.

ActionMailer, Named Routes and Testing

I’ve immersed myself in Ruby and Rails for the last several weeks, working on a project I hope to complete in the next month or so. The other day, I created a new mailer to send a welcome message when a user registers with the site. I’d done a mailer before and written a unit test for it, and was surprised to see the following when I wrote a unit test for the new one:

1) Error:
test_welcome(UserAccountMailerTest):
ActionView::TemplateError: confirm_user_url failed to generate from {:controller=>"users", :email_address_id=>"1", :secret=>nil, :action=>"confirm"}, expected: {:controller=>"users", :action=>"confirm"}, diff: {:email_address_id=>"1", :secret=>nil}


It looks like ActionMailer isn’t happy when a mail template makes use of named routes when run inside the test framework, but that doesn’t make any sense. Here is the route, from routes.rb:

map.confirm_user "users/confirm/:email_address_id/:secret",
:controller => "users",
:action => "confirm",
:requirements => { :email_address_id => /\d+/,
:secret => /\d+/ }


The error seems to say that the routing framework is not parsing my route correctly, and fails to see that :email_address_id and :secret are both requirements for the route (“expected:” specifically excludes those two parameters).

This is one of those times where the error message didn’t help as much as I hope it would. It turns out that the entire problem is because “secret” is a new column, and I hadn’t added it to my fixtures yet. Fixing that fixes the problem, and my test passes.

Usually, the net is amazingly wise and I can find either an answer or a hint in the right direction after a few searches. This time, I had to rely on a “hey, wait a second…” moment.