simple_listing_rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dcde66c4f015e09e79441ce4dddd6e82047df681
+  data.tar.gz: 46bd5fc5b24a3b6de8ecbbe6d807dbde2cc7eb73
+SHA512:
+  metadata.gz: 4569d75905bdf6ba38e3b0a2824a94d80f9dfea627ff093a25a8a6d7370f06b283e44057be58ed0530375cca779e398e04662299b2b4fa356880bbb7b84b9ea1
+  data.tar.gz: 39e34bda2d1098f3ddd3a84008cd45df283408ce5cd1ed4668050ad8ce0718f2ea07b7d996803e0ecc711bf34c12cf8cd934e9494d7bc4d44f07ddbd69daa23f

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in simple_listing_rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Pavel Shutin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,151 @@
+# SimpleListingRails
+
+This gem provides easy listing objects for your ActiveRecord relations.
+
+## Why
+
+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.
+
+## Installation
+
+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
+
+## Usage
+
+### Minimal required code
+
+First of all you need to define a listing class. E.g.
+
+```ruby
+class UserListing < SimpleListing::Standard
+end
+```
+
+and then use it in your controller with "perform" function:
+
+```ruby
+def index
+  @users = UserListing(User.all, params).perform
+end
+```
+
+Now you can add some filters or sortings declaration to your class.
+
+### Filtering
+
+#### Simple "equal" filters
+
+You can add strict match filter to your listing class with only one line:
+
+```ruby
+class UserListing < SimpleListing::Standard
+  filterable_by :first_name, :last_name, :email
+end
+```
+
+`filterable_by` will perform "=" comparision with corresponding value in DB.
+
+#### Custom filters
+
+If you need your own custom filter with custom logic you can use `filter_by` function:
+
+```ruby
+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.:
+
+```ruby
+class UserListing < SimpleListing::Standard
+  filter_by :age, lambda { |scope, value, listing|
+    scope.where("age > :min AND age < :max", value)
+  }
+end
+```
+
+#### Filters configuration
+
+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
+
+```ruby
+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.
+
+### Sorting
+
+#### Simple sorting by DB field
+
+You can add sortings to your listing class with only one line:
+
+```ruby
+class UserListing < SimpleListing::Standard
+  sortable_by :first_name, :last_name, :email
+end
+```
+
+#### Custom sorting
+
+If you need your own custom sorting with custom logic you can use `sort_by` function:
+
+```ruby
+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.
+
+#### Sorters configuration
+
+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
+
+```ruby
+class UserListing < SimpleListing::Standard
+  config sort_by_param_key: :sind, sort_direction_param_key: :sord
+end
+```
+
+See more details in source code.
+
+### Customizing your listings
+
+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.
+
+## Contributing
+
+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
+
+
+

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/lib/simple_listing.rb

@@ -0,0 +1,9 @@
+require "simple_listing/configurable"
+require "simple_listing/base"
+require "simple_listing/filterable"
+require "simple_listing/paginatable"
+require "simple_listing/sortable"
+require "simple_listing/standard"
+
+module SimpleListing
+end

data/lib/simple_listing/base.rb

@@ -0,0 +1,27 @@
+require 'simple_listing/configurable'
+
+module SimpleListing
+  class Base
+    include Configurable
+
+    delegate :config, to: :class
+
+    attr_accessor :scope, :params
+    private :scope=, :params=
+
+    def initialize(scope, params)
+      @scope, @params = scope, params
+    end
+
+    def perform
+      yield self if block_given?
+      scope
+    end
+
+    private
+
+    def guard(message = nil)
+      raise(ArgumentError, message) unless yield == true
+    end
+  end
+end

data/lib/simple_listing/configurable.rb

@@ -0,0 +1,17 @@
+module SimpleListing
+  module Configurable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def config(config_hash = nil)
+        self.configuration = configuration.merge(config_hash) if config_hash
+        configuration
+      end
+    end
+
+    included do
+      class_attribute :configuration
+      self.configuration = {}
+    end
+  end
+end

data/lib/simple_listing/filterable.rb

@@ -0,0 +1,59 @@
+module SimpleListing
+  module Filterable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      attr_reader :filterable_keys
+      attr_reader :filtering_handlers
+
+      def filterable_by(*keys)
+        @filterable_keys ||= []
+        @filterable_keys += keys.map(&:to_s)
+        @filterable_keys.uniq!
+      end
+
+      def filter_by(key, handler_proc)
+        filterable_by key
+        @filtering_handlers ||= {}.with_indifferent_access
+        @filtering_handlers[key] = handler_proc
+      end
+    end
+
+    included do
+      delegate :filtering_handlers, :filterable_keys, to: :class
+
+      config filter_params_key: :filters
+    end
+
+    def perform
+      super
+      apply_filters if should_be_filtered?
+      scope
+    end
+
+    def filter_params
+      params[config[:filter_params_key]]
+    end
+
+    def should_be_filtered?
+      filter_params && filter_params.respond_to?(:each)
+    end
+
+    private
+
+    def apply_filters
+      filter_params.each do |key, value|
+        guard("incorrect filter key '#{key}'") { filterable_by?(key) }
+        self.scope = if handler = filtering_handlers[key]
+                       handler.call(scope, value, self)
+                     else
+                       scope.where(key => value)
+                     end
+      end
+    end
+
+    def filterable_by?(key)
+      key.to_s.in? filterable_keys
+    end
+  end
+end

data/lib/simple_listing/paginatable.rb

@@ -0,0 +1,33 @@
+module SimpleListing
+  module Paginatable
+    extend ActiveSupport::Concern
+
+    included do
+      config page_param_key: :page, per_page_param_key: :per_page
+    end
+
+    def perform
+      super
+      apply_pagination if should_be_paginated?
+      scope
+    end
+
+    def page
+      params[config[:page_param_key]]
+    end
+
+    def per_page
+      params[config[:per_page_param_key]]
+    end
+
+    def should_be_paginated?
+      page && per_page
+    end
+
+    private
+
+    def apply_pagination
+      self.scope = scope.page(page).per(per_page)
+    end
+  end
+end

data/lib/simple_listing/sortable.rb

@@ -0,0 +1,72 @@
+module SimpleListing
+  module Sortable
+    extend ActiveSupport::Concern
+
+    SORT_DIRECTIONS = %w{asc desc}.freeze
+
+    module ClassMethods
+      attr_reader :sortable_keys
+      attr_reader :sorting_handlers
+
+      def sortable_by(*keys)
+        @sortable_keys ||= []
+        @sortable_keys += keys.map(&:to_s)
+        @sortable_keys.uniq!
+      end
+
+      def sort_by(key, handler_proc)
+        sortable_by key
+        @sorting_handlers ||= {}.with_indifferent_access
+        @sorting_handlers[key] = handler_proc
+      end
+    end
+
+    included do
+      delegate :sorting_handlers, :sortable_keys, to: :class
+
+      config sort_by_param_key: :sort_by, sort_direction_param_key: :sort_dir
+    end
+
+    def perform
+      super
+      apply_sorting if should_be_sorted?
+      scope
+    end
+
+    def sort_value
+      @sort_value ||= params[config[:sort_by_param_key]].tap do |value|
+        guard("incorrect sorting value '#{value}'") { sortable_by?(value) }
+      end
+    end
+
+    def sort_direction
+      @sort_direction ||= begin
+        direction = params[config[:sort_direction_param_key]]
+        guard("incorrect sorting direction '#{direction}'") { direction.in? SORT_DIRECTIONS }
+        direction.to_sym
+      end
+    end
+
+    def inverted_sort_direction
+      sort_direction == :asc ? :desc : :asc
+    end
+
+    def should_be_sorted?
+      params[config[:sort_by_param_key]] && params[config[:sort_direction_param_key]]
+    end
+
+    private
+
+    def apply_sorting
+      self.scope = if handler = sorting_handlers[sort_value]
+                     handler.call(scope, sort_direction, self)
+                   else
+                     scope.order(sort_value => sort_direction)
+                   end
+    end
+
+    def sortable_by?(value)
+      sortable_keys.include? value
+    end
+  end
+end

data/lib/simple_listing/standard.rb

@@ -0,0 +1,11 @@
+require "simple_listing/base"
+require "simple_listing/filterable"
+require "simple_listing/paginatable"
+require "simple_listing/sortable"
+
+module SimpleListing
+  class Standard < Base
+    include Filterable
+    include Sortable
+  end
+end

data/lib/simple_listing_rails.rb

@@ -0,0 +1,6 @@
+require "simple_listing_rails/version"
+require 'simple_listing'
+
+module SimpleListingRails
+  # Your code goes here...
+end

data/lib/simple_listing_rails/version.rb

@@ -0,0 +1,3 @@
+module SimpleListingRails
+  VERSION = "0.0.1"
+end

data/simple_listing_rails.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'simple_listing_rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "simple_listing_rails"
+  spec.version       = SimpleListingRails::VERSION
+  spec.authors       = ["Pavel Shutsin"]
+  spec.email         = ["publicshady@gmail.com"]
+  spec.summary       = 'Simple classes for listing actions in your Rails app.'
+  spec.description   = 'This gem provides easy and flexible way to write listing actions in your Rails app. It provides nice DSL for filtering, sorting and paginating in your listings.'
+  spec.homepage      = "https://github.com/pluff/simple_listing_rails"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'activerecord', '~> 4.0'
+  spec.add_dependency 'activesupport', '~> 4.0'
+
+  spec.add_development_dependency "bundler", "~> 1.6"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: simple_listing_rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Pavel Shutsin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This gem provides easy and flexible way to write listing actions in your
+  Rails app. It provides nice DSL for filtering, sorting and paginating in your listings.
+email:
+- publicshady@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/simple_listing.rb
+- lib/simple_listing/base.rb
+- lib/simple_listing/configurable.rb
+- lib/simple_listing/filterable.rb
+- lib/simple_listing/paginatable.rb
+- lib/simple_listing/sortable.rb
+- lib/simple_listing/standard.rb
+- lib/simple_listing_rails.rb
+- lib/simple_listing_rails/version.rb
+- simple_listing_rails.gemspec
+homepage: https://github.com/pluff/simple_listing_rails
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Simple classes for listing actions in your Rails app.
+test_files: []