Chris@1296: = AwesomeNestedSet Chris@1296: Chris@1296: Awesome Nested Set is an implementation of the nested set pattern for ActiveRecord models. It is replacement for acts_as_nested_set and BetterNestedSet, but more awesome. Chris@1296: Chris@1296: Version 2 supports Rails 3. Gem versions prior to 2.0 support Rails 2. Chris@1296: Chris@1296: == What makes this so awesome? Chris@1296: Chris@1296: This is a new implementation of nested set based off of BetterNestedSet that fixes some bugs, removes tons of duplication, adds a few useful methods, and adds STI support. Chris@1296: Chris@1296: == Installation Chris@1296: Chris@1296: Add to your Gemfile: Chris@1296: Chris@1296: gem 'awesome_nested_set' Chris@1296: Chris@1296: == Usage Chris@1296: Chris@1296: To make use of awesome_nested_set, your model needs to have 3 fields: lft, rgt, and parent_id: Chris@1296: Chris@1296: class CreateCategories < ActiveRecord::Migration Chris@1296: def self.up Chris@1296: create_table :categories do |t| Chris@1296: t.string :name Chris@1296: t.integer :parent_id Chris@1296: t.integer :lft Chris@1296: t.integer :rgt Chris@1296: end Chris@1296: end Chris@1296: Chris@1296: def self.down Chris@1296: drop_table :categories Chris@1296: end Chris@1296: end Chris@1296: Chris@1296: Enable the nested set functionality by declaring acts_as_nested_set on your model Chris@1296: Chris@1296: class Category < ActiveRecord::Base Chris@1296: acts_as_nested_set Chris@1296: end Chris@1296: Chris@1296: Run `rake rdoc` to generate the API docs and see CollectiveIdea::Acts::NestedSet for more info. Chris@1296: Chris@1296: == Protecting attributes from mass assignment Chris@1296: Chris@1296: It's generally best to "white list" the attributes that can be used in mass assignment: Chris@1296: Chris@1296: class Category < ActiveRecord::Base Chris@1296: acts_as_nested_set Chris@1296: attr_accessible :name, :parent_id Chris@1296: end Chris@1296: Chris@1296: If for some reason that is not possible, you will probably want to protect the lft and rgt attributes: Chris@1296: Chris@1296: class Category < ActiveRecord::Base Chris@1296: acts_as_nested_set Chris@1296: attr_protected :lft, :rgt Chris@1296: end Chris@1296: Chris@1296: == Conversion from other trees Chris@1296: Chris@1296: Coming from acts_as_tree or another system where you only have a parent_id? No problem. Simply add the lft & rgt fields as above, and then run Chris@1296: Chris@1296: Category.rebuild! Chris@1296: Chris@1296: Your tree will be converted to a valid nested set. Awesome! Chris@1296: Chris@1296: == View Helper Chris@1296: Chris@1296: The view helper is called #nested_set_options. Chris@1296: Chris@1296: Example usage: Chris@1296: Chris@1296: <%= f.select :parent_id, nested_set_options(Category, @category) {|i| "#{'-' * i.level} #{i.name}" } %> Chris@1296: Chris@1296: <%= select_tag 'parent_id', options_for_select(nested_set_options(Category) {|i| "#{'-' * i.level} #{i.name}" } ) %> Chris@1296: Chris@1296: See CollectiveIdea::Acts::NestedSet::Helper for more information about the helpers. Chris@1296: Chris@1296: == References Chris@1296: Chris@1296: You can learn more about nested sets at: http://threebit.net/tutorials/nestedset/tutorial1.html Chris@1296: Chris@1296: == How to contribute Chris@1296: Chris@1296: If you find what you might think is a bug: Chris@1296: Chris@1296: 1. Check the GitHub issue tracker to see if anyone else has had the same issue. Chris@1296: http://github.com/collectiveidea/awesome_nested_set/issues/ Chris@1296: 2. If you don't see anything, create an issue with information on how to reproduce it. Chris@1296: Chris@1296: If you want to contribute an enhancement or a fix: Chris@1296: Chris@1296: 1. Fork the project on github. Chris@1296: http://github.com/collectiveidea/awesome_nested_set/ Chris@1296: 2. Make your changes with tests. Chris@1296: 3. Commit the changes without making changes to the Rakefile, VERSION, or any other files that aren't related to your enhancement or fix Chris@1296: 4. Send a pull request. Chris@1296: Chris@1296: Copyright ©2008 Collective Idea, released under the MIT license