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