Rails has a lot of features but the core team is very cautious about adding any new functionality.  Part of what has made it such a good framework is that they don't allow features in that aren't necessary or highly useful.  This means that most of the cool add-ons we'd like to see have to end up as plugins.  And plugins are really hard to make, right?  Well, if you follow along with this tutorial you'll be a plugin author in just a few minutes.

What we're going to do is create a new Rails plugin that allows certain models to specify how they are loaded from the database by default.

The Concept
How things work now:

How things will work after this plugin:

This is in response to an open ticket on the Ruby on Rails dev site.

Things to know for this tutorial:
  - Lines that start with a $ are things you'll need to type into a command line
  - You'll be needing to set up your own databases, everything else will be step-by-step
  - This plugin won't have any built-in testing (that's much more complicated).  We'll be using the application's tests

Lay a Foundation

You just created a rails app and stepped into it.  Now I'll need you to edit your config/database.yml file to point to a valid development database and a valid test database.  You can ignore the production one.

We're going to create a model that we can run our tests on.  To continue the example from above we'll make it a Person model.


Now you've got a model set up.  Go ahead and edit the file "db/migrate/001_create_people.rb" and just copy and paste the following into it:

And now we need to create this model's table in our database:

Now we've got a barebones Rails app.  It won't do much on it's own but it's enough to allow us to build a plugin to modify it.  The next step is to generate a plugin.  It's every bit as simple as it should be.  Because this modifies ActiveRecord and it involves default options I've decided to call it "ar_default_options".  You can be more clever if you like.

The only detail left to do before we get into some code is to hook this plugin up so it's automatically included in our application.  To do this, edit the "vendor/plugins/ar_default_options/init.rb" file to look like this:


Modify the way ActiveRecord Works

Pretty much all of our work will happen in just one file: "vendor/plugins/ar_default_options/lib/ar_default_options.rb".

Open it and copy the following into the file:

Congratulations, you've just opened up the guts of Rails and reached your hand inside. We haven't done anything yet, but it's significant to know that we just opened up one of the most essential pieces of Rails code and we could add ANYTHING we want to it.  Ignore the 'class <<' notation for now.

Now, our goal is to be able to specify certain values that will be used as defaults for the model whenever it calls the 'find' method on a given model.  To do this we'll need some way of storing these values.  But not just storing them any old place; we need to satisfy the following criteria:
  - the values should be set in the class definition before any instances are created
  - the values should be unique for each class/model (i.e. one table's values shouldn't effect another's)

It turns out that there's a specific way Ruby lets us do this.  We're going to use the class's 'singleton class'.  Basically we'll be able to use @-styled variables and set up method definitions that can be used for the class itself - not for instances of the class.  The 'class <<' notation is the way Ruby lets us do this.


There.  We've now got a class method that lets us assign values to any ActiveRecord model and they'll stay put.  Let's try it out (you can type this into irb or just read along):


So we've got the values saved in there.  Now we need to figure out what we're going to do with them.

Since we're trying to emulate the same functionality as when someone calls Person.find(:all, :order => :age) we need some way to throw the information we've collected at the find method.  It turns out that the best way to do that is to create our own find method that jumps in front of the old one.  We're going to re-route all calls to Person.find to our own method. 

Now we run into a different problem.  The last line of our method calls itself!  That would put us into an infinite loop.  So how do we do all that database-y stuff that the original find method did?  Do we have to copy-and-paste the whole original method into ours or is there some way of still getting to the original?

Ruby offers many ways to override or add-on to methods.  We're going to go with a rather odd one that just happens to be the best for what we're doing.  'alias_method' is a way of copying some method to a new name.  It's great for making a backup of methods that we're about to clobber.

There we go, now we've successfully intercepted the call to ActiveRecord::Base.find and we didn't have to reinvent all the clever stuff that Rails does so well.

There's one more (insignificant) thing to do.  If we just redefine 'find' then we won't have any say in how the records are loaded if any of the other find-like variations are used (e.g. Person.find_by_age).  It turns out that all these find-ey methods eventually call the 'find_every' method to do their dirty work.  So that's the one we actually want to overwrite.  And we're going to mark 'find_every' as a private method because that's how it's listed normally.

And that's it!  This is a working plugin that allows you to specify defaults for how ActiveRecord loads records on a per-model basis.  But just to be sure (and because untested code is scary), let's do a little testing.


Testing our plugin using a simple application

Edit the 'test/fixtures/people.yml' file that was created when we generated our model and paste the following into it:

And put the following into 'test/unit/person_test.rb':

And now for the great reckoning, type 'rake test:units' into the command line and see what comes out:

discuss this topic to forum