Toller

URL-query-param-based filtering and sorting for Rails controllers.

Toller is a Rails engine that lets controllers declare filter_on/sort_on directives, then applies whichever filters and sorts are active for the current request to an ActiveRecord relation based on URL query parameters.

See the wiki for usage information.

Requirements

Ruby >= 3.3.0
Rails >= 6.0

Installation

Add this line to your application's Gemfile:

gem 'toller', '~> 1.0'

And then execute:

$ bundle install

Filtering

Filters are not automagically set up for you. You define the filters you want.

Filtering parameters are passed in the URL as such ?filters[visible]=1. Multiple filter parameters can be passed like so ?filters[visible]=1&filters[published_after]=2020-07-04.

More information is available in the wiki.

Sorting

Sorting is not automagically set up for you. You define the sorting you want.

Sorting parameters are passed in the URL as such ?sort=position. Multiple sort parameters can be passed like so ?sort=-published_at,title.

More information is available in the wiki.

Testing

$ bin/test

Appraisal

Uses Appraisal2 (a maintained fork of Appraisal, still exposing the appraisal executable) to ensure various dependency versions work as expected

When dependencies change, run

$ bundle exec appraisal install
$ bundle exec appraisal generate-install

To run tests with Appraisal, run

$ bundle exec appraisal rspec

-n 1 forces Appraisal2 to run one Rails version at a time. Without it, Appraisal2 defaults to running 2 appraisals in parallel, and since every appraisal shares the same test/dummy/db/test.sqlite3 file, concurrent runs can intermittently fail with SQLite3::BusyException: database is locked.

$ bundle exec appraisal rails-6-0 rspec
$ bundle exec appraisal rails-6-1 rspec
$ bundle exec appraisal rails-7-0 rspec
$ bundle exec appraisal rails-7-1 rspec
$ bundle exec appraisal rails-7-2 rspec
$ bundle exec appraisal rails-8-0 rspec
$ bundle exec appraisal rails-8-1 rspec

Release

See Release.md

Code Analysis

Various tools are used to ensure code is linted and formatted correctly.

RuboCop

RuboCop is a Ruby static code analyzer.

$ rubocop

YARD-Lint

YARD-Lint is a linter for YARD documentation.

$ bundle exec yard-lint

Documentation

Yard is used to generate documentation. Online documentation is available

Build the documentation with one of the following

$ yard
$ yard doc

Build the documentation and list all undocumented objects

$ yard stats --list-undoc

Contributing

Fork it (https://github.com/dfrerksen/toller/fork)
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

License

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