Mongoid Nested Set

Mongoid Nested Set is an implementation of the nested set pattern for Mongoid. It is a port of AwesomeNestedSet for ActiveRecord. It supports Mongoid 2 and Rails 3.

Nested Set represents hierarchies of trees in MongoDB using references rather than embedded documents. A tree is stored as a flat list of documents in a collection. Nested Set allows quick, ordered queries of nodes and their descendants. Tree modification is more costly. The nested set pattern is ideal for models that are read more frequently than modified.

For more on the nested set pattern: http://en.wikipedia.org/wiki/Nested_set_model

Installation

Install as Gem

gem install mongoid_nested_set

via Gemfile

gem 'mongoid_nested_set', '0.1.3'

Usage

To start using Mongoid Nested Set, just declare acts_as_nested_set on your model:

class Category
    include Mongoid::Document
    acts_as_nested_set
end

Creating a root node

root = Category.create(:name => 'Root Category')

Inserting a node

child1 = root.children.create(:name => 'Child Category #1')

child2 = Category.create(:name => 'Child Category #2')
root.children << child2

Deleting a node

child1.destroy

Descendants of a destroyed nodes will also be deleted. By default, descendant's destroy method will not be called. To enable calling descendant's destroy method:

class Category
    include Mongoid::Document
    acts_as_nested_set :dependent => :destroy
end

Moving a node

Several methods exist for moving nodes:

• move_left
• move_right
• move_to_left_of(other_node)
• move_to_right_of(other_node)
• move_to_child_of(other_node)
• move_to_root

Scopes

Scopes restrict what is considered a list. This is commonly used to represent multiple trees (or multiple roots) in a single collection.

class Category
    include Mongoid::Document
    acts_as_nested_set :scope => :root_id
end

Conversion from other trees

Coming from acts_as_tree or adjacency list system where you only have parent_id? No problem. Simply add acts_as_nested_set and run:

Category.rebuild!

Your tree will be converted to a valid nested set.

Outline Numbering

Mongoid Nested Set can manage outline numbers (e.g. 1.3.2) for your documents if you wish. Simply add :outline_number_field:

acts_as_nested_set, :outline_number_field => 'number'

Your documents will now include a number field (you can call it anything you wish) that will contain outline numbers.

Don't like the outline numbers format? Simply override outline_number_seperator, build_outline_number, or outline_number_sequence in your model classes. For example:

class Category
    include Mongoid::Document
    acts_as_nested_set :scope => :root_id, :outline_number_field => 'number'

    # Use a dash instead of a dot for outline numbers
    # e.g. 1-3-2
    def outline_number_seperator
        '-'
    end

    # Use 0-based indexing instead of 1-based indexing
    # e.g. 1.0
    def outline_number_sequence(prev_siblings)
        prev_siblings.count
    end
end

References

You can learn more about nested sets at:

http://en.wikipedia.org/wiki/Nested_set_model
http://dev.mysql.com/tech-resources/articles/hierarchical-data.html

Contributing to mongoid_nested_set

• 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) 2010 Brandon Turner. See LICENSE.txt for further details.