# 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:

```ruby
gem "lexoranking", "~> 1.3"
```

And then execute:

    $ bundle install

To generate the require migration for your models execute:

```ruby
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.

```ruby
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
```ruby
rails db:migrate
```
## Usage

Declare your model as a lexoranking model
```ruby
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.

```ruby
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.
```ruby
# 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.
```ruby
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.

```ruby
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.

```ruby
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.

```ruby
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](https://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](https://github.com/[USERNAME]/lexoranking/blob/master/CODE_OF_CONDUCT.md).


## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

## 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](https://github.com/[USERNAME]/lexoranking/blob/master/CODE_OF_CONDUCT.md).