Lexoranking

Lexicographical sorting for ActiveRecord Models.

How does it work?

Allows your ActiveRecord models to sort its elements using lexographical sorting.

This is inpired by how Jira handles sorting of kanban board.

Installation

Add this line to your application's Gemfile:

gem "lexoranking", "~> 1.3"

And then execute:

$ bundle install

To generate the require migration for your models execute:

rails generate lexoranking:install --model=your_model

This will generate a migration file adding a rank column to your model, which is used to perform sorting.

class AddRankToProjects < ActiveRecord::Migration[6.1]
  def change
    add_column :projects, :rank, :text
    add_index :projects, :rank
  end
end

Then run the migration by executing

rails db:migrate

Usage

Declare your model as a lexoranking model

class Project < ApplicationRecord
  include Lexoranking::Model
end

Now when you create a new Project the sorting value for the rank column will be calculated automatically when saving the record to the data base.

project = Project.new(name: 'My Project', description: 'Random description')
project.save

#<Project:0x00007f9f6b4a2a38
  id: 1,
  name: 'My Project',
  description: 'Random description',
  rank: 'y'
>

Class Methods

The model will have access to the following class method.

# Retrieve the collection of Projects sorted by their ranking in ascending order
Project.ranked

Instance Methods

You will have access to the following instance methods.

project = Project.find(3)

# Rank the element to the last position of the list
project.rank_last

# Rank the record to the first position of the list
project.rank_first

# Rank the record to a specific position of the list
project.rank_to(4)

Working with Associations

If your model belongs to another model and you want to sort the elements scope to the association, you can simply add a class attribute that will allow your models to be sorted based on the scope they belong to.

For example, in an application where a Project model has many tasks. We can sort tasks using the project they belong to as the scope.

class Project < ApplicationRecord
  has_many :tasks
end

class Task < ApplicationRecord
  include Lexoranking::Model
  self.ranking_scope = :project_id

  belongs_to :project
end

Adding this class attribute to the model, allows your records to be sorted in the scope of the project they belong to.

You can also define a default scope for your models if you want to retreive the elements in the lexicographical order.

class Task < ApplicationRecord
  include Lexoranking::Model
  self.ranking_scope = :project_id
  default_scope { self.ranked }

  belongs_to :project
end

With this you can chain ActiveRecord methods and get all the elements in their right lexicographical order.

Project.last.tasks

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lexoranking. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Lexoranking project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.