Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
684cd42
commit 199473e
Showing
2 changed files
with
19 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1 @@ | ||
{"name":"Simple filter","tagline":"A simple DSL to create filter classes for ActiveRecord scopes","body":"[![Code Climate](https://codeclimate.com/github/matiasleidemer/simple_filter/badges/gpa.svg)](https://codeclimate.com/github/matiasleidemer/simple_filter) [![Build Status](https://travis-ci.org/matiasleidemer/simple_filter.svg)](https://travis-ci.org/matiasleidemer/simple_filter)\r\n\r\n# SimpleFilter\r\n\r\nSimpleFilter is a very simple ruby _DSL_ to write filter (or search) classes for ActiveRecord scopes. It's only responsability is to map parameters to defined scopes.\r\n\r\n## Usage\r\n\r\nTo use search classes is pretty straightforward:\r\n\r\n```ruby\r\nFooSearch.new(params = {}).scoping(Model.all).search\r\n```\r\n\r\n`params` should be a hash containing all the desired filters, and `scope` is the current model scope that the filters will be applied into, for example:\r\n\r\n```ruby\r\nclass CampaignsController < ApplicationController\r\n def index\r\n @campaigns = CampaignSearcher.new(search_params).scoping(Campaign.all).search\r\n end\r\n\r\n private\r\n \r\n def search_params\r\n params.slice(:name, :category, :whatever)\r\n end\r\nend\r\n```\r\n\r\nThe `search` method returns an `ActiveRecord::Relation`, making it easy to chain other scopes or conditions when needed.\r\n\r\n### Filter\r\n\r\nFilter is the class method that creates a new filter (really?!). Here's a simple example:\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n \r\nend\r\n\r\n# Usage\r\nFooSearch.new(active: true).scoping(Foo.all).search\r\n\r\n# Which is the same as\r\nFoo.all.active\r\n```\r\n\r\nYou can apply whatever scope needed:\r\n\r\n```ruby\r\nFooSearch.new(active: true).scoping(current_user.posts).search\r\n# => current_user.posts.active\r\n```\r\n\r\nYou can also create a filter that calls the scope method with the parameter value using the option `value_param: true`\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n filter :by_name, value_param: true\r\nend\r\n\r\nFooSearch.new(by_name: 'Matias').scoping(Foo.all).search\r\n# => Foo.all.by_name('Matias')\r\n\r\nFooSearch.new(by_name: 'Matias', active: true).scoping(Foo.all).search\r\n# => Foo.all.active.by_name('Matias')\r\n```\r\n\r\nOf course you have to define those scopes in your ActiveRecord model:\r\n\r\n```ruby\r\nclass Foo < ActiceRecord::Base\r\n scope :active, -> { where active: true }\r\n scope :by_name, -> (name) { where 'name like ?', \"%#{name}%\" }\r\nend\r\n```\r\n\r\n### Custom filters\r\n\r\nLastly, you can create fully customized filters. Let's say you want to apply a specific filter only when some condition is true\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n filter :name, value_param: true\r\n filter :within_period\r\n \r\n def within_period\r\n return unless date_range?\r\n \r\n scope.where('start_at >= ? and end_at <= ?', params[:start_at], params[:end_at])\r\n end\r\n \r\n private\r\n \r\n def date_range?\r\n params[:start_at].present? && params[:end_at].present?\r\n end\r\nend\r\n\r\nFooSearch.new(start_at: '2015-05-08', end_at: '2015-05-31').scoping(Foo.all).search\r\n```\r\n\r\nNote that in the example above I'm using `params` and `scope` attributes. You can use it the create custom conditions and validation for your filters. It's important that your custom filters always return a `ActiveRecord::Relation` object, since it will chain it with the other filters.\r\n\r\nIt's also possible to call `super` when you define your custom filters, this happens because of the way filters are defined in the `SimpleFilter::Base` class.\r\n\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n \r\n def active\r\n super.where 'some other condition'\r\n end\r\nend\r\n\r\n```\r\n\r\n## Development\r\n\r\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.\r\n\r\nTo 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\r\n\r\n## Contributing\r\n\r\n1. Fork it ( https://github.com/matiasleidemer/simple_filter/fork )\r\n2. Create your feature branch (`git checkout -b my-new-feature`)\r\n3. Commit your changes (`git commit -am 'Add some feature'`)\r\n4. Push to the branch (`git push origin my-new-feature`)\r\n5. Create a new Pull Request\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."} | ||
{"name":"Simple filter","tagline":"A simple DSL to create filter classes for ActiveRecord scopes","body":"[![Code Climate](https://codeclimate.com/github/matiasleidemer/simple_filter/badges/gpa.svg)](https://codeclimate.com/github/matiasleidemer/simple_filter) [![Build Status](https://travis-ci.org/matiasleidemer/simple_filter.svg)](https://travis-ci.org/matiasleidemer/simple_filter)\r\n\r\n# SimpleFilter\r\n\r\nSimpleFilter is a very simple ruby _DSL_ to write filter (or search) classes for ActiveRecord scopes. It's only responsability is to map parameters to defined scopes.\r\n\r\nIt currently works with ActiveRecord 4.0 or greater.\r\n\r\n## Instalation\r\n\r\nUnfortunetely there's already a gem called `simple_form`, but fear not, you only need to require the lib in your Gemfile:\r\n\r\n```ruby\r\ngem 'simple-form', require: 'simple_form'\r\n```\r\n\r\n## Usage\r\n\r\nTo use search classes is pretty straightforward:\r\n\r\n```ruby\r\nFooSearch.new(params = {}).scoping(Model.all).search\r\n```\r\n\r\n`params` should be a hash containing all the desired filters, and `scope` is the current model scope that the filters will be applied into, for example:\r\n\r\n```ruby\r\nclass CampaignsController < ApplicationController\r\n def index\r\n @campaigns = CampaignSearcher.new(search_params).scoping(Campaign.all).search\r\n end\r\n\r\n private\r\n \r\n def search_params\r\n params.slice(:name, :category, :whatever)\r\n end\r\nend\r\n```\r\n\r\nThe `search` method returns an `ActiveRecord::Relation`, making it easy to chain other scopes or conditions when needed.\r\n\r\n### Filter\r\n\r\nFilter is the class method that creates a new filter (really?!). Here's a simple example:\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n \r\nend\r\n\r\n# Usage\r\nFooSearch.new(active: true).scoping(Foo.all).search\r\n\r\n# Which is the same as\r\nFoo.all.active\r\n```\r\n\r\nYou can apply whatever scope needed:\r\n\r\n```ruby\r\nFooSearch.new(active: true).scoping(current_user.posts).search\r\n# => current_user.posts.active\r\n```\r\n\r\nYou can also create a filter that calls the scope method with the parameter value using the option `value_param: true`\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n filter :by_name, value_param: true\r\nend\r\n\r\nFooSearch.new(by_name: 'Matias').scoping(Foo.all).search\r\n# => Foo.all.by_name('Matias')\r\n\r\nFooSearch.new(by_name: 'Matias', active: true).scoping(Foo.all).search\r\n# => Foo.all.active.by_name('Matias')\r\n```\r\n\r\nOf course you have to define those scopes in your ActiveRecord model:\r\n\r\n```ruby\r\nclass Foo < ActiceRecord::Base\r\n scope :active, -> { where active: true }\r\n scope :by_name, -> (name) { where 'name like ?', \"%#{name}%\" }\r\nend\r\n```\r\n\r\n### Custom filters\r\n\r\nLastly, you can create fully customized filters. Let's say you want to apply a specific filter only when some condition is true\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n filter :name, value_param: true\r\n filter :within_period\r\n \r\n def within_period\r\n return unless date_range?\r\n \r\n scope.where('start_at >= ? and end_at <= ?', params[:start_at], params[:end_at])\r\n end\r\n \r\n private\r\n \r\n def date_range?\r\n params[:start_at].present? && params[:end_at].present?\r\n end\r\nend\r\n\r\nFooSearch.new(start_at: '2015-05-08', end_at: '2015-05-31').scoping(Foo.all).search\r\n```\r\n\r\nNote that in the example above I'm using `params` and `scope` attributes. You can use it the create custom conditions and validation for your filters. It's important that your custom filters always return a `ActiveRecord::Relation` object, since it will chain it with the other filters.\r\n\r\nIt's also possible to call `super` when you define your custom filters, this happens because of the way filters are defined in the `SimpleFilter::Base` class.\r\n\r\n\r\n```ruby\r\nclass FooSearch < SimpleFilter::Base\r\n filter :active\r\n \r\n def active\r\n super.where 'some other condition'\r\n end\r\nend\r\n```\r\n\r\n## Todo\r\n\r\n- Ordering\r\n- Pagination\r\n\r\n## Development\r\n\r\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.\r\n\r\nTo 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\r\n\r\n## Contributing\r\n\r\n1. Fork it ( https://github.com/matiasleidemer/simple_filter/fork )\r\n2. Create your feature branch (`git checkout -b my-new-feature`)\r\n3. Commit your changes (`git commit -am 'Add some feature'`)\r\n4. Push to the branch (`git push origin my-new-feature`)\r\n5. Create a new Pull Request\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."} |