with_filters 0.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp
+spec/dummy/log/*.log
+.yardoc
+doc

data/.yardopts

@@ -0,0 +1 @@
+--no-private --markup markdown

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Aaron Lasseigne
+
+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,63 @@
+# with_filters
+
+Add filtering to tables, lists, etc.
+
+This project follows [Semantic Versioning](http://semver.org/).
+
+## Installation
+
+    $ gem install with_filters
+
+If you're using Bundler, add this to your Gemfile:
+
+    gem 'with_filters', '~> 0.1.0'
+
+## Support
+
+<table>
+  <tr>
+    <td><strong>Ruby</strong></td>
+    <td>1.9</td>
+  </tr>
+  <tr>
+    <td><strong>Rails</strong></td>
+    <td>3.1</td>
+  </tr>
+  <tr>
+    <td><strong>Database Framework</strong></td>
+    <td>ActiveRecord</td>
+  </tr>
+</table>
+
+## Usage
+
+In your controller:
+
+    @data = Data.with_filters(params, fields: {
+      email_address: {match: :contains},
+      full_name:     ->(value, scope) {
+        first_word, second_word = value.strip.split(/\s+/)
+
+        if second_word
+          scope.where(['first_name LIKE ? OR last_name LIKE ?', first_word, first_word])
+        else
+          scope.where(['first_name LIKE ? AND last_name LIKE ?', first_word, second_word])
+        end
+      }
+    }).order('created_at DESC').page(params[:page] || 1)
+
+In your view:
+
+    <%= filter_form_for(@data) do |f| %>
+      <%# pass through variables needed in the form but not associated with filtering %>
+      <% if params[:order] %>
+        <% f.hidden(:order, name: 'order', value: params[:order]) %>
+      <% end %>
+
+      <% f.input(:id) %>
+      <% f.input_range(:created_at, label: 'Account Created On') %> <%# creates a filter to search a range %>
+      <% f.input(:full_name) %>
+      <% f.input(:email_address) %>
+
+      <% f.action(:submit, label: 'Filter') %>
+    <% end %>

data/Rakefile

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

data/app/views/with_filters/_filter_form.html.erb

@@ -0,0 +1,14 @@
+<%= form_tag(nil, filter_form.attrs) do %>
+  <%= with_filters_hidden(filter_form.hidden_filters) %>
+
+  <% filter_form.filters.each do |filter| %>
+    <%= with_filters_input(filter) %><br/>
+  <% end %>
+
+  <% if filter_form.actions.any? %>
+    <br/>
+    <% filter_form.actions.each do |action|  %>
+      <%= with_filters_action_tag(action) %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/views/with_filters/filter/_check_box.html.erb

@@ -0,0 +1,2 @@
+<%= with_filters_label_tag(filter) %><br/>
+<%= check_box_tag(filter.field_name, filter.value, filter.selected?, filter.attrs) %>

data/app/views/with_filters/filter/_check_boxes.html.erb

@@ -0,0 +1,5 @@
+<%= with_filters_label(filter) %>
+<% filter.collection.each do |choice| %>
+  <%= check_box_tag(choice.field_name, choice.value, choice.selected?, choice.attrs) %>
+  <%= label_tag(choice.attrs[:id], choice.label) %><br/>
+<% end %>

data/app/views/with_filters/filter/_radio.html.erb

@@ -0,0 +1,5 @@
+<%= with_filters_label(filter) %>
+<% filter.collection.each do |choice| %>
+  <%= radio_button_tag(choice.field_name, choice.value, choice.selected?, choice.attrs) %>
+  <%= label_tag(choice.attrs[:id], choice.label) %><br/>
+<% end %>

data/app/views/with_filters/filter/_select.html.erb

@@ -0,0 +1,2 @@
+<%= with_filters_label_tag(filter) %><br/>
+<%= with_filters_select_tag(filter) %>

data/app/views/with_filters/filter/_select_range.html.erb

@@ -0,0 +1,4 @@
+<%= with_filters_label_tag(filter.start) %><br/>
+<%= with_filters_select_tag(filter.start) %><br/>
+<%= with_filters_label_tag(filter.stop) %><br/>
+<%= with_filters_select_tag(filter.stop) %>

data/app/views/with_filters/filter/_text.html.erb

@@ -0,0 +1,2 @@
+<%= with_filters_label_tag(filter) %><br/>
+<%= with_filters_text_field_tag(filter) %>

data/app/views/with_filters/filter/_text_range.html.erb

@@ -0,0 +1,4 @@
+<%= with_filters_label_tag(filter.start) %><br/>
+<%= with_filters_text_field_tag(filter.start) %><br/>
+<%= with_filters_label_tag(filter.stop) %><br/>
+<%= with_filters_text_field_tag(filter.stop) %>

data/changelog.md

@@ -0,0 +1,2 @@
+## 0.1.0
+ * initial release

data/lib/generators/with_filters/theme/theme_generator.rb

@@ -0,0 +1,43 @@
+module WithFilters
+  class ThemeGenerator < Rails::Generators::NamedBase
+    desc('Create a new theme.')
+
+    VIEW_PATH = 'app/views/with_filters'
+
+    source_root File.expand_path("../../../../../#{VIEW_PATH}", __FILE__)
+
+    argument :partial, required: false
+
+    # A generator to create a theme. Any files missing from the theme will fall
+    # back to the original theme. It's recommended that you only generate the
+    # files you plan to change.
+    #
+    # @example Create an entire theme.
+    #   $ rails generate with_filters:theme foo
+    #
+    # @example Create a single file.
+    #   $ rails generate with_filters:theme foo filter_form
+    #
+    # @since 0.1.0
+    def create_theme
+      empty_directory(VIEW_PATH)
+
+      if partial
+        if partial.index('/')
+          (extra_dirs, partial_name) = partial.match(/^(.*)\/(.*)$/).captures
+
+          empty_directory("#{VIEW_PATH}/#{file_name}/#{extra_dirs}")
+
+          copy_file(
+            "#{extra_dirs}/_#{partial_name.match(/^text_as_/) ? 'text' : partial_name}.html.erb",
+            "#{VIEW_PATH}/#{file_name}/#{extra_dirs}/_#{partial_name}.html.erb"
+          )
+        else
+          copy_file("_#{partial}.html.erb", "#{VIEW_PATH}/#{file_name}/_#{partial}.html.erb")
+        end
+      else
+        directory('', "#{VIEW_PATH}/#{file_name}")
+      end
+    end
+  end
+end

data/lib/with_filters/action_view_extension.rb

@@ -0,0 +1,110 @@
+module WithFilters
+  module ActionViewExtension
+    include WithFilters::HashExtraction
+
+    # Create a filter form.
+    #
+    # @param records [ActiveRecord::Relation, Array] The data being filtered.
+    # @param options [Hash]
+    # @option options [String] :theme The theme to use when rendering the form.
+    # @option options [Varied] remaining ("{'novalidate: 'novalidate', method: 'get'}")
+    #   All other options are passed as options to the `form_tag` helper.
+    #
+    # @example
+    #   <%= filter_form_for(@data, theme: 'foo', class: 'bar') do |f|
+    #     f.input(:full_name)
+    #     f.input(:email)
+    #   end %>
+    #
+    # @since 0.1.0
+    def filter_form_for(records, options = {})
+      filter_form = WithFilters::FilterForm.new(records, self.extract_hash_value(params, records.with_filters_data[:param_namespace]) || {}, options)
+      yield(filter_form)
+
+      render(partial: filter_form.to_partial_path, locals: {filter_form: filter_form})
+    end
+
+    # Create hidden inputs.
+    #
+    # @param [Array<Filter>] hidden_filters
+    #
+    # @since 0.1.0
+    def with_filters_hidden(hidden_filters)
+      hidden_filters.map{|hidden_filter|
+        hidden_field_tag(hidden_filter.field_name, hidden_filter.value, hidden_filter.attrs)
+      }.join("\n").html_safe
+    end
+
+    # Create an input based on the type of `filter` provided.
+    #
+    # @param [Filter] filter
+    #
+    # @since 0.1.0
+    def with_filters_input(filter)
+      render(partial: filter.to_partial_path, locals: {filter: filter})
+    end
+
+    # Create an text like `input` tag based on the `filter`.
+    #
+    # @param [Filter] filter
+    #
+    # @since 0.1.0
+    def with_filters_text_field_tag(filter)
+      text_field_tag(filter.field_name, filter.value, filter.attrs)
+    end
+
+    # Create a `label` tag based on the `filter`.
+    #
+    # @param [Filter] filter
+    #
+    # @since 0.1.0
+    def with_filters_label_tag(filter)
+      label_tag(filter.field_name, filter.label, filter.label_attrs)
+    end
+
+    # Create a `label` tag for individual fields or a `div` tag in its place in
+    # the case of fields where the `label` tags are used for individual items.
+    #
+    # @param [Filter] filter
+    #
+    # @since 0.1.0
+    def with_filters_label(filter)
+      if [WithFilters::Filter::Radio, WithFilters::Filter::CheckBox].include?(filter.class) and filter.collection.any?
+        content_tag(:div, filter.label, filter.label_attrs)
+      else
+        with_filters_label_tag(filter)
+      end
+    end
+
+    # Create a `select` tag based on the `filter`.
+    #
+    # @param [Filter] filter
+    #
+    # @since 0.1.0
+    def with_filters_select_tag(filter)
+      collection = filter.collection
+      unless filter.collection.is_a?(String)
+        collection = filter.collection.map do |choice|
+          html_attributes = choice.attrs.length > 0 ? ' ' + choice.attrs.map {|k, v| %(#{k.to_s}="#{v}")}.join(' ') : ''
+          selected_attribute = choice.selected? ? ' selected="selected"' : ''
+
+          %(<option value="#{ERB::Util.html_escape(choice.value)}"#{selected_attribute}#{html_attributes}>#{ERB::Util.html_escape(choice.label)}</option>)
+        end.join("\n")
+      end
+
+      select_tag(filter.field_name, collection.html_safe, filter.attrs)
+    end
+
+    # @param [WithFilters::Action] action
+    #
+    # @since 0.1.0
+    def with_filters_action_tag(action)
+      case action.type
+      when :submit
+        submit_tag(action.attrs.delete(:value), action.attrs)
+      when :reset
+        button_tag(action.attrs.delete(:value) || 'Reset', action.attrs)
+      end
+    end
+  end
+end

data/lib/with_filters/active_record_extension.rb

@@ -0,0 +1,26 @@
+module WithFilters
+  # @private
+  module ActiveRecordExtension
+    extend ActiveSupport::Concern
+
+    included do
+      class << self
+        alias_method_chain :inherited, :with_filters
+      end
+
+      # Attach the ActiveRecord extensions to children of ActiveRecord that were initiated before we loaded WithFilters.
+      self.descendants.each do |descendant|
+        descendant.send(:include, WithFilters::ActiveRecordModelExtension) if descendant.superclass == ActiveRecord::Base
+      end
+    end
+
+    # @private
+    module ClassMethods
+      # Attaches the ActiveRecord extensions to children of ActiveRecord so we don't pollute ActiveRecord::Base.
+      def inherited_with_with_filters(base)
+        inherited_without_with_filters(base)
+        base.send(:include, WithFilters::ActiveRecordModelExtension) if base.superclass == ActiveRecord::Base
+      end
+    end
+  end
+end

data/lib/with_filters/active_record_model_extension.rb

@@ -0,0 +1,163 @@
+module WithFilters
+  module ActiveRecordModelExtension
+    extend ActiveSupport::Concern
+
+    # @private
+    module AddData
+      # @return [Hash<:column_types, :param_namespace>] Properties relating to the current filters.
+      #
+      # @since 0.1.0
+      attr_accessor :with_filters_data
+    end
+
+    # Attaches conditions to a scope.
+    #
+    # @scope class
+    # @overload with_filters(params = nil, options = {})
+    #   @param [Hash] params A hash of values to filter on.
+    #   @param [Hash] options
+    #   @option options [Symbol] :param_namespace ('primary table name') The namespace
+    #     of the filters inside `params`.
+    #   @option options [Hash, Proc] :fields When a hash is passed this is a mapping
+    #     of custom fields to field options. When a proc is passed it is sent `value`
+    #     and `scope` and is expected to return the scope.
+    #   @option options [String] :fields[:column] The database column to map the field to.
+    #   @option options [Symbol] :fields[:match] Determines the way the filter is matched.
+    #     Accepts `:exact`, `:contains`, `:begins_with` and `:ends_with`.
+    #
+    #   @example Basic
+    #     with_filters(params)
+    #
+    #   @example With a custom matching and field name.
+    #     with_filters(params, {fields: {
+    #       given_name: {column: 'first_name', match: :contains}
+    #     }})
+    #
+    #   @example With a custom field using a proc.
+    #     with_filters(params, {fields: {
+    #       full_name: ->(value, scope) {
+    #         first_word, second_word = value.strip.split(/\s+/)
+    #
+    #         if second_word
+    #           scope.where(['first_name LIKE ? OR last_name LIKE ?', first_word, first_word])
+    #         else
+    #           scope.where(['first_name LIKE ? AND last_name LIKE ?', first_word, second_word])
+    #         end
+    #       }
+    #     }})
+    #
+    # @return [ActiveRecord::Relation]
+    #
+    # @note Switched from `scope` to class method because of a bug in Rails 3.2.1 where
+    #   `joins_values` aren't available in scopes.
+    #
+    # @since 0.1.0
+    included do
+      extend WithFilters::HashExtraction
+      def self.with_filters(params = nil, options = {})
+        relation = self.scoped.extend(AddData).extending do
+          def to_a
+            a = super.extend(AddData)
+            a.with_filters_data = self.with_filters_data
+            a
+          end
+        end
+        param_namespace = options.delete(:param_namespace) || relation.table_name.to_sym
+        relation.with_filters_data = {
+          param_namespace: param_namespace,
+          column_types:    find_column_types(relation, options[:fields] || {})
+        }
+
+        scoped_params = params ? self.extract_hash_value(params, param_namespace) || {} : {}
+        scoped_params.each do |field, value|
+          # skip blank entries
+          value.reject!{|v| v.blank?} if value.is_a?(Array)
+          if (value.is_a?(String) and value.blank?) or
+             (value.is_a?(Array) and value.empty?) or
+             (value.is_a?(Hash) and not (value[:start].present? and value[:stop].present?))
+            next
+          end
+
+          field_options = {}
+          field_options = options[:fields][field] if options[:fields] and options[:fields][field]
+
+          if field_options.is_a?(Proc)
+            relation = field_options.call(value, relation)
+          else
+            db_column_table_name, db_column_name = (field_options.delete(:column) || field).to_s.split('.')
+            if db_column_name.nil?
+              db_column_name = db_column_table_name
+              db_column_table_name = relation.column_names.include?(db_column_name) ? self.table_name : nil
+            end
+
+            quoted_field = relation.connection.quote_column_name(db_column_name)
+            quoted_field = "#{db_column_table_name}.#{quoted_field}" if db_column_table_name
+
+            value = WithFilters::ValuePrep.prepare(relation.with_filters_data[:column_types][field.to_sym], value, field_options)
+
+            # attach filter
+            relation = case value.class.name.to_sym
+              when :Array
+                relation.where([Array.new(value.size, "#{quoted_field} LIKE ?").join(' OR '), *value])
+              when :Hash
+                if ![:datetime, :timestamp].include?(relation.with_filters_data[:column_types][field]) or Date._parse(value[:start])[:sec_fraction]
+                  relation.where(["#{quoted_field} BETWEEN :start AND :stop", value])
+                else
+                  relation.where(["#{quoted_field} >= :start AND #{quoted_field} < :stop", value])
+                end
+              when :String, :FalseClass, :TrueClass, :Date, :Time
+                relation.where(["#{quoted_field} LIKE ?", value])
+              else
+                relation
+            end
+          end
+        end
+
+        relation
+      end
+    end
+
+    # @private
+    module ClassMethods
+      # @param [ActiveRecord::Relation] relation A relation to find the columns of.
+      # @param [Hash] field_options
+      #
+      # @return [Hash<String>] A mapping of fields to their database types.
+      #
+      # @since 0.1.0
+      def find_column_types(relation, field_options)
+        field_options = field_options.reject{|k, v| v.is_a?(Proc)}
+
+        # primary table column types
+        column_types = Hash[*relation.columns.map{|column|
+          [
+            field_options.detect{|field, options|
+              [column.name, "#{relation.table_name}.#{column.name}"].include?(options[:column].to_s)
+            }.try(:first) || column.name.to_sym,
+            column.type
+          ]
+        }.flatten]
+
+        # non-primary table columns
+        (relation.joins_values + relation.includes_values).uniq.map{|join|
+          # convert string joins to table names
+          if join.is_a?(String)
+            join.scan(/\G(?:(?:,|\bjoin\s)\s*(\w+))/i)
+          else
+            join
+          end 
+        }.flatten.map do |table_name|
+          ActiveRecord::Base::connection.columns(table_name.to_s.tableize).each do |column|
+            column_name = field_options.detect{|field, options|
+              [column.name, "#{table_name}.#{column.name}"].include?(options[:column].to_s)
+            }.try(:first) || column.name.to_sym
+
+            column_types.reverse_merge!(column_name => column.type)
+          end
+        end
+
+        column_types
+      end
+    end
+  end
+end

data/lib/with_filters/engine.rb

@@ -0,0 +1,5 @@
+module WithFilters
+  # @private
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/with_filters/hash_extraction.rb

@@ -0,0 +1,31 @@
+module WithFilters
+  # @private
+  module HashExtraction
+    # Extracts the value from a hash and takes nesting into account.
+    #
+    # @param [Hash] hash The hash to search.
+    # @param [String, Symbol] key The key or nested key to search for.
+    #
+    # @return [Object, nil]
+    #
+    # @example Key is a symbol.
+    #   extract_hash_key({foo: 'bar'}, :foo) # => 'bar'
+    #
+    # @example Key is a string with nesting.
+    #   extract_hash_key({foo: {bar: 'baz'}}, 'foo[:bar]') # => 'baz'
+    #
+    # @since 0.1.0
+    def extract_hash_value(hash, key)
+      key  = key.to_s
+      hash = hash.stringify_keys
+      
+      if hash[key]
+        hash[key]
+      else
+        first_key, remaining_content = key.to_s.match(/^([^\[]+)(.*)$/).captures
+
+        eval "hash[first_key]#{remaining_content.gsub(/\[/, '["').gsub(/]/, '"]')} rescue nil"
+      end
+    end
+  end
+end

data/lib/with_filters/models/action.rb

@@ -0,0 +1,14 @@
+module WithFilters
+  class Action
+    attr_accessor :type, :attrs
+
+    def initialize(type, options = {})
+      @type = type
+
+      options[:type]  = @type
+      options[:value] = options.delete(:label) if options[:label]
+
+      @attrs = options
+    end
+  end
+end

data/lib/with_filters/models/filter/base.rb

@@ -0,0 +1,36 @@
+module WithFilters
+  module Filter
+    # @private
+    class Base
+      attr_reader :to_partial_path, :label, :label_attrs, :field_name, :value, :attrs, :collection
+
+      def initialize(name, namespace, value, options = {})
+        @value = value
+
+        @theme       = options.delete(:theme)
+        @label       = options.delete(:label) || name.to_s.titleize
+        @label_attrs = options.delete(:label_attrs) || {}
+        @field_name  = options[:field_name] || "#{namespace}[#{name}]"
+        @collection  = options[:collection] ? Collection.new(@field_name, options.delete(:collection) || [], {selected: value}) : nil
+        @attrs       = options
+
+        @to_partial_path = create_partial_path
+      end
+
+      private
+
+      def create_partial_path
+        partial_path = self.class.name.underscore
+
+        if @theme
+          themed_partial_path = partial_path.split(File::SEPARATOR).insert(1, @theme)
+          if Dir.glob(File.join(Rails.root, 'app', 'views', *themed_partial_path).sub(/([^#{File::SEPARATOR}]+?)$/, '_\1.*')).any?
+            partial_path = themed_partial_path.join(File::SEPARATOR)
+          end
+        end
+
+        partial_path
+      end
+    end
+  end
+end

data/lib/with_filters/models/filter/base_range.rb

@@ -0,0 +1,42 @@
+module WithFilters
+  module Filter
+    # @private
+    class BaseStart < Base
+      def initialize(name, namespace, value, options = {})
+        super
+
+        @field_name << '[start]'
+      end
+    end
+
+    # @private
+    class BaseStop < Base
+      def initialize(name, namespace, value, options = {})
+        super
+
+        @field_name << '[stop]'
+      end
+    end
+
+    # @private
+    class BaseRange < Base
+      attr_reader :start, :stop
+
+      def initialize(name, namespace, value, options = {})
+        start_attrs = options.delete(:start) || {}
+        stop_attrs  = options.delete(:stop)  || {}
+
+        super
+
+        start_attrs.reverse_merge!(@attrs)
+        start_attrs.reverse_merge!(label: self.label, label_attrs: self.label_attrs, collection: @collection)
+        stop_attrs.reverse_merge!(@attrs)
+        stop_attrs.reverse_merge!(label: self.label, label_attrs: self.label_attrs, collection: @collection)
+
+        base_class_name = self.class.to_s.match(/^(.*)Range$/).captures.first
+        @start = "#{base_class_name}Start".constantize.new(name, namespace, value[:start], start_attrs)
+        @stop  = "#{base_class_name}Stop".constantize.new(name, namespace, value[:stop], stop_attrs)
+      end
+    end
+  end
+end

data/lib/with_filters/models/filter/check_box.rb

@@ -0,0 +1,20 @@
+module WithFilters
+  module Filter
+    # @private
+    class CheckBox < Base
+      def initialize(name, namespace, value, options = {})
+        super
+
+        @to_partial_path << 'es' unless self.collection.nil?
+      end
+
+      def selected?
+        if self.collection.nil?
+          value.to_s == 'on'
+        else
+          value.present?
+        end
+      end
+    end
+  end
+end