A tree structure for Mongoid documents using the materialized path pattern
- mongoid (>= 4.0, < 9.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', branch: :main
You might want to add require: nil
option and explicitly require 'mongoid/tree'
where needed and finally run
bundle install
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 https://www.rubydoc.info/github/benedikt/mongoid-tree and take a look at the Mongoid::Tree
module
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)
See 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?
Example:
class Node
include Mongoid::Document
include Mongoid::Tree
include Mongoid::Tree::Ordering
end
See Mongoid::Tree::Ordering
for more information on these methods.
It's possible to traverse the tree using different traversal methods using the Mongoid::Tree::Traversal
module.
Example:
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 before_destroy
callbacks.
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#destroy
method (invokes callbacks):delete_descendants
-- Deletes all descendants using a database query (doesn't invoke callbacks)
Example:
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.
Example:
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 validates_associated
validation.
Example:
class Node
include Mongoid::Document
include Mongoid::Tree
validates_associated :parent, :children
end
mongoid-tree is on GitHub Actions running the specs on Ruby 2.7-3.2 and Mongoid 4.x-8.x.
See https://github.com/benedikt/mongoid-tree/issues
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!
Copyright (c) 2010-2023 Benedikt Deicke. See LICENSE for details.