A tree structure for Mongoid documents using the materialized path pattern
- mongoid (>= 4.0, < 6.0)
For a mongoid 3.x compatible version, please use mongoid-tree 1.0.x, for a mongoid 2.x compatible version, please use mongoid-tree 0.7.x.
To install mongoid_tree, simply add it to your Gemfile:
gem 'mongoid-tree', :require => 'mongoid/tree'
In order to get the latest development version of mongoid-tree:
gem 'mongoid-tree', :git => 'git://github.com/benedikt/mongoid-tree'
You might want to add
:require => nil option and explicitly
require 'mongoid/tree' where needed and finally run
Upgrade from mongoid-tree 1.x
To fix issues with the ordering of ancestors, mongoid-tree 2.0 introduces a new
depth field to the documents that include the
Mongoid::Tree module. In case your project uses its own
depth field, you can now rely on mongoid-tree to handle this.
Read the API documentation at http://benedikt.github.com/mongoid-tree and take a look at the
class Node include Mongoid::Document include Mongoid::Tree end
There are several utility methods that help getting to other related documents in the tree:
Node.root Node.roots Node.leaves node.root node.parent node.children node.ancestors node.ancestors_and_self node.descendants node.descendants_and_self node.siblings node.siblings_and_self node.leaves
In addition it's possible to check certain aspects of the document's position in the tree:
node.root? node.leaf? node.depth node.ancestor_of?(other) node.descendant_of?(other) node.sibling_of?(other)
Mongoid::Tree for more information on these methods.
Mongoid::Tree doesn't order children by default. To enable ordering of tree nodes include the
Mongoid::Tree::Ordering module. This will add a
position field to your document and provide additional utility methods:
node.lower_siblings node.higher_siblings node.first_sibling_in_list node.last_sibling_in_list node.move_up node.move_down node.move_to_top node.move_to_bottom node.move_above(other) node.move_below(other) node.at_top? node.at_bottom?
class Node include Mongoid::Document include Mongoid::Tree include Mongoid::Tree::Ordering end
Mongoid::Tree::Ordering for more information on these methods.
It's possible to traverse the tree using different traversal methods using the
class Node include Mongoid::Document include Mongoid::Tree include Mongoid::Tree::Traversal end node.traverse(:breadth_first) do |n| # Do something with Node n end
Mongoid::Tree does not handle destroying of nodes by default. However it provides several strategies that help you to deal with children of deleted documents. You can simply add them as
Available strategies are:
:nullify_children-- Sets the children's parent_id to null
:move_children_to_parent-- Moves the children to the current document's parent
:destroy_children-- Destroys all children by calling their
#destroymethod (invokes callbacks)
:delete_descendants-- Deletes all descendants using a database query (doesn't invoke callbacks)
class Node include Mongoid::Document include Mongoid::Tree before_destroy :nullify_children end
There are two callbacks that are called before and after the rearranging process. This enables you to do additional computations after the documents position in the tree is updated. See
Mongoid::Tree for details.
class Page include Mongoid::Document include Mongoid::Tree after_rearrange :rebuild_path field :slug field :path private def rebuild_path self.path = self.ancestors_and_self.collect(&:slug).join('/') end end
Mongoid::Tree currently does not validate the document's children or parent associations by default. To explicitly enable validation for children and parent documents it's required to add a
class Node include Mongoid::Document include Mongoid::Tree validates_associated :parent, :children end
mongoid-tree is on Travis CI running the specs on Ruby Head, Ruby 1.9.3, JRuby (1.9 mode), and Rubinius (1.9 mode).
See https://github.com/benedikt/mongoid-tree and feel free to fork it!
See a list of all contributors at https://github.com/benedikt/mongoid-tree/contributors. Thanks a lot everyone!
If you like mongoid-tree and want to support the development, I would appreciate a small donation:
Copyright (c) 2010-2013 Benedikt Deicke. See LICENSE for details.