{"id":15403937,"url":"https://github.com/pluff/simple_listing_rails","last_synced_at":"2025-02-24T14:43:49.749Z","repository":{"id":26661550,"uuid":"30117915","full_name":"pluff/simple_listing_rails","owner":"pluff","description":"Simple Listing classes for you rails actions. Filterable, sortable, paginatable.","archived":false,"fork":false,"pushed_at":"2015-02-04T21:28:50.000Z","size":136,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-07T11:51:35.318Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pluff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-31T16:25:39.000Z","updated_at":"2017-01-11T11:07:09.000Z","dependencies_parsed_at":"2022-07-25T16:00:06.306Z","dependency_job_id":null,"html_url":"https://github.com/pluff/simple_listing_rails","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pluff%2Fsimple_listing_rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pluff%2Fsimple_listing_rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pluff%2Fsimple_listing_rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pluff%2Fsimple_listing_rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pluff","download_url":"https://codeload.github.com/pluff/simple_listing_rails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240499263,"owners_count":19811438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T16:10:45.396Z","updated_at":"2025-02-24T14:43:49.725Z","avatar_url":"https://github.com/pluff.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SimpleListingRails\n\nThis gem provides easy listing objects for your ActiveRecord relations.\n\n## Why\n\nUsually application listings have are sortable, filterable and can be paginated.\nI need an easy straightforward way to write flexible filters and sortings for my app, so I created this gem.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'simple_listing_rails'\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install simple_listing_rails\n\n## Usage\n\n### Minimal required code\n\nFirst of all you need to define a listing class. E.g.\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\nend\n```\n\nand then use it in your controller with \"perform\" function:\n\n```ruby\ndef index\n  @users = UserListing(User.all, params).perform\nend\n```\n\nNow you can add some filters or sortings declaration to your class.\n\n### Filtering\n\n#### Simple \"equal\" filters\n\nYou can add strict match filter to your listing class with only one line:\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  filterable_by :first_name, :last_name, :email\nend\n```\n\n`filterable_by` will perform \"=\" comparision with corresponding value in DB.\n\n#### Custom filters\n\nIf you need your own custom filter with custom logic you can use `filter_by` function:\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  filter_by :email, lambda { |scope, value, listing|\n    scope.where(\"email LIKE ?\", \"%#{value}\")\n  }\nend\n```\n\n`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.\n\nKeep in mind that \"value\" parameter can be a hash, so you can create complex filters e.g.:\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  filter_by :age, lambda { |scope, value, listing|\n    scope.where(\"age \u003e :min AND age \u003c :max\", value)\n  }\nend\n```\n\n#### Filters configuration\n\nBy default simple_listing pulls filters data from \"params[:filters]\".\nIf you need to change params key you can do it so by calling \"config\" function\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  config filter_params_key: :my_filters\nend\n```\n\nIn case you need completely different behavior you can override \"filter_params\" function in your listing class.\n\nSee more details in source code.\n\n### Sorting\n\n#### Simple sorting by DB field\n\nYou can add sortings to your listing class with only one line:\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  sortable_by :first_name, :last_name, :email\nend\n```\n\n#### Custom sorting\n\nIf you need your own custom sorting with custom logic you can use `sort_by` function:\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  sort_by :email, lambda { |scope, direction, listing|\n    scope.order(\"CONCAT(first_name, last_name) #{direction}\")\n  }\nend\n```\n\n`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.\n\n#### Sorters configuration\n\nBy default simple_listing pulls sorting data from \"params[:sort_by]\" and \"params[:sort_dir]\".\nIf you need to change params keys you can do it so by calling \"config\" function\n\n```ruby\nclass UserListing \u003c SimpleListing::Standard\n  config sort_by_param_key: :sind, sort_direction_param_key: :sord\nend\n```\n\nSee more details in source code.\n\n### Customizing your listings\n\nIn rare case when you want to remove sorting or filtering ability from your listing\nyou can always inherit from \"SimpleListing::Base\" class and include only modules you need.\n\n## Contributing\n\n1. Fork it ( https://github.com/pluff/simple_listing_rails/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpluff%2Fsimple_listing_rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpluff%2Fsimple_listing_rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpluff%2Fsimple_listing_rails/lists"}