Awesome

mongoid-ordering

mongoid-ordering makes it easy to keep your Mongoid documents in order.

Most of mongoid-ordering is based on the Mongoid::Tree::Ordering module from the mongoid-tree gem. I thought the ordering logic would be useful outside of the tree context as well, so I extracted it into the gem you're looking at right now.

Features

• Automatically order your query results by a new position attribute.
• Allow documents to be ordered within a certain scope.
• Handle changes in position when a document is destroyed or when a document is moved outside of this scope.
• Tons of utility methods to make working with ordered documents incredibly easy.

Requirements

• mongoid (~> 3.0)

Installation

Add the following to your Gemfile:

gem "mongoid-ordering", require: "mongoid/ordering"

And tell Bundler to install the new gem:

bundle install

Usage

Include the Mongoid::Ordering module in your document class:

class Book
  include Mongoid::Document
  include Mongoid::Ordering

  ...
end

This will take care of everything to get you going.

If you want to specify a scope within which to keep the documents in order, you can like this:

class Book
  include Mongoid::Document
  include Mongoid::Ordering

  belongs_to :author

  ordered scope: :author

  ...
end

You will now have access to the following methods:

# Retrieve siblings positioned above this document.
book.higher_siblings
# Retrieve siblings positioned below this document.
book.lower_siblings
# Retrieve the highest sibling.
book.highest_sibling
# Retrieve the lowest sibling.
book.lowest_sibling

# Is this the highest sibling?
book.at_top?
# Is this the lowest sibling?
book.at_bottom?

# Move document to the top.
book.move_to_top
# Move document to the bottom.
book.move_to_bottom
# Move document one position up.
book.move_up
# Move document one position down.
book.move_down
# Move document above another document.
book.move_above(other_book)
# Move document below another document.
book.move_below(other_book)

mongoid-ordering uses mongoid-siblings to get all of this to work, so you'll get the following methods as a bonus:

# Retrieve document's siblings
book.siblings
# Retrieve document's siblings and itself
book.siblings_and_self
# Is this document a sibling of the other document?
book.sibling_of?(other_book)
# Make document a sibling of the other document.
# This will move this book to the same scope as the other book.
book.sibling_of!(other_book)

Full documentation

See this project's RubyDoc.info page.

Known issues

See the GitHub Issues page.

License

Copyright (c) 2012 Douwe Maan

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.