I’m finding that managing my projects’ code dependencies is smelling worse and worse as time goes on. Code bases get bigger and acquire libraries as they grow; a part of your project sits untouched for a few months and its particulars leave your medium-term memory, and so on.

In Rails, we can freeze lots of stuff to our vendor directories. I do that as much as possible—gems that I only use for Rails apps get frozen to vendor/gems and then uninstalled system-wide; I use the gemsonrails plugin for this. If the little gem bits aren’t necessary, you can just pistonize a repository. Old news.

That’s not going to fly for platform-compiled gems, or even compiled libraries that aren’t gems at all (since you’re possibly running several different platforms between development and production). So I’ve been cooking up ways to keep myself sane:

The Simplest Thing That Could Possibly Work, I think, is just a quick test failure when a dependency is missing. If you’re already autotesting locally, and automatically running your test suite on each production machine as part of your deployment recipe, a quick, obvious exception could save you a little misery.

What I mean by “obvious”

This all came about because I went through two development platform switches recently: first, a clean install of Leopard, and just last week, a move to Intel from my old PowerBook. Both of those hosed my gems, and although I got test failures for each “broken” part of the app, certain libraries’ lazy/quiet-loading techniques don’t raise exceptions in a way that’s obvious.

For example, Rick Olson’s fantastic attachment_fu plugin is meant to work just fine for non-image files, so if you don’t have a compatible image processing library installed, it’ll just skip the thumbnailing for images and move right along. So my image-uploading tests failed on not creating the right number of files and records. It took me way too long to figure out what was going on, so I think it’d be better if I was checking for known dependencies directly.

First try

1
2
3
4
5
6
7
8
9
10
11
12
13
14

describe User do

  it "depends on one of three image processing libraries" do
    processors = %w(image_science RMagick mini_magick)
    lambda {
      begin
        require processors.shift
      rescue LoadError, MissingSourceFile => e
        retry if processors.any? or raise e, "Make sure an image processing library is available"
      end
    }.should_not raise_error
  end

end

Pretty good, although so much space between it and end makes me sad. Also, attachment_fu’s requirements are kind of an edge-case; I want to be able to spec a requirement for only one library, or several all at once.

Less sadness with matchers

Read up: if you aren’t using matchers, you aren’t using RSpec.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

describe User do
  it "depends on an image processing library for attachment_fu" do
    one_of(:image_science, :RMagick, :mini_magick).should be_loadable
  end

  it "depends on SHA libraries for password hashing" do
    both_of('digest/sha1', 'digest/sha2').should be_loadable
  end
end

describe Event do
  it "depends on chronic for date/time string processing" do
    :chronic.should be_loadable
  end
end

describe Post do
  it "depends on a text processing library for Markdown support" do
    either_of(:maruku, :RedCloth).should be_loadable
  end

  it "depends on some XML libraries" do
    all_of(:hpricot, :builder, :haml).should be_loadable
  end
end

The matcher I wrote to do this is a little beefy, around 60 lines. To check it out, you can grab it from svn (or in the <3 warehouse), or from pastie.

I’m now using this all over the place, and it’s saved me at least a couple headaches. It’s really helpful for making sure your CI and deployment environments are up to spec, as well.

I’m sure there’s more to do—like checking gem versions. How are you checking your dependencies from platform to platform?

On a recent project, we decided it would be nice to have “templated attributes” for certain fields in a form. A templated attribute has a helpful initial value—kind of like a default value—except that these aren’t valid data or saved in the database. They’re suggestions to the user about the expected formatting or content of a field.

So the game is:

1. keep these values out of the database
2. specify these values once in the model, super-duper-DRY
3. create a user experience that clearly implies that these values are just templates for valid data

Case one: a website attribute

We wanted a website attribute to be prefilled with http:// as a suggestion to the user about proper URL formatting—most users will just enter “example.com” when prompted for a URL. This is to avoid XSS problems with javascript: URIs and the like, and to keep browsers from resolving short URLs to be internal—nothing quite like being sent to http://yoursite.com/www.theirsite.com.

(Aside: there are better ways to handle this specific situation: a :before_validation callback to fix invalid URLs and check for XSS attacks, or the fantastic white_list plugin. But for now I’m interested in the general case.)

This attribute needed certain behavior:

• When the user hits the form, the field should be pre-filled with http:// if the real value is empty or nil.
• If the field is left as http://, we should convert it to nil before validation.
• Client-side: to imply that the initial value is a suggestion, we’ll make the text color gray until the user makes a change. If the user’s only change is to empty the field, we should reset it to http:// and gray again on blur.

Case two: label attributes

There’s another use case, which you’ve seen before: a text field’s initial value is used as a replacement for its label. When the user clicks in the field, the “label” disappears. My example of this is a phone attribute, where we’d like to suggest a standard US area code format. Something like (123) 555-1234.

We don’t want the user to have to delete our dummy numbers and put in their own; it’s too much work. Instead we think that the reminder will help coax the right format out of the user by itself—so this field gets blanked on focus, unlike the website attribute.

You also see this pattern used for content suggestions instead of formatting hints: for example, search fields and login forms which are space-constrained, like the built-in search in Firefox and Safari.

Get on with the plugin, already

OK, OK. So we have two kinds of templated attributes: those with starting values, which are potentially the start of valid data, and labels, which are just helpful, ephemeral reminders.

Check out the goods:

1
2
3
4

class User < ActiveRecord::Base
  templated_attribute :website, :starting_value => 'http://'
  templated_attribute :phone, :label => '(123) 555-1234'
end

Validations work as expected, since unchanged template values get removed in a :before_validation callback. So you can sprinkle on a little :validates_presence_of and :validates_format_of for a really good time.

There’s also some nice, unobtrusive Javascript you can generate to get the behavior I mentioned above. If you’re using form_for, it’s totally automatic. It gets installed when you install the plugin, or you can install and remove manually with these rake tasks:

1
2

rake templated_attribute:install
rake templated_attribute:remove

To turn off the Javascript for a given templated_attribute—say, because the generated stuff doesn’t jibe with your fancy-pantsy, AJAX-validating, Grey Poupon of a form—just throw :templated_javascript => false in the options hash for text_field or text_area. You’ll have to do any styling and event handling by yourself.

I’d like to make this work for fields other than text_field and text_area; the other contenders were file_field, which we can’t do because the Javascript security model doesn’t let us touch its value at runtime, and password_field, which I haven’t done because showing the template value would require dynamically switching the element to a text_field and back (to avoid all those asterisks). That one’s on the list, though.

Plugin resources

• Browse the code:
  http://railsplugins.code.shiftcommathree.com/browser/templated_attribute
• Generated rdocs (with installation instructions):
  http://docs.shiftcommathree.com/rails_plugins/templated_attribute
• Raw svn action:
  https://svn.shiftcommathree.com/rails_plugins/templated_attribute
• Feed for svn changesets:
  http://railsplugins.code.shiftcommathree.com/changesets.atom