Multiple Select Helper
============================

Selecting multiple elements in a list is sometimes tricky. You may click
inadvertably on one item of the list and lost all your previous selection. You
are forced to use Ctrl (or Command) clicks to select more than one element.

Multiple Select Helper allows you to create easy to use list for multiple
selections from array, hashes, collections or trees. The list is build using
checkboxes so you can click easily and you will not lost the elements you
clicked before. As drawback you lose the use of the keyboard in the "list".

This multiple selections are very useful in many to many relationships
(has_and_belongs_to_many or has_many :through with no obligatory fields) where
a "add and remove" solution will be cumbersome.

You can download this plugin at:

http://svn.ruido-blanco.net/multiple_select/trunk

You can find this information at:

http://svn.ruido-blanco.net/blog/rails-multiple-select-plugin/

Using Multiple Select Helper
============================

There are 3 pairs of functions that you can use depending of the source of your
data:

- multiple_select (and checkboxes_for_multiple_select): With arrays, hashes or
  your own classes (implementing first and last in them).
- collection_multiple_select
  (and checkboxes_from_collection_for_multiple_select): With arrays of classes
  using text_method and value_method to access the data in the instances.
- tree_multiple_select (and checkboxes_from_tree_for_multiple_select): With
  tree-like structures (like ActiveRecord's acts_as_tree) using text_method and
  value_method to access the data in the instances.

All three posibilites supports the following options in the options hash:

[outer_class] Specifies the class of the div that wraps all the checkboxes.
[selected_items] Specifies an array of items that should be selected when the
                 list renders (only in the three main methods, the other three
                 use the selected_items parameter instead).
[inner_class] Specifies the class of the div that wraps each checkbox.
[position] Determines the position of the label besides the checkbox. The value
           should be :right or :left. The default is :right.
[alternate] Determines if the class of each of the checkboxes should alternate.
            The default is not alternating classes.
[alternate_class] Specifies the alternative class that will be used if alternate
                  option is used. The alternative class will be added to the
                  inner_class options if it is also specified. The default
                  alternative class is "alt".
[initial_alternate] Determines if the first element of the list should be the
                    alternative one or not. The default is that the first
                    element is not the alternative one.

Besides the options above described the two tree methods supports also the
following options:

[depth] Maximum depth the tree will be trasversed. A depth of 0 will only show
        the nodes of the first level. The default is traverse all the tree.
[child_method] The method that will be send to the node to obtain its children.
               This method must only return an array of the direct children of
               the node. The default is "children" (valid for acts_as_tree. For
               acts_as_nested_set use "direct_children" instead).
[level_class] Specifies the preffix of the class that will be used in each of
              the divs that wrap each checkbox. The level_class will be
              suffixed with a incresing number according the level of the
              actual checkbox. This class will be added to the inner_class and
              the alternative class if they are also specified.
[initial_level] Specifies the first level that will be used as preffix of
                level_class. The default is 0.

When you want to store your list of checked options in a habtm relationship you
could use something like:

 # In the model
 class Person < ActiveRecord::Base
   has_and_belongs_to_many :fruits
 end
 
 # In the view
 <%=
   collection_multiple_select(
     'fruits', Fruit.find(:all), :id, :name, :selected_items => @fruits
   )
 %>
 
 # In the controller
 @fruits = (params[:fruits] or []).collect {|item| item.to_i}
 @person.fruits.clear
 @person.fruits << Node.find(@fruits)

And you will have all the fruits you have selected linked to the person you are
editing.

Author
======

Daniel Rodríguez Troitiño <drodrigueztroitino@yahoo.es>.