= dm-is-select

A DataMapper plugin that makes getting the <tt><select></tt> options from a Model easier.


== Installation

  $  gem install dm-is-select
  
  
Or add the gem to your Gemfile, and then run <tt>bundle install</tt>.

  gem 'dm-is-select', 'CURRENT_VERSION_NUMBER'

  
=== Dependencies

The plugin depends upon the following:

* dm-mysql-adapter  OR  dm-sqlite3-adapter ( >= 1.2.0)
* data_mapper ( >= 1.2.0)
* dm-is-tree ( >= 1.2.0)
* activesupport (>= 3.2.7)  -  methods => Hash#except  and  Hash#slice


== Getting Started

Let's say you got a basic Category Model.

  class Category
    include DataMapper::Resource
    property :id, Serial
    property :name, String
    
    is :select, :name
    
  end
    
Through that simple declaration you get the following class method ..

  Category.items_for_select_menu

...which returns an Array with the Model items in a structured way, ready for use.

  [
    [nil, "Select Category"], 
    ["nil", "  ------  "], 
    [1, "Category 1"], 
    [2, "Category 2"], 
    [3, "Category 3"], 
    [4, "Category 4"], 
    [5, "Category 5"]
  ]

Great, but you don't want the prompt to say "Select Category", but 

  Category.items_for_select_menu( :prompt => "Choose Whatever" )


...which returns the Array with the prompt changed

  [
    [nil, "Choose Whatever"], 
    ["nil", "  ------  "], 
    [1, "Category 1"], 
    ...<snip>...
  ]


OK, but you don't like the divider node (2nd in output above). That’s fine, you remove it like this:

  Category.items_for_select_menu( :divider => false )


...which returns the Array with the divider removed

  [
    [nil, "Select Category"], 
    [1, "Category 1"], 
    ...<snip>...
  ]



Hmm, fine, but I don't want either a prompt or a divider, you say. That's fine too.

  Category.items_for_select_menu( :prompt => false )

...which returns the Array with the prompt and divider removed

  [
    [1, "Category 1"], 
    [1, "Category 2"], 
    ...<snip>...
  ]


OK, that's smooth, but my Category model is a tree with parents, children and so on. This won't work with that.

Sure, no problem, just do this when you declare the Model:

  is :select, :name, :is_tree => true


Then you can just use this

  Category.items_for_select_menu( :prompt => "Choose Parent" )
  
...and you get this nicely formatted <tt><select></tt> options array

  [
    [nil, "Choose Parent"], 
    ["nil", "  ------  "], 
    [0, "Top Level Category"],
    ["nil", "  ------  "], 
    [1, "Parent-1"], 
    [2, "-- Parent-1-Child"], 
    [3, "-- -- Parent-1-Child-GrandChild"],
    [4, "Parent-2"], 
    [5, "-- Parent-2-Child"], 
    [6, "-- -- Parent-2-Child-GrandChild"]
  ]
  
<b>NB!</b> It only supports 3 levels at this point in time, as I think that's enough in most use cases, 
but IF not, fix the code and let me know and I'll add it.

Cool, but that "Top Level Category" node is a bit ugly, but easily fixed. 

  Category.items_for_select_menu( :root_text => "1st Parent (root)" )

...gives you:
  
  [
    ...<snip>...
    ["nil", "  ------  "], 
    [0, "1st Parent (root)"],
    ["nil", "  ------  "], 
    ...<snip>...
  ]

You can even remove it all together by doing this:

  Category.items_for_select_menu( :show_root => false )




Obviously all the config options from above works with Tree models as well.

== Last Few Words

OK, I admit it, not the most impressive DM plugin there is, but hey, it sure helps keeping your model/views cleaner.


== RTFM 

For a better understanding of this gem/plugin, make sure you study the '<tt>dm-is-select/spec/dm-is-select_spec.rb</tt>' file.
 

== Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported.
Report it here: http://github.com/kematzy/dm-is-select/issues 


== Contributing to dm-is-select
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.

* Fork the project.

* Start a feature/bugfix branch.

* Commit and push until you are happy with your contribution.

* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


== Copyright

Copyright (c) 2009 - 2013 Kematzy.

== Licence

Released under the MIT license.