Skip to content
Acts as list mongoid implementation
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib
spec
.gitignore
.rspec
.rvmrc
.travis.yml
CHANGELOG.md Version bump Oct 21, 2015
Gemfile
README.md
Rakefile
mongoid_orderable.gemspec

README.md

Gem Version Build Status

What?

Mongoid::Orderable is a ordered list implementation for your Mongoid 2, 3, 4 and 5 models.

Why?

  • It uses native mongo batch increment feature
  • It supports mutators api
  • It correctly assigns the position while moving document between scopes
  • It supports mongoid 2, 3 and 4
  • It supports specifying multiple orderable columns

How?

gem 'mongoid_orderable'

Gem has the same api as others. Just include Mongoid::Orderable into your model and call orderable method. Embedded objects are automatically scoped by their parent.

class Item
  include Mongoid::Document
  include Mongoid::Orderable

  # belongs_to :group
  # belongs_to :drawer, class_name: "Office::Drawer",
  #            foreign_key: "legacy_drawer_key_id"

  # orderable
  # orderable scope: :group, column: :pos
  # orderable scope: :drawer, column: :pos # resolves scope foreign key from relation
  # orderable scope: 'drawer', column: :pos # but if you pass a string - it will use it as is, as the column name for scope
  # orderable scope: lambda { |document| where(group_id: document.group_id) }
  # orderable index: false # this one if you want specify indexes manually
  # orderable base: 0 # count position from zero as the top-most value (1 is the default value)
end

Usage

item.move_to 2 # just change position
item.move_to! 2 # and save
item.move_to = 2 # assignable method

# symbol position
item.move_to :top
item.move_to :bottom
item.move_to :higher
item.move_to :lower

# generated methods
item.move_to_top
item.move_to_bottom
item.move_higher
item.move_lower

item.next_items # return a collection of items higher on the list
item.previous_items # return a collection of items lower on the list

item.next_item # returns the next item in the list
item.previous_item # returns the previous item in the list

Multiple Columns

You can also define multiple orderable columns for any class including the Mongoid::Orderable module.

class Book
  include Mongoid::Document
  include Mongoid::Orderable

  orderable base: 0
  orderable column: sno, as: :serial_no
end

The above defines two different orderable_columns on Book - position and serial_no. The following helpers are generated in this case:

item.move_#{column_name}_to
item.move_#{column_name}_to=
item.move_#{column_name}_to!

item.move_#{column_name}_to_top
item.move_#{column_name}_to_bottom
item.move_#{column_name}_higher
item.move_#{column_name}_lower

item.next_#{column_name}_items
item.previous_#{column_name}_items

item.next_#{column_name}_item
item.previous_#{column_name}_item

where column_name is either *position** or serial_no.*

When a model defines multiple orderable columns, the original helpers are also available and work on the first orderable column.

  @book1 = Book.create!
  @book2 = Book.create!
  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 1>
  @book2.move_to! :top   # this will change the :position of the book to 0 (not serial_no)
  @book2                 => #<Book _id: 53a16a2ba1bde4f746000001, serial_no: 1, position: 0>

To specify any other orderable column as default pass the default: true option with orderable.

  orderable column: sno, as: :serial_no, default: true

Embedded documents

class Question
  include Mongoid::Document
  include Mongoid::Orderable

  embedded_in :survey

  orderable
end

If you bulk import embedded documents without specifying their position, no field position will be written.

class Survey
  include Mongoid::Document

  embeds_many :questions, cascade_callbacks: true
end

To ensure the position is written correctly, you will need to provide the cascade callbacks option to the relation.

Contributing

Fork && Patch && Spec && Push && Pull request.

License

Mongoid::Orderable is released under the MIT license.

Something went wrong with that request. Please try again.