Inferred Routes plugin

for Rails 2.0
==============

DESCRIPTION

This plugin lets you do shorter versions of named nested RESTful
routes.  I've written it because I don't like to have to inline
the objects from which the route elements need to be gleaned, if
those objects can be inferred from ONE object.  

For example: given a nest of routes:

  map.resources :schools do |s|
    s.resources :departments do |d|
      d.resources :teachers
    end
  end

I don't like to have to specify all of the components of the nest,
like this:

  teacher_path(@school,@department,@teacher)

I would rather just do:

  teacher_path(@teacher)

and have the nest be inferred, as if I'd written:

  teacher_path(@teacher.department.school, @teacher.department, @teacher)

Similarly, I'd like a plural route:

  teachers_path(@department)

to be interpreted as:

  teachers_path(@department.school, @department)

I'd even like to "fall off the cliff" and specify a route using
something that isn't technically part of it:

  teachers_path(@teacher)

expanding to:

  teachers_path(@teacher.department.school, @teacher.department)

There's no teacher in the route, but this lets me generate, say, a URL
for creating a new teacher in the same department as a known teacher.

(The variables don't have to be instance variables; that's just for
consistency in the examples.)


HOW IT WORKS

The routing system processes a list of arguments, and a list of route segments.
Usually, you're supposed to provide one argument for each segment that has
to be matched. The plugin figures out that if the argument list is shorter than
the segment list, then it should be padded by asking for associated objects.

You should be aware of the fact that this potentially involves database hits
from the view, which some people strongly dislike. (I take a kind of soft
dislike approach to it.) 


USAGE

SINGULAR:

  a_path(z,y,x,...c,b,a)

becomes:

  a_path(a)

and z,y,x...c,b will be inferred.  The nest has to match the object
associations; that is, all of these must be present:

  a.b      == some_b
  some_b.c == some_c
  ...
  some_y.z == some_z 


PLURAL:

  as_path(z,y,x,...b)

becomes:

  as_path(b)

You can also use an 'a':

  as_path(a)

and the b-object will be gleaned from the a.  The cascade of object
associations has to work all the way through the list.  


LIMITATIONS

The plugin doesn't handle cases where a routing segment might not have
the same name as an association; it just dumbly walks through the segments
and calls the same-named methods on the objects as it goes. 

It also doesn't work with form_for. At least, my brief experiments suggest
that it doesn't. I haven't investigated that part fully. 

In general, the plugin is simple and partial and somewhat experimental. You
should keep this in mind, and make sure you're happy with what it's doing, if
you want to use it. 


TESTING

See test/inferred_routes_test.rb. It uses an sqlite3 database and contains
everything it needs to create the database, create some objects, and test
some routes. 


BUGS

I don't know of any, but there may well be some. Please report any bugs or
improvements to me.  Thanks.


AUTHOR

inferred_routes is by David A. Black, Director of Ruby Power and
Light, LLC.  dblack@rubypal.com, http://www.rubypal.com


VERSION

This is inferred_routes version 0.2.0, April 2008. 


COPYRIGHT AND WARRANTY

See file "MIT-LICENSE"