dependent_select 0.6.5

data/README.rdoc

@@ -0,0 +1,183 @@
+
+=dependent_select
+
+This package extends rails with some helpers that allow "selects that update dynamically 
+depending on other fields"
+
+Demo application can be found in http://github.com/splendeo/dependent_select
+
+Mailing list on http://groups.google.com/group/dependent_select/
+
+==Quick example: Store with country and province
+  
+On your layout:
+    <%= javascript_include_tag :defaults %>
+    <%= dependent_select_includes %>
+
+On your new/edit views:
+
+    <% form_for :store do |f| %>
+      Country:<br/>
+      <% f.collection_select :country_id, @countries, :id, :name, :include_blanks => true %> <br />
+      Province:<br/>
+      <% f.dependent_collection_select :province_id, @provinces, :id, :name, :country_id, :include_blanks => true %> <br />
+      City:<br/>
+      <% f.dependent_collection_select :city_id, @cities, :id, :name, :province_id, :include_blanks => true %> <br />
+    <% end %>
+    
+In order for this to work properly, the Store model must have methods for +country_id+ and +store_id+.
+The best way I've found for implementing this is by using +delegate+. So the model would be:
+
+    class Store < ActiveRecord::Base
+      belongs_to :city, :include => [{:province => :country}] #useful to preload these
+      delegate :country, :country_id, :country_id=, :to =>:city
+      delegate :province, :province_id, :province_id=, :to =>:city
+    end
+  
+Notice that I've delegated the country to the city - so the city should probably have another +delegate+ line:
+    
+    class City < ActiveRecord::Base
+      belongs_to :province, :include => [:country] #again, useful but not needed
+      delegate :country, :country_id, :country_id=, :to =>:province
+    end
+    
+Finally, the controller might look like this:
+  
+    class StoresController < ApplicationController
+      before_filter :fill_selects :only => [:new, :edit, :update, :create]
+      
+      {...} # Standard scaffold-generated methods
+      
+      protected
+      def fill_selects
+        @countries = Country.find(:all, :order => 'name ASC')
+        @provinces = Province.find(:all, :order => 'name ASC') # all provinces for all countries
+        @cities = City.find(:all, :order => 'name ASC') # all cities for all provinces
+      end
+    end
+    
+This will generate a regular +collection_select+ for the country and a +dependent_collection_select+
+for province. The later will be a regular +collection_select+ followed by a js +<script>+ tag that:
+* Will create an array with all the provinces. (+var array=[province1, province2...];+)
+* Will place a listeners on the +country_id+ +select+ in order to update the provinces select if
+    the countries select is modified
+* Fill up the provinces select with appropiate values.
+
+*Note that this will not work if you haven't followed the installation procedure - see below*
+  
+There's a more complex example at the end of this document.
+  
+==Installation
+
+===As a gem
+Copy this on config/environment.erb, inside the gems section
+    config.gem "splendeo-dependent_select", :lib => 'dependent_select', :source => "http://gems.github.com"
+Then execute
+    rake gems:install
+
+The first time you initialize your server after this (presumably with script/server) the necesary javascript files and css will be copied to the public/ directory.
+
+===As a plug-in
+I actually haven't tried this, sorry I don't know how to do it.
+
+==Re-installation
+===As a gem
+Several steps are needed:
+* It is recommended that you uninstall the gem before installing a new version.
+* You must remove this file: public/javascripts/dependent_select/dependent_select.js
+* And then install the new version
+
+In other words:
+    sudo gem uninstall splendeo-dependent_select
+    rm public/javascripts/dependent_select/dependent_select.js
+    rake gems:install
+
+===As a plug-in
+I haven't looked into that yet.
+
+==No AJAX? I can't sent the client all my cities!
+
+No AJAX for now, sorry. Just plain old javascript.
+
+However, it might interest you that you'll be generating this:
+
+    <script>
+      var whatever = [['opt1',1,1],['opt2',2,1],['opt3',3,1]...];
+    </script>
+
+Instead of this :
+
+    <option value='1'>opt1</option>
+    <option value='2'>opt2</option>
+    <option value='3'>opt3</option>
+
+In our tests, generating information for 8000 cities took arond 20k - the size of a small image.
+
+Make the test and then decide. It will not take you more than 10 minutes.
+
+==Complex example: Employee with home city and work city
+
+On this case we have an employee model with 2 relationships with cities. So the employee model
+might look like the one below. Notice that the +delegates+ get a bit more complicated.
+    
+    class Employee < ActiveRecord::Base
+    
+      belongs_to :home_city, :class_name => "City", :include => [{:province => :country}]
+      delegate :country, :country_id, :country_id=, :to =>:home_city,
+        :allow_nil => true, :prefix => :home
+      delegate :province, :province_id, :province_id=, :to =>:home_city,
+        :allow_nil => true, :prefix => :home
+  
+      belongs_to :work_city, :class_name => "City", :include => [{:province => :country}]
+      delegate :country, :country_id, :country_id=, :to =>:work_city,
+        :allow_nil => true, :prefix => :work
+      delegate :province, :province_id, :province_id=, :to =>:work_city,
+        :allow_nil => true, :prefix => :home
+    
+    end
+
+On your layout:
+    <%= javascript_include_tag :defaults %>
+    <%= dependent_select_includes %>
+
+On your new/edit views, the "filter" for provinces isn't +:country_id+ any more, but +:home_country_id+ or
++:work_country_id+. The same happens with the cities and the provinces. You have to tell the selects
+where to find the right filter fields, using the +filter_field+ option.
+
+    <% form_for :employee do |f| %>
+      Home Country:<br/>
+      <% f.collection_select :home_country_id, @countries, :id, :name, :include_blanks => true %> <br />
+      Home Province:<br/>
+      <% f.dependent_collection_select :home_province_id, @provinces, :id, :name, :country_id, 
+        :filter_field => :home_country_id,
+        :include_blanks => true %> <br />
+      Home City:<br/>
+      <% f.dependent_collection_select :home_city_id, @cities, :id, :name, :city_id, 
+        :filter_field => :home_province_id,
+        :include_blanks => true %> <br />
+      Work Country:<br/>
+      <% f.collection_select :work_country_id, @countries, :id, :name, :include_blanks => true %> <br />
+      Work Province:<br/>
+      <% f.dependent_collection_select :work_province_id, @provinces, :id, :name, :country_id, 
+        :filter_field => :work_country_id,
+        :include_blanks => true %> <br />
+      Work City:<br/>
+      <% f.dependent_collection_select :work_city_id, @cities, :id, :name, :city_id, 
+        :filter_field => :work_province_id,
+        :include_blanks => true %> <br />
+    <% end %>
+    
+On your controller:
+  
+    class EmployeesController < ApplicationController
+      before_filter :fill_selects :only => [:new, :edit, :update, :create]
+      
+      {...} # Standard scaffold-generated methods
+      
+      protected
+      def fill_selects
+        @countries = Country.find(:all, :order => 'name ASC')
+        @provinces = Province.find(:all, :order => 'name ASC') # all provinces for all countries
+        @cities = City.find(:all, :order => 'name ASC') # all cities for all provinces
+      end
+    end

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/lib/dependent_select.rb"

data/lib/dependent_select/dependent_select.rb

@@ -0,0 +1,28 @@
+module DependentSelect
+
+  # Returns the default_options hash.  These options are by default provided to every calendar_date_select control, unless otherwise overrided.
+  # 
+  # Example:
+  #   # At the bottom of config/environment.rb:
+  #   DependentSelect.default_options.update(
+  #     :collapse_spaces => false
+  #   )
+  def self.default_options
+    @default_options ||= { :collapse_spaces => true }
+  end
+
+  # By default, spaces are collapsed on browsers when printing the select option texts
+  # For example:
+  #    <select>
+  #       <option>This  option    should   have      lots of       spaces   on its text</option>
+  #    </select>
+  # When you browse that, some browsers collapse the spaces, so you get an option that says
+  #       "This option should have lots of spaces on its text"
+  # Setting collapse_blanks to false will replace the blanks with the &nbsp; character, using
+  # javascript
+  #    option_text.replace(/ /g, "\240"); // "\240" is the octal representation of charcode 160 (nbsp)
+  def self.collapse_spaces=(value)
+    default_options[:collapse_spaces] = value
+  end
+
+end

data/lib/dependent_select/form_helpers.rb

@@ -0,0 +1,521 @@
+# Various helpers available for use in your view
+module DependentSelect::FormHelpers
+
+  # Similar to collection_select form helper, but adds a "filter_method" parameter
+  # the generated code includes a javascript observer that modifies the select
+  # using the value of a form method.
+  #
+  # == Parameters
+  #   +object_name+:: The name of an object being modified by this select. Example: +:employee+
+  #   +method+:: The name of a method of the object designated by "object_name" that
+  #              this select affects. Example: +:city_id+
+  #   +collection+:: The collection used for generating the +<options>+ on the
+  #                  select. Example: +@cities+
+  #   +value_method+:: The method that returns the value of each +<option>+ when
+  #                    applied to each element on +collection+.
+  #                    Example: +:id+ (for city.id)
+  #   +text_method+:: The method that returns the text of each +<option>+ when
+  #                   applied to each to each element on +collection+.
+  #                   Example: +:name+ (for city.name)
+  #   +filter_method:: The method being used for filtering. For example,
+  #                    +:province_id+ will filter cities by province.
+  #                    Important notice: this parameter also sets the DOM field
+  #                    id that should be used for getting the filter value.
+  #                    In other words, setting this to :province_id and the +object_name+ to
+  #                    :employee will mean that somewhere on your form there will be a
+  #                    field called "employee_province_id", used for filtering.
+  #   +options+:: (Optional) Usual options for +collection_select+ (such as
+  #               +include_blank+) plus 3 new ones, detailed below.
+  #   +html_options+:: (Optional)The same html options as +collection_select+.
+  #                    They are appended to the html +select+ as attributes.
+  # == Options
+  # In addition to all options for +collection_select+, several new options are available
+  #
+  # === :collapse_spaces
+  # By default, blank spaces are collapsed on browsers when printing the select option texts
+  # For example, given the following html:
+  #    <select>
+  #       <option>This  option    should   have      lots of       spaces   on its text</option>
+  #    </select>
+  # Most browsers will "collapse" the spaces, and present something like this instead:
+  #       "This option should have lots of spaces on its text"
+  # Setting collapse_spaces to false will replace the blanks with the &nbsp; character.
+  # This is accomplised on the javascript function using code similar to the following
+  #
+  #    option_text.replace(/ /g, "\240"); // "\240" is the octal representation of charcode 160 (nbsp)
+  #
+  # On the following example, a sale occurs on a store that belongs to a company. The store model
+  # has a method called +name_for_selects+ that prints a two-column text - the first column has
+  # the company name on it, while the second has the store address. They are separated by a '|'
+  # character, and padded with spaces when necesary (company name has 10 chars or less)
+  #
+  #    class Store < ActiveRecord::Model
+  #      belongs_to :company
+  #      has_many :sales
+  #      validates_presence_of :address
+  #
+  #      def name_for_selects
+  #        "#{company.name.ljust(10)} | #{address}"
+  #      end
+  #    end
+  #
+  # Now on the edit/new sale view, we will need to use the :collapse_spaces option like this:
+  #
+  #    <%= dependent_collection_select(:sale, :store_id, @stores, :id, :name_for_selects, :company_id,
+  #          {:collapse_spaces => true}, {:class => 'monospaced'})
+  #     %>
+  #
+  # It is recommended that you use this function in conjunction with a monospaced css style. The following
+  # rule should be available, for example on application.css:
+  #
+  #    .monospaced {
+  #      font-family: monospaced;
+  #    }
+  #
+  # === :filter_field
+  # The javascript employed for updating the dependent select needs a field for getting
+  # the "filter value". The default behaviour is calculating this field name by using the
+  # +:object_name+ and +:filter_value+ parameters. For example, on this case:
+  #
+  #    <%= dependent_collection_select(:sale, :province_id, @provinces, :id, :name, :country_id) %>
+  #
+  # +:object_name+ is +:sale+, and +:filter_id+ is +:country_id+, so the javascript will look
+  # for a field called +'sale_country_id'+ on the html.
+  #
+  # It is possible to override this default behaviour by specifying a +:filter_field+ option.
+  # For example, in this case:
+  #
+  #    <%= dependent_collection_select(:sale, :province_id, @provinces, :id, :name, 
+  #          :country_id, {:filter_field => :state_id})
+  #     %>
+  #
+  # This will make the javascript to look for a field called +'sale_state_id+
+  # Notice that the chain 'sale_' is still appended to the field name. It is possible to override this
+  # by using the +:complete_filter_field+ option istead of this one.
+  #
+  # The most common use of this property will be for dealing with multiple relationships between the same
+  # models. See the complex example below for details.
+  #
+  # === :complete_filter_field
+  # Works the same way as :filter_field, except that it uses its value directly, instead
+  # of appending the :object_name at all. For example:
+  #
+  #    <%= dependent_collection_select(:sale, :province_id, @provinces, :id, :name, 
+  #          :country_id, {:complete_filter_field => :the_province})
+  #     %>
+  #
+  # This will make the javascript to look for a field called +'the_province'+ on the
+  # page, and use its value for filtering.
+  #
+  # === :array_name
+  # dependent_select generates a javascript array with all the options available to the dependent select.
+  # By default, the name of that variable is automatically generated using the following formula:
+  #
+  #    js_array_name = "ds_#{dependent_field_id}_array"
+  #
+  # This can be overriden by using the js_array_name option (its value will be used instead of the previous)
+  #
+  # This is useful because, by default, dependant_select forms will keep track of generated arrays, and *will not*
+  # generate the same array twice. This is very useful for situations in which lots of dependent_selects have
+  # to be generated, with the same data. For example, a flight has a destination and origin city:
+  #
+  #    <%= dependent_collection_select( :flight, :origin_city_id, @cities, :id, :name, :province_id,
+  #          { :filter_field => :origin_province_id, js_array_name => 'cities_array' }
+  #     %>
+  #
+  #    <%= dependent_collection_select( :flight, :destination_city_id, @cities, :id, :name, :province_id,
+  #          { :filter_field => :destination_province_id, js_array_name => 'cities_array' }
+  #     %>
+  #
+  # This example will generate the first javascript array and call it cities_array. Then the second
+  # call to +dependent_select+ is done, the form will already know that the javascript for this script
+  # is generated, so it will not generate an array.
+  #
+  # The +:array_name+ option can also be used in the opposite way: to force the generation of an array.
+  # This should happen very rarely - two dependent selects generate the same object name and method but are not
+  # supposed to use the same list of values.
+  #
+  # == Examples
+  #
+  # === Example 1: A store on a City
+  # In a form for creating a Store, the three selects used for Store, Province and City.
+  #
+  # views/Stores/new and views/Stores/edit:
+  #
+  #    <p>
+  #      Country:
+  #      <%= collection_select :store, :country_id, @countries, :id, :name %>
+  #    </p><p>
+  #      Province:
+  #      <%= dependent_collection_select :store, :province_id, @provinces, :id, :name, :country_id %>
+  #    </p><p>
+  #      City:
+  #      <%= dependent_collection_select :store, :city_id, @cities, :id, :name, :province_id %>
+  #    </p>
+  #
+  # Notes:
+  #   * The first helper is rail's regular +collection_select+, since countries don't
+  #     "depend" on anything on this example.
+  #   * You only need a +city_id+ on the +stores+ table (+belongs_to :city+).
+  #
+  #  You need to define methods on your model for obtaining a +province_id+ and
+  #  +country_id+. One of the possible ways is using rails' +delegate+ keyword. See
+  #  example below (and note the +:include+ clause)
+  #
+  #    class Store < ActiveRecord::Base
+  #      belongs_to :city, :include => [{:province => :country}] #:include not necessary, but nice
+  #      delegate :country, :country_id, :country_id=, :to =>:city, :allow_nil => true
+  #      delegate :province, :province_id, :province_id=, :to =>:city, :allow_nil => true
+  #    end
+  #
+  # This delegates the +province_id+ and +country_id+ methods to the +:city+ object_name.
+  # So a City must be able to handle country-related stuff too. Again, using +delegate+, you can
+  # do:
+  #
+  #    class City < ActiveRecord::Base
+  #      belongs_to :province, :include => [:country]
+  #      delegate :country, :country_id, :country_id=, :to =>:province, :allow_nil => true
+  #    end
+  #
+  # Note that I've also delegated +province+, +province=+, +country+ and +country=+ .
+  # This is so I'm able to do things like +puts store.country.name+.
+  # This is convenient but not needed.
+  #
+  # === Example 2: Using html_options
+  # Imagine that you want your selects to be of an specific css class, for formatting.
+  # You can accomplish this by using the +html_options+ parameter
+  #
+  #    <p>
+  #      Country:
+  #      <%= collection_select :store, :country_id, @countries, :id, :name,
+  #            {:include_blanks => true}, {:class=>'monospaced'}
+  #       %>
+  #    </p><p>
+  #      Province:
+  #      <%= dependent_collection_select :store, :province_id, @provinces, :id, :name,
+  #            :country_id, {:include_blanks => true}, {:class=>'brightYellow'}
+  #       %>
+  #    </p><p>
+  #      City:
+  #      <%= dependent_collection_select :store, :city_id, @cities, :id, :name,
+  #            :province_id, {:include_blanks => true}, {:class=>'navyBlue'}
+  #       %>
+  #    </p>
+  #
+  # Notice the use of +{}+ for the +:options+ parameter. If we wanted to include +html_options+
+  # but not options, we would have had to leave empty brackets.
+  #
+  # === Example 3: Multiple relations and +:filter_field+
+  # Imagine that you want your stores to have two cities instead of one; One for
+  # importing and another one for exporting. Let's call them +:import_city+ and
+  # +:export_city+:
+  #
+  # Models/Store.rb:
+  #
+  #     class Store < ActiveRecord::Base
+  #
+  #      belongs_to :import_city, :class_name => "City", :include => [{:province => :country}]
+  #      delegate :country, :country_id, :country_id=, :to =>:import_city,
+  #        :allow_nil => true, :prefix => :import
+  #      delegate :province, :province_id, :province_id=, :to =>:import_city,
+  #        :allow_nil => true, :prefix => :import
+  #
+  #      belongs_to :export_city, :class_name => "City", :include => [{:province => :country}]
+  #      delegate :country, :country_id, :country_id=, :to =>:export_city,
+  #        :allow_nil => true, :prefix => :export
+  #      delegate :province, :province_id, :province_id=, :to =>:export_city,
+  #        :allow_nil => true, :prefix => :import
+  #    end
+  #
+  # In this case, the store doesn't have a +:city_id+, +:country_id+ or +:province_id+. Instead, it has
+  # +:export_city_id+, +:export_country_id+ and +:export_province_id+, and the same for import.
+  #
+  # We'll have to use the +:filter_field+ option in order to use the right field for
+  # updating the selects.
+  #
+  # views/Stores/new and views/Stores/edit:
+  #
+  #    <p>
+  #      Import Country:
+  #      <%= collection_select :store, :import_country_id, @countries, :id, :name %>
+  #    </p><p>
+  #      Import Province:
+  #      <%= dependent_collection_select :store, :import_province_id, @provinces, :id, :name,
+  #            :country_id, :filter_field => :import_country_id, :array_name => 'provinces_array'
+  #       %>
+  #    </p><p>
+  #      Import City:
+  #      <%= dependent_collection_select :store, :import_city_id, @cities, :id, :name,
+  #            :province_id, :filter_field => :import_province_id, :array_name => 'cities_array'
+  #       %>
+  #    </p><p>
+  #      Export Country:
+  #      <%= collection_collection_select :store, :export_country_id, @countries, :id, :name %>
+  #    </p><p>
+  #      Export Province:
+  #      <%= dependent_collection_select :store, :export_province_id, @provinces, :id, :name,
+  #            :country_id, :filter_field => :export_country_id, :array_name => 'provinces_array'
+  #       %>
+  #    </p><p>
+  #      Export City:
+  #      <%= dependent_select :store, :export_city_id, @cities, :id, :name,
+  #            :province_id, :filter_field => :export_province_id, :array_name => 'cities_array'
+  #       %>
+  #    </p>
+  # Notice the use of +:array_name+. This is optional, but greatly reduces the amount of js code generated
+  #
+  def dependent_collection_select(object_name, method, collection, value_method, 
+    text_method, filter_method, options = {}, html_options = {}
+  )
+    object, options, extra_options = dependent_select_process_options(object_name, options)
+
+    initial_collection = dependent_select_initial_collection(object,
+      method, collection, value_method)
+    
+    tag, dependent_field_id = dependent_collection_select_build_tag(
+      object_name, object, method, initial_collection, value_method, 
+      text_method, options, html_options)
+
+    script = dependent_select_js_for_collection(object_name, object, method, 
+      collection, value_method, text_method, filter_method, options, html_options,
+      extra_options, dependent_field_id)
+      
+    return "#{tag}\n#{script}"
+  end
+
+
+  # Similar to +select+ form helper, but generates javascript for filtering the
+  # results depending on the value on another field.
+  # Consider using +dependent_collection_select+ instead of this one, it will probably
+  # help you more. And I'll be updating that one more often.
+  # == Parameters
+  #   +object_name+:: The name of the object being modified by this select. 
+  #                   Example: +:employee+
+  #   +method+:: The name of the method on the object cadded "object_name" that this
+  #              will affect. Example: +:city_id+
+  #   +choices_with_filter+:: The structure is +[[opt1_txt, opt1_value, opt1_filter],
+  #                           [opt2_txt, opt2_value, opt2_filter] ... ]+.
+  #   +filter_method:: The method being used for filtering. For example,
+  #                    +:province_id+ will filter cities by province.
+  #                    Important notice: this parameter also sets the DOM field
+  #                    id that should be used for getting the filter value.
+  #                    In other words, setting this to :province_id and the +object_name+ to
+  #                    :employee will mean that somewhere on your form there will be a
+  #                    field called "employee_province_id", used for filtering.
+  #   +options+ and +html_options+:: See +dependent_collection_select+.
+  # == Examples
+  #
+  # === Example 1: Types of animals
+  # Create an animal on a children-oriented app, where groups and subgroups
+  # are predefined constants.
+  #
+  # models/animal.rb
+  #
+  #    class Animal < ActiveRecord::Base
+  #      GROUPS = [['Invertebrates', 1], ['Vertebrates', 2]]
+  #      SUBGROUPS = [
+  #        ['Protozoa', 1, 1], ['Echinoderms',2,1], ['Annelids',3,1], ['Mollusks',4,1],
+  #        ['Arthropods',5,1], ['Crustaceans',6,1], ['Arachnids',7,1], ['Insects',8,1],
+  #        ['Fish',9,2], ['Amphibians',10,2], ['Reptiles',11,2], ['Birds',12,2],
+  #        ['Mammals',13,2], ['Marsupials',14,2], ['Primates',15,2], ['Rodents',16,2],
+  #        ['Cetaceans',17,2], ['Seals, Seal Lions and Walrus',18,2]
+  #      ]
+  #    end
+  #
+  # new/edit animal html.erb
+  #
+  #    <p>
+  #      Group: <%= select :animal, :group_id, Animal::GROUPS %>
+  #    </p><p>
+  #      Subgroup: <%= select :animal, :subgroup_id, :group, Animal::SUBGROUPS %>
+  #    </p>
+  #
+  def dependent_select(object_name, method, choices_with_filter, filter_method,
+    options = {}, html_options = {})
+
+    object, options, extra_options = dependent_select_process_options(object_name, options)
+
+    initial_choices = dependent_select_initial_choices(object, method, choices_with_filter)
+    
+    tag, dependent_field_id = dependent_select_build_tag(
+      object_name, object, method, initial_collection, value_method, 
+      text_method, options, html_options)
+
+    script = dependent_select_js(object_name, method, choices_with_filter,
+      filter_method, options, html_options, extra_options)
+    
+    return "#{tag}\n#{script}"
+  end
+
+  private
+    #holds the names of the arrays already generated, so repetitions can be avoided.
+    def dependend_select_array_names
+      @dependend_select_array_names ||= {}
+    end
+  
+    # extracts any options passed into calendar date select, appropriating them to either the Javascript call or the html tag.
+    def dependent_select_process_options(object_name, options)
+      options, extra_options = DependentSelect.default_options.merge(options), {}
+      for key in [:collapse_spaces, :filter_field, :complete_filter_field, :array_name]
+        extra_options[key] = options.delete(key) if options.has_key?(key)
+      end
+       
+      object = options.delete(:object) || instance_variable_get("@#{object_name}")
+      
+      options[:object]=object
+
+      [object, options, extra_options]
+    end
+
+    # generates the javascript that will follow the dependent select
+    # contains:
+    #  * An array with all the possible options (structure [text, value, filter])
+    #  * An observer that detects changes on the "observed" field and triggers an update
+    #  * An extra observer for custon events. These events are raised by the dependent_select itself.
+    #  * An first call to update_dependent_select, that sets up the initial stuff
+    def dependent_select_js(object_name, object, method, choices_with_filter, 
+      filter_method, options, html_options, extra_options, dependent_field_id)
+
+      # the js variable that will hold the array with option values, texts and filters
+      js_array_name = extra_options[:array_name] || "ds_#{dependent_field_id}_array"
+      
+      js_array_code = ""
+      
+      if(dependend_select_array_names[js_array_name].nil?)
+        dependend_select_array_names[js_array_name] = true;
+        js_array_code += "#{js_array_name} = #{choices_with_filter.to_json};\n"    
+      end
+      
+      observed_field_id = dependent_select_calculate_observed_field_id(object_name, object,
+        filter_method, html_options, extra_options)
+      initial_value = dependent_select_initial_value(object, method)
+      include_blank = options[:include_blank] || false
+      collapse_spaces = extra_options[:collapse_spaces] || false
+
+      js_callback =
+        "function(e) { update_dependent_select( '#{dependent_field_id}', '#{observed_field_id}', #{js_array_name}, " +
+        "'#{initial_value}', #{include_blank}, #{collapse_spaces}, false); }"
+
+      javascript_tag(js_array_code +
+        "$('#{observed_field_id}').observe ('change', #{js_callback});\n" +
+        "$('#{observed_field_id}').observe ('DependentSelectFormBuilder:change', #{js_callback}); \n" +
+        "update_dependent_select( '#{dependent_field_id}', '#{observed_field_id}', #{js_array_name}, " +
+        "'#{initial_value}', #{include_blank}, #{collapse_spaces}, true);"
+      )
+    end
+    
+    # generates the js script for a dependent_collection_select. See +dependent_select_js+
+    def dependent_select_js_for_collection(object_name, object, method, collection, 
+      value_method, text_method, filter_method, options, html_options, extra_options, dependent_field_id)
+
+      # the array that, converted to javascript, will be assigned values_var variable,
+      # so it can be used for updating the select
+      choices_with_filter = collection.collect do |c|
+        [ c.send(text_method), c.send(value_method), c.send(filter_method) ]
+      end
+
+      dependent_select_js(object_name, object, method, choices_with_filter, 
+        filter_method, options, html_options, extra_options, dependent_field_id)
+    end
+    
+    # returns a collection_select html string and the id of the generated field
+    def dependent_collection_select_build_tag(object_name, object, method, collection, value_method, 
+      text_method, options, html_options)
+      dependent_field_id, it = dependent_select_calculate_field_id_and_it(object_name, 
+        object, method, html_options)
+      
+      tag = it.to_collection_select_tag(collection, value_method, text_method, options, html_options)
+      
+      return [tag, dependent_field_id]
+    end
+    
+    # returns a select html string and the id of the generated field
+    def dependent_select_build_tag(object_name, object, method, choices, options = {}, html_options = {})
+      
+      dependent_field_id, it = dependent_select_calculate_field_id_and_it(object_name, 
+        object, method, html_options)
+      
+      tag = it.to_select_tag(choices, options, html_options)
+      
+      return [tag, dependent_field_id]
+    end
+
+    # Calculates the dom id of the observed field, usually concatenating object_name and filt. meth.
+    # For example, 'employee_province_id'. Exceptions:
+    #  * If +extra_options+ has an item with key +:complete_filter_field+, 
+    #    it returns the value of that item
+    #  * If +extra_options+ has an item with key +:filter_field+,
+    #    it uses its value instead of +method+
+    def dependent_select_calculate_observed_field_id(object_name, object, method, 
+      html_options, extra_options)
+      
+      return extra_options[:complete_filter_field] if extra_options.has_key? :complete_filter_field
+      method = extra_options[:filter_field] if extra_options.has_key? :filter_field
+
+      return dependent_select_calculate_field_id(object_name, object, method, html_options)
+    end
+    
+    # calculates the id of a generated field
+    def dependent_select_calculate_field_id(object_name, object, method, html_options)
+      field_id, it = dependent_select_calculate_field_id_and_it(object_name, object, method, html_options)
+      return field_id
+    end
+    
+    # ugly hack used to obtain the generated id from a form_helper
+    # uses the method ActionView::Helpers::InstanceTag.add_default_name_and_id,
+    # ...which is a private method of an internal class of rails. filty.
+    def dependent_select_calculate_field_id_and_it(object_name, object, method, html_options)
+      it = ActionView::Helpers::InstanceTag.new(object_name, method, self, object)
+      html_options = html_options.stringify_keys
+      it.send :add_default_name_and_id, html_options #use send since add_default... is private
+      return [ html_options['id'], it]
+    end
+    
+    # Returns the collection that will be used when the dependent_select is first displayed
+    # (before even the first update_dependent_select call is done)
+    # The collection is obained by taking all the elements in collection whose value
+    # equals to +initial_value+. For example if we are editing an employee with city_id=4,
+    # we should put here all the cities with id=4 (there could be more than one)
+    def dependent_select_initial_collection(object, method, collection, value_method)
+      initial_value = dependent_select_initial_value(object, method)
+      return collection.select { |c| c.send(value_method) == initial_value }
+    end
+
+    # this is +dependent_select+'s version of +dependent_select_initial_collection+ 
+    def dependent_select_initial_choices(object, method, choices_with_filter)
+      initial_value = dependent_select_initial_value(object, method)
+      return choices_with_filter.select { |c| c[1] == initial_value }
+    end
+
+    # The value that the dependend select will have when first rendered. It could be different from
+    # nil, if we are editing. Example: if we are editing an employee with city_id=4, then 4 should be
+    # the initial value.
+    def dependent_select_initial_value(object, method)
+      return object.send(method) || "" if object
+      return ""
+    end
+
+
+end
+
+# Helper method for form builders
+module ActionView
+  module Helpers
+    class FormBuilder
+      def dependent_select( method, choices_with_filter, filter_method, 
+        options = {}, html_options = {}
+      )
+        @template.dependent_select(@object_name, method, choices_with_filter, 
+          filter_method, options.merge(:object => @object), html_options)
+      end
+      
+      def dependent_collection_select( method, collection, value_method, 
+        text_method, filter_method, options = {}, html_options = {}
+      )
+        @template.dependent_collection_select(@object_name, method, collection, 
+          value_method, text_method, filter_method,
+          options.merge(:object => @object), html_options)
+      end
+    end
+  end
+end

data/lib/dependent_select/includes_helper.rb

@@ -0,0 +1,9 @@
+module DependentSelect::IncludesHelper
+  # returns html necessary to load the javascript needed for dependent_select
+  def dependent_select_includes(options = {})
+    return "" if @ds_already_included
+    @ds_already_included=true
+    
+    javascript_include_tag("dependent_select/dependent_select")
+  end
+end

data/lib/dependent_select.rb

@@ -0,0 +1,19 @@
+require "dependent_select/dependent_select.rb"
+require "dependent_select/form_helpers.rb"
+require "dependent_select/includes_helper.rb"
+
+if Object.const_defined?(:Rails) && File.directory?(Rails.root.to_s + "/public")  
+  ActionView::Helpers::FormHelper.send(:include, DependentSelect::FormHelpers)
+  ActionView::Base.send(:include, DependentSelect::FormHelpers)
+  ActionView::Base.send(:include, DependentSelect::IncludesHelper)
+  
+  # install files
+  unless File.exists?(RAILS_ROOT + '/public/javascripts/dependent_select/dependent_select.js')
+    ['/public', '/public/javascripts/dependent_select'].each do |dir|
+      source = File.dirname(__FILE__) + "/../#{dir}"
+      dest = RAILS_ROOT + dir
+      FileUtils.mkdir_p(dest)
+      FileUtils.cp(Dir.glob(source+'/*.*'), dest)
+    end
+  end
+end

data/public/javascripts/dependent_select/dependent_select.js

@@ -0,0 +1,45 @@
+
+function update_dependent_select( dependent_id, observed_id, values_array, // mandatory
+  initial_value, include_blank, collapse_spaces, first_run ) {             // optional
+  
+  // parse the optional parameters ....
+  initial_value = initial_value || '';
+  include_blank = include_blank || false;
+  collapse_spaces = collapse_spaces || false;
+  first_run = first_run || false;
+
+  // select DOM node whose options are modified
+  var dependent_field = $(dependent_id);
+
+  // select DOM node whose changes trigger this
+  var observed_field = $(observed_id);
+
+  // value chosen on observed_select, used for filtering dependent_select
+  var filter = observed_field.value;
+
+  // the first time the update_func is executed (on edit) the value the select has
+  // comes directly from the model. From them on, it will only use the client's input
+  var previous_value = first_run ? initial_value : dependent_field.value;
+
+  // removes all options from dependent_field
+  dependent_field.childElements().each( function(o) { o.remove(); } );
+
+  // adds a blank option, only if specified on options
+  if(include_blank) {
+    dependent_field.appendChild(new Element('option', {selected: !previous_value})); // it will be selected if previous_value is nil
+  }
+
+  // this fills the dependent select
+  values_array.each (function (e) {
+    if (e[2]==filter) {                                        // only include options with the right filter field
+      var opt = new Element('option', {value: e[1]});          // create one <option> element...
+      if(collapse_spaces) { opt.text= e[0];}                   // assign the text (spaces are automatically collapsed)
+      else { opt.text = e[0].replace(/ /g, '\240'); }          // replacing spaces with &nbsp; if requested
+      if(opt.value == previous_value) { opt.selected=true; }   // mark it as selected if appropiate
+      dependent_field.options[dependent_field.options.length]=opt; // attach to depentent_select.. could not use "add"
+    }
+  });
+
+  // launch a custom event (Prototype doesn't allow launcthing "change") to support dependencies of dependencies
+  dependent_field.fire('DependentSelectFormBuilder:change');
+}

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: dependent_select
+version: !ruby/object:Gem::Version 
+  version: 0.6.5
+platform: ruby
+authors: 
+- Enrique Garcia Cota (egarcia)
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-10 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: "dependent_select: a select that depends on other field and updates itself using js"
+email: egarcia@splendeo.es
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- init.rb
+- lib/dependent_select.rb
+- lib/dependent_select/dependent_select.rb
+- lib/dependent_select/form_helpers.rb
+- lib/dependent_select/includes_helper.rb
+- public/javascripts/dependent_select/dependent_select.js
+- README.rdoc
+has_rdoc: true
+homepage: http://github.com/splendeo/dependent_select
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: generates a select with some js code that updates if if another field is modified.
+test_files: []
+