dm-is-select

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

Installation

$  gem install dm-is-select

Or add the gem to your Gemfile, and then run bundle install.

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 <select> 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"]
]

NB! 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 ‘dm-is-select/spec/dm-is-select_spec.rb’ file.

Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported. Report it here: 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

Licence

Released under the MIT license.