* Original code Copyright (C) 2007 Dimitrij Denissenko
* Rails 2.3.2 support added by Russ Johnson (russ@angry-fly.com)
* Full :include_blank support added by Corey Ehmke (www.idolhands.com)
* http://angry-fly.com
* http://www.dvisionfactory.com
* http://www.idolhands.com
* git://github.com/russjohnson/related_select_forms.git
* Please read LICENSE document for more information.

This plugin adds a new helper to the Ruby on Rails framework that simplifies 
the creation of multiple, dependent HTML select tags.

It handles the relations with simple JavaScript (requires prototype.js library),
so you do not need to code any AJAX callbacks-- handy when you only deal with a
small amount of data.

This plugin works also well with RJS templates and supports recursive
pre-selection of the related select tags (see the examples).

The usage is trivial. First create a usual select (or collection_select) which
will act as "parent". Afterwards you can create one or many dependent 
child select(s) by calling:

    related_collection_select(
        object, method, parent_select_tag, collection, 
        value_method, text_method, reference_method, 
        options = {}, html_options = {})

=== Arguments:

* 'object', 'method', 'collection', 'value_method', 'text_method', 
  'options' & 'html_options' are used exactly the same way as in
  the standard collection_select helper method. 
* 'parent_select_tag' specifies, as the name says, the parent 
  select tag; argument can be passed as an array 
  [:parent_object, :method] or directly as string referencing the 
  tag id (e.g. "parent_object_method")
* Parameter 'reference_method' specifies the method that is used to get
  a reference to parent selection.
  
Additionally the 'options' argument can include a ':selected' attribute,
that will override the default pre-selection behaviour (which uses to call 
'@object.method' to determine the to be selected option).

You can also pass an :include_blank attribute consisting of true, false (default), a string, or a two-element array, just like the standard Rails select form helper. If you do not set this attribute, the related select will default to the first option.

=== Example:

<b>Models</b>

  class Metro < ActiveRecord::Base
    has_many :areas
  end
  
  class Area < ActiveRecord::Base
    belongs_to :metro
    has_many :neighborhoods
  end
  
  class Neighborhood < ActiveRecord::Base
    belongs_to :area
  end

  Just looking at the models it should be plain to see how the selects should be related. You must first select a Metro, then that will populate the Areas. Once you select the area, that will populate the Neighborhoods.

<b>View</b>

  Normally this would take a lot of handwritten Javascript to accomplish. And I know there are probably some super simple jQuery plugins for this thing, but this application is using the standard Prototype/Scriptaculous combo that ships with Rails.

  So here is the how simple the form fields are using the plugin:

    <%- form_for(@sales_contact) do |f| -%>

      <%= f.label :metro_id, '', :class => 'title' %>
      <%= f.collection_select :metro_id, Metro.find(:all, :order => "name"), :id, :name, :include_blank => 'Select a Metro %>
  
      <%= f.label :area_id, '', :class => 'title' %>
      <%= related_collection_select(:sales_contact, :area_id, [:sales_contact_metro, :id], Area.find(:all,:order => "area" ), :id, :area, :metro_id, :include_blank => 'Select an Area') %>
  
      <%= f.label :neighborhood_id, '', :class => "title" %>
      <%= related_collection_select(:sales_contact, :neighborhood_id, [:sales_contact_area, :id], Neighborhood.find(:all,:order => "title"), :id, :title, :area_id, :include_blank => 'Select a Neighborhood') %>

      ...
    
  Notice the first select is a standard collection_select, then for each related field we make calls to the plugin. The method signature is very similar to the standard collection_select with the addition of a couple of parent-related arguments.