SimpleListingRails

This gem provides easy listing objects for your ActiveRecord relations.

Usually application listings have are sortable, filterable and can be paginated. I need an easy straightforward way to write flexible filters and sortings for my app, so I created this gem.

Add this line to your application's Gemfile:

gem 'simple_listing_rails'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install simple_listing_rails

First of all you need to define a listing class. E.g.

class UserListing < SimpleListing::Standard
end

and then use it in your controller with "perform" function:

def index
  @users = UserListing(User.all, params).perform
end

Now you can add some filters or sortings declaration to your class.

You can add strict match filter to your listing class with only one line:

class UserListing < SimpleListing::Standard
  filterable_by :first_name, :last_name, :email
end

filterable_by will perform "=" comparision with corresponding value in DB.

If you need your own custom filter with custom logic you can use filter_by function:

class UserListing < SimpleListing::Standard
  filter_by :email, lambda { |scope, value, listing|
    scope.where("email LIKE ?", "%#{value}")
  }
end

filter_by accepts filtering key and lambda-function with your own custom logic. As you see lambda accepts 3 arguments and MUST return a scope.

Keep in mind that "value" parameter can be a hash, so you can create complex filters e.g.:

class UserListing < SimpleListing::Standard
  filter_by :age, lambda { |scope, value, listing|
    scope.where("age > :min AND age < :max", value)
  }
end

By default simple_listing pulls filters data from "params[:filters]". If you need to change params key you can do it so by calling "config" function

class UserListing < SimpleListing::Standard
  config filter_params_key: :my_filters
end

In case you need completely different behavior you can override "filter_params" function in your listing class.

See more details in source code.

You can add sortings to your listing class with only one line:

class UserListing < SimpleListing::Standard
  sortable_by :first_name, :last_name, :email
end

If you need your own custom sorting with custom logic you can use sort_by function:

class UserListing < SimpleListing::Standard
  sort_by :email, lambda { |scope, direction, listing|
    scope.order("CONCAT(first_name, last_name) #{direction}")
  }
end

sort_by accepts sorting key and lambda-function with your own custom logic. As you see lambda accepts 3 arguments and MUST return a scope.

By default simple_listing pulls sorting data from "params[:sort_by]" and "params[:sort_dir]". If you need to change params keys you can do it so by calling "config" function

class UserListing < SimpleListing::Standard
  config sort_by_param_key: :sind, sort_direction_param_key: :sord
end

See more details in source code.

In rare case when you want to remove sorting or filtering ability from your listing you can always inherit from "SimpleListing::Base" class and include only modules you need.

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