Skip to content

Commit

Permalink
Reformat README to take advantage of Markdown; extracted CONTRIBUTING…
Browse files Browse the repository at this point in the history 
….md document
  • Loading branch information
@parndt
parndt committed Jun 29, 2013
1 parent 4cc7b3b commit a7e7a8a
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 95 deletions.
14 changes: 14 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Contributing to AwesomeNestedSet

If you find what you might think is a bug:

1. Check the [GitHub issue tracker](https://github.com/collectiveidea/awesome_nested_set/issues/) to see if anyone else has had the same issue.
2. If you don't see anything, create an issue with information on how to reproduce it.

If you want to contribute an enhancement or a fix:

1. Fork [the project on GitHub](https://github.com/collectiveidea/awesome_nested_set)
2. Make your changes with tests.
3. Commit the changes without making changes to the [Rakefile](Rakefile) or any other files that aren't related to your enhancement or fix.
4. Write an entry in the [CHANGELOG](CHANGELOG)
5. Send a pull request.
198 changes: 103 additions & 95 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,153 +1,161 @@
= AwesomeNestedSet
# AwesomeNestedSet

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.
Awesome Nested Set is an implementation of the nested set pattern for ActiveRecord models.
It is a 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.

== What makes this so awesome?
## 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
[![Code Climate](https://codeclimate.com/github/collectiveidea/awesome_nested_set.png)](https://codeclimate.com/github/collectiveidea/awesome_nested_set)

Add to your Gemfile:
## Installation

gem 'awesome_nested_set'
Add to your Gemfile:

== Usage
```ruby
gem 'awesome_nested_set'
```

To make use of awesome_nested_set, your model needs to have 3 fields: lft, rgt, and parent_id.
You can also have an optional field: depth:
## Usage

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
t.integer :depth # this is optional.
end
end
To make use of `awesome_nested_set`, your model needs to have 3 fields:
`lft`, `rgt`, and `parent_id`. The names of these fields are configurable.
You can also have an optional field, `depth`:

def self.down
drop_table :categories
```ruby
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
t.integer :depth # this is optional.
end
end

Enable the nested set functionality by declaring acts_as_nested_set on your model

class Category < ActiveRecord::Base
acts_as_nested_set
def self.down
drop_table :categories
end
end
```

Run `rake rdoc` to generate the API docs and see CollectiveIdea::Acts::NestedSet for more info.
Enable the nested set functionality by declaring `acts_as_nested_set` on your model

== Callbacks
```ruby
class Category < ActiveRecord::Base
acts_as_nested_set
end
```

There are three callbacks called when moving a node. `before_move`, `after_move` and `around_move`.
Run `rake rdoc` to generate the API docs and see [CollectiveIdea::Acts::NestedSet](lib/awesome_nested_set/awesome_nested_set.rb) for more information.

class Category < ActiveRecord::Base
acts_as_nested_set
## Callbacks

after_move :rebuild_slug
around_move :da_fancy_things_around
There are three callbacks called when moving a node:
`before_move`, `after_move` and `around_move`.

private
```ruby
class Category < ActiveRecord::Base
acts_as_nested_set

def rebuild_slug
# do whatever
end
after_move :rebuild_slug
around_move :da_fancy_things_around

def da_fancy_things_around
# do something...
yield # actually moves
# do something else...
end
private

def rebuild_slug
# do whatever
end

Beside this there are also hooks to act on the newly added or removed children.
def da_fancy_things_around
# do something...
yield # actually moves
# do something else...
end
end
```

class Category < ActiveRecord::Base
acts_as_nested_set :before_add => :do_before_add_stuff,
:after_add => :do_after_add_stuff,
:before_remove => :do_before_remove_stuff,
:after_remove => :do_after_remove_stuff
Beside this there are also hooks to act on the newly added or removed children.

private
```ruby
class Category < ActiveRecord::Base
acts_as_nested_set :before_add => :do_before_add_stuff,
:after_add => :do_after_add_stuff,
:before_remove => :do_before_remove_stuff,
:after_remove => :do_after_remove_stuff

def do_before_add_stuff(child_node)
# do whatever with the child
end
private

def do_after_add_stuff(child_node)
# do whatever with the child
end
def do_before_add_stuff(child_node)
# do whatever with the child
end

def do_before_remove_stuff(child_node)
# do whatever with the child
end
def do_after_add_stuff(child_node)
# do whatever with the child
end

def do_after_remove_stuff(child_node)
# do whatever with the child
end
def do_before_remove_stuff(child_node)
# do whatever with the child
end

def do_after_remove_stuff(child_node)
# do whatever with the child
end
end
```

== Protecting attributes from mass assignment
## Protecting attributes from mass assignment

It's generally best to "white list" the attributes that can be used in mass assignment:
It's generally best to "whitelist" the attributes that can be used in mass assignment:

class Category < ActiveRecord::Base
acts_as_nested_set
attr_accessible :name, :parent_id
end
```ruby
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:
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
```ruby
class Category < ActiveRecord::Base
acts_as_nested_set
attr_protected :lft, :rgt
end
```

== Conversion from other trees
## 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
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!
```ruby
Category.rebuild!
```

Your tree will be converted to a valid nested set. Awesome!

== View Helper
## View Helper

The view helper is called #nested_set_options.

Example usage:

<%= f.select :parent_id, nested_set_options(Category, @category) {|i| "#{'-' * i.level} #{i.name}" } %>
```erb
<%= 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}" } ) %>
<%= 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.
See [CollectiveIdea::Acts::NestedSet::Helper](lib/awesome_nested_set/helper.rb) for more information about the helpers.

== References
## References

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.
https://github.com/collectiveidea/awesome_nested_set/issues/
2. If you don't see anything, create an issue with information on how to reproduce it.

If you want to contribute an enhancement or a fix:

1. Fork the project on GitHub.
https://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.
## How to contribute

Copyright ©2008 Collective Idea, released under the MIT license
Copyright © 2008 - 2013 Collective Idea, released under the MIT license

0 comments on commit a7e7a8a

Please sign in to comment.