rails-simple-search 1.1.9 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c180305a173dc76d61b6bf88048d7b4071b374b0ca3d18e68179f57516e00bc8
-  data.tar.gz: 36296809170c80c856bb2b300663faae462a11c4fa211803d9386560d605ffba
+  metadata.gz: 290634cd836385acaa327ac5b5971e75a716291d51629d8c54dc3c8db728e466
+  data.tar.gz: 9a8c7d6985147d3669c9cf1d98cf41fed6854e1039bdddf7fc271b6b4c4d5f01
 SHA512:
-  metadata.gz: 8a8d8986df1dc830c910f3812968102ab527d9b70fc6cc7d4d8e3550eeeb20b3334c6f1d4d51b06a4d86295dac99a16eb8e94d880f653dada4337244217b098c
-  data.tar.gz: c03cb28f7e8349be45aa3ff441d811fc4ab0b20b57951c41b7440daacdc9d1a48cbe018fb4d5166c61a9ee40b4d6b1efff46ddaeb60dcacee9eef28d33d8014b
+  metadata.gz: 890be5b99ab922d000adad63885a50a4bd678a1294b4915c32db93d808ac89774934626a0b73b3dd117728beb7d6b62a2df15c3b9353fb0113a80a05f11a57fa
+  data.tar.gz: 2e72fd3aef31f0b0b3fdf7b34e80a5f1035cac36b869a62d543d178c5bee132a78caf00605bd1bc93e60e675b52ced76a9fffffb0d22be23acad1e65adf0269b

data/README.md

@@ -0,0 +1,129 @@
+## What is rails-simple-search?
+rails-simple-search is a Ruby gem. It can help Ruby on Rails developers **quickly**
+implement searching/filtering function against database. If you're not looking
+for a full-text searching solution, this plugin will most probably **satisfy all**
+your searching requirement.
+
+## Why?
+From time to time, I need to build pages to show a list of narrowed down records
+from a database table by giving some searching criteria on some columns of the
+table and/or of some referencing tables. Before I implemented this plugin, I usually
+do the searching in the following way:
+
+1. Use <%= form_tag %> to build a form in the view
+2. Get the searching criteria from the params hash individually in the controller
+   and put them into instance variables to be used in view
+3. Build the SQL WHERE clause and sometimes the JOIN clause according to the
+   values from the form
+4. Run the find(:all, :conditions => [xxxxxxxx], :joins => "xxxxxxxx") with the
+   WHERE and JOIN clauses
+
+After having used this pattern a few times, I realized I could DRY it to make
+future coding of this kind of searching **much simpler**. That's where the
+rails-simple-search plugin comes in. 
+
+## Installation
+1. Put the following line into the Gemfile of your project
+```
+   gem 'rails-simple-search'
+```
+
+2. Install the gems in Gemfile
+```
+   $ bundle install
+```
+
+## Usage 
+
+Let's suppose we have models of User, Address, Post and Comment. User model has_one
+address, has_many posts, and has_many comments; Post model has_many comments; Comment
+model belongs_to an author(of model User). We'd like to search for users according
+to any combination of the following criteria:
+
+* part of the user's email addrsss
+* part of the first name or last name
+* range of the user's birth date
+* part of the city name of the user's address
+* state of the user's address
+* part of the name of any authors who commented the user's any posts
+
+The following is how we implement this searching function with rails-simple-search:
+
+1. Include gem into Gemfile
+```  
+    gem 'rails-simple-search'
+```
+
+2. Code in model (app/model/search.rb):
+```
+    class Search < RailsSimpleSearch::Base
+    end
+```
+
+3. Code in controller: 
+```
+    @search = Search.new(User, params[:search])
+    @users = @search.run.order('email')
+```
+
+4. Code in views:
+```
+    <% form_for @search, url => "/xxxxxx", data: {turbo: false} do |f| %>
+
+      <%=f.label :email %>
+      <%=f.text_field :email %>
+
+      <%=f.label "first name or last name" %>
+      <%=f.text_field "first_name_or_last_name" %>
+
+      <%=f.label :from_birth_date %>
+      <%=f.text_field :birth_date_greater_than_equal_to %>
+
+      <%=f.label :to_birth_date %>
+      <%=f.text_field :birth_date_less_than_equal_to %>
+
+      <%=f.label :state%>
+      <%=f.select "address.state_id", [['AL', 1], ...] %>  <!-- address is an association of model User -->
+
+      <%=f.label :city %>
+      <%=f.text_field "address.city" %>                    <!-- address is an association of model User -->
+
+      <%=f.label "name of any one who commented to my posts" %>
+      <%=f.text_field "posts.comments.user.first_name_or_posts.comments.user.last_name" %>
+                                                           <!-- the associations could go even deeper, isn't it POWERFUL? -->
+
+      <%=f.submit %>
+    <% end %>
+
+    <% @users.each do |user| %>
+     <%= # show the attributes of user %>
+    <% end %>
+```
+
+5. Add route for the post to url "/xxxxxx" (config/route.rb)
+```
+    post "/xxxxxx" => "yyyyyyy#zzzzzz"
+```
+
+## Demo projects
+There are 2 demo projects for this gem, one for [Rails 5](https://github.com/yzhanginwa/demo_app_for_rails_simple_search)
+and one for [Rails 7](https://github.com/yzhanginwa/rails_simple_search_demo). You are encouraged to clone them to your local and
+get a feel of the power of rails-simple-search.
+
+## Version history 
+For rails 2.x.x applications, you might want to use the version 0.9.0. 
+
+From version 0.9.1 to 0.9.7, Rails 3 is supported.
+
+From version 0.9.8 on, this gem started to support Rails 4. Version 0.9.8 is tested under Rails 4.1.1, and version 0.9.9 fixed an issue under
+Rails 4.2.
+
+From version 1.1.0 on, we started to support the "or" relation, e.g., we can use field like "first_name_or_last_name".
+
+From version 1.1.3 on, we started to support Rails 5.
+
+For Rails 7, please use version 1.2.0.
+
+## License
+
+Copyright &copy; 2012 [Ethan Zhang], released under the MIT license

data/lib/rails-simple-search.rb

@@ -1,9 +1,10 @@
 require_relative 'sql_handler'
 
 module RailsSimpleSearch
-  DEFAULT_CONFIG = { :exact_match => [], 
-                     :or_separator => '_or_'
-                   }
+  DEFAULT_CONFIG = {
+    exact_match: [],
+    or_separator: '_or_'
+  }
 
   module FixModelName
     def model_name
@@ -16,16 +17,16 @@ module RailsSimpleSearch
 
     def self.inherited(subclass)
       class << subclass
-         # in rails 3, the call to "form_for" invokes the model_name 
-         def model_name
-           ActiveModel::Name.new(self)
-         end
+        # in rails 3, the call to "form_for" invokes the model_name
+        def model_name
+          ActiveModel::Name.new(self)
+        end
       end
-     
+
       # to fix an issues in rails 4.2
       subclass.send(:include, RailsSimpleSearch::FixModelName)
     end
- 
+
     def self.pre_process(model_name, &procedure)
       model_name.each { |internal_model_name| pre_process(internal_model_name, &procedure) } if model_name.is_a?(Array)
       @pre_processors ||= {}
@@ -37,7 +38,7 @@ module RailsSimpleSearch
       @pre_processors[model_name]
     end
 
-    def initialize(model_class, criteria={}, config={})
+    def initialize(model_class, criteria = {}, config = {})
       @criteria = sanitize_criteria(criteria)
       @config = DEFAULT_CONFIG.merge(config)
       @config[:exact_match] = [@config[:exact_match]] unless @config[:exact_match].respond_to?(:map!)
@@ -49,21 +50,19 @@ module RailsSimpleSearch
     end
 
     def load_database_handler(model_class)
-      if model_class.ancestors.include?(ActiveRecord::Base)
-        RailsSimpleSearch::Base.send(:include, RailsSimpleSearch::SqlHandler)
-      else
-        raise("RailsSimpleSearch only supports ActiveRecord for now")
-      end
+      raise("RailsSimpleSearch only supports ActiveRecord for now") unless model_class.ancestors.include?(ActiveRecord::Base)
+
+      RailsSimpleSearch::Base.send(:include, RailsSimpleSearch::SqlHandler)
     end
-  
+
     def count
       @count || 0
     end
 
-    def add_conditions(h={})
-      @criteria.merge!(h.stringify_keys)
+    def add_conditions(hash = {})
+      @criteria.merge!(hash.stringify_keys)
     end
-  
+
     def remove_criteria(key)
       key.each { |internal_key| remove_criteria(internal_key) } if key.is_a?(Array)
       @criteria.delete(key.to_s)
@@ -73,43 +72,33 @@ module RailsSimpleSearch
       @criteria[key.to_s] = value
     end
 
-    private 
+    private
 
     def method_missing(method, *args)
       method_str = method.to_s
       if method_str =~ /^([^=]+)=$/
-        @criteria[$1.to_s] = args[0]
-      else 
+        @criteria[::Regexp.last_match(1).to_s] = args[0]
+      else
         @criteria[method_str]
       end
     end
 
     def parse_field_name(name)
-      result = {}
       if name =~ /^(.*)?((_(greater|less)_than)(_equal_to)?)$/
-        result[:field_name] = $1
-        if $4 == 'greater'
-          result[:operator] = ">"
-        else
-          result[:operator] = "<"
-        end
-        if $5
-          result[:operator] << "="
-        end
+        field_name = ::Regexp.last_match(1)
+        operator = (::Regexp.last_match(4) == 'greater' ? '>' : '<')
+        operator << '=' if ::Regexp.last_match(5)
       else
-        result[:field_name] = name
+        field_name = name
       end
-      result
+
+      [field_name, operator]
     end
-  
+
     def sanitize_criteria(criteria)
-      criteria = criteria || {}
+      criteria ||= {}
       c = {}
-      criteria.each do |key, value|
-        unless value.blank?
-          c[key] = value
-        end
-      end
+      criteria.each { |key, value| c[key] = value unless value.blank? }
       c.stringify_keys
     end
   end

data/lib/sql_handler.rb

@@ -1,8 +1,7 @@
 module RailsSimpleSearch
-  module SqlHandler  
-
+  module SqlHandler
     def init
-      @table_name = @model_class.table_name
+      @model_table_name = @model_class.table_name
       @joins = {}
     end
 
@@ -26,40 +25,38 @@ module RailsSimpleSearch
       elsif column.respond_to?(:type)
         column.type == :string || column.type == :text
       else
-        raise "encountered new version of Rails"
+        raise 'encountered new version of Rails'
       end
     end
-  
+
     def make_joins
       @joins_str = ''
       joins = @joins.values
-      joins.sort! {|a,b| a[0] <=> b[0]}
+      joins.sort! { |a, b| a[0] <=> b[0] }
       joins.each do |j|
         table = j[1]
         constrain = j[2]
-        @joins_str << " inner join  #{table} on #{constrain}" 
+        @joins_str << format(" inner join #{table} AS A%02d on #{constrain}", j[0])
       end
     end
-  
+
     def run_criteria
       @condition_group = ConditionGroup.new
       @condition_group.set_relation(:and)
 
       @criteria.each do |key, value|
-        @condition_group.add(parse_attribute(key, value))
+        @condition_group.add(parse_search_parameters(key, value))
       end
 
       make_joins
     end
 
-    def insert_condition(base_class, attribute, field, value)
-      name_hash = parse_field_name(field)
-      field = name_hash[:field_name]
-      operator = name_hash[:operator]
-
+    def build_single_condition(base_class, association_alias, field, value)
+      field, operator = parse_field_name(field)
       table = base_class.table_name
       key = "#{table}.#{field}"
-  
+      final_key = "#{association_alias}.#{field}"
+
       column = base_class.columns_hash[field.to_s]
       return nil unless column
 
@@ -69,68 +66,78 @@ module RailsSimpleSearch
         verb = 'in'
       elsif operator
         verb = operator
-      elsif text_column?(column) && ! @config[:exact_match].include?((@table_name == table)? field : key)
+      elsif text_column?(column) && ! @config[:exact_match].include?((@model_table_name == table) ? field : key)
         verb = 'like'
         value = "%#{value}%"
       else
         verb = '='
       end
 
-      ConditionGroup.new(ConditionItem.new(key, verb, value))
+      ConditionGroup.new(ConditionItem.new(final_key, verb, value))
+    end
+
+    def table_name_to_alias(table_name)
+      format('A%02d', @joins[table_name][0])
     end
-  
+
     def insert_join(base_class, asso_ref)
       base_table = base_class.table_name
       asso_table = asso_ref.klass.table_name
-      
+
       @join_count ||= 0
-      unless base_table == asso_table
-        if @joins[asso_table].nil?
-          @join_count += 1
-          if asso_ref.belongs_to?
-            @joins[asso_table] =[@join_count, asso_table, "#{base_table}.#{asso_ref.foreign_key} = #{asso_table}.#{asso_ref.klass.primary_key}"]
-          else
-            join_cond = "#{base_table}.#{base_class.primary_key} = #{asso_table}.#{asso_ref.foreign_key}"
-            join_cond = "#{asso_table}.#{asso_ref.type} = '#{base_class.name}' and #{join_cond}" if asso_ref.type
-            @joins[asso_table] = [@join_count, asso_table, join_cond]
-          end
-        end
+      return if base_table == asso_table
+      return unless @joins[asso_table].nil?
+
+      @join_count += 1
+      base_table_alias = @join_count < 2 ? base_table : table_name_to_alias(base_table)
+      asso_table_alias = format('A%02d', @join_count)
+
+      if asso_ref.belongs_to?
+        @joins[asso_table] =[@join_count, asso_table, "#{base_table_alias}.#{asso_ref.foreign_key} = #{asso_table_alias}.#{asso_ref.klass.primary_key}"]
+      else
+        join_cond = "#{base_table_alias}.#{base_class.primary_key} = #{asso_table_alias}.#{asso_ref.foreign_key}"
+        join_cond = "#{asso_table_alias}.#{asso_ref.type} = '#{base_class.name}' and #{join_cond}" if asso_ref.type
+        @joins[asso_table] = [@join_count, asso_table, join_cond]
       end
     end
-  
-    def parse_attribute(attribute, value)
+
+    # This method parse a search parameter and its value
+    # then produce a ConditionGroup
+    def parse_search_parameters(attribute, value)
+      # handle _or_ parameters
       attributes = attribute.split(@config[:or_separator])
-      if(attributes.size > 1)
+      if attributes.size > 1
         cg = ConditionGroup.new
         cg.set_relation(:or)
         attributes.each do |a|
-          cg.add(parse_attribute(a, value))
+          cg.add(parse_search_parameters(a, value))
         end
         return cg
       end
 
+      # handle direct fields
       unless attribute =~ /\./
-        field = attribute
-        condition = insert_condition(@model_class, attribute, field, value)
+        condition = build_single_condition(@model_class, @model_class.table_name, attribute, value)
         return condition
-      end 
+      end
 
+      # handle association fields
       association_fields = attribute.split(/\./)
       field = association_fields.pop
 
       base_class = @model_class
-      while (association_fields.size > 0) 
+      until association_fields.empty?
         association_fields[0] = base_class.reflect_on_association(association_fields[0].to_sym)
         insert_join(base_class, association_fields[0])
         base_class = association_fields.shift.klass
       end
 
-      condition = insert_condition(base_class, attribute, field, value)
-      return condition
+      association_alias = table_name_to_alias(base_class.table_name)
+      build_single_condition(base_class, association_alias, field, value)
     end
-  
   end
 
+  # This class holds a single condition
   class ConditionItem
     attr_reader :field, :verb, :value
 
@@ -141,8 +148,11 @@ module RailsSimpleSearch
     end
   end
 
+  # This class holds a ConditionGroup
+  # One ConditionGroup can hold one or more
+  # conditions
   class ConditionGroup
-    def initialize(item=nil)
+    def initialize(item = nil)
       if item
         @condition_item = item
       else
@@ -150,17 +160,15 @@ module RailsSimpleSearch
       end
     end
 
-    def add(cg)
-      if leaf?
-        raise "It's not allowed to add child into leaf node"
-      end
-      @children << cg if cg
+    def add(condition_group)
+      raise "It's not allowed to add child into leaf node" if leaf?
+
+      @children << condition_group if condition_group
     end
 
     def set_relation(and_or)
-      if leaf?
-        raise "It's not needed to set relation for leaf node"
-      end
+      raise "It's not needed to set relation for leaf node" if leaf?
+
       @relation = and_or
     end
 
@@ -169,7 +177,7 @@ module RailsSimpleSearch
     end
 
     def empty?
-      (@children && @children.empty?) ? true : false
+      @children && @children.empty? ? true : false
     end
 
     def to_ar_condition
@@ -177,17 +185,14 @@ module RailsSimpleSearch
       if leaf?
         i = @condition_item
         condition << "#{i.field} #{i.verb}"
-        if i.verb == 'in'
-          condition[0] << " (?)"
-        else
-          condition[0] << " ?"
-        end
+        condition[0] << (i.verb == 'in' ? ' (?)' : ' ?')
         condition << i.value
       else
-        tmp = @children.map(&:to_ar_condition)
-        condition << "(" + tmp.map(&:first).join(" #{@relation} ") + ")"
-        tmp.each do |t|
-          (1..(t.length-1)).each do |index|
+        tmp_conditions = @children.map(&:to_ar_condition)
+        tmp_condition_str = tmp_conditions.map(&:first).join(" #{@relation} ")
+        condition << "(#{tmp_condition_str})"
+        tmp_conditions.each do |t|
+          (1..(t.length - 1)).each do |index|
             condition << t[index]
           end
         end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-simple-search
 version: !ruby/object:Gem::Version
-  version: 1.1.9
+  version: 1.2.0
 platform: ruby
 authors:
 - Yi Zhang
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-12-24 00:00:00.000000000 Z
+date: 2023-12-27 00:00:00.000000000 Z
 dependencies: []
 description: rails-simple-search is a light and easy to use gem. It could help developers
   quickly build a search page.
@@ -17,7 +17,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- README.rdoc
+- README.md
 - lib/rails-simple-search.rb
 - lib/sql_handler.rb
 homepage: http://github.com/yzhanginwa/rails-simple-search

data/README.rdoc

@@ -1,95 +0,0 @@
-=rails-simple-search
-
-rails-simple-search is a Ruby gem. It helps you quickly implement searching/filtering function for your web site. This plugin has paginating feature built in. If you're not looking for a full-text searching solution, this plugin will most probably satisfy all your searching requirement.
-
-From time to time, I need to build pages to show a list of narrowed down records from a database table by giving some searching criteria on some columns of the table and/or of some referencing tables. Before I implemented this plugin, I usually do the searching in the following way:
-
-1. Use <%= form_tag %> to build a form in the view
-2. Get the searching criteria from the params hash individually in the controller and put them into instance variable to be used in view
-3. Build the SQL WHERE clause and sometimes the JOIN clause according to the values from the form
-4. Run the find(:all, :conditions => [xxxxxx], :joins => "yyyyyy") with the WHERE and JOIN clauses
-
-After having used this pattern a few times, I realized I could DRY it to make future coding of this kind of searching much simpler. That's where the rails-simple-search plugin comes in. 
-
-Now implementing the searching/filter page is a lot easier for me. You're see how easy it is by taking a look at the following example. I may give more examples in the future when I have some spare time. 
-
-
-== Example
-
-Let's suppose we have models of User, Address, Post and Comment. User model has_one address and has_many posts; Post model has_many comments. We'd like to search for users according to any combination of the following criteria:
-
-* part of the user's email addrsss
-* range of the user's birth date
-* state of the user's address
-* part of the name of any authors who commented the user's any posts
-
-The following is how we implement this searching function with rails-simple-search:
-
-1. Include gem into Gemfile
-  
-    gem 'rails-simple-search'
-
-2. Code in model (app/model/search.rb):
-
-    class Search < RailsSimpleSearch::Base
-    end
-
-3. Code in controller: 
-
-    @search = Search.new(User, params[:search])
-    @users = @search.run.paginate(page: params[:page], per_page: 20).order('email')
-
-4. Code in views:
-
-    <% form_for @search, url => "/xxxxxx", data: {turbo: false} do |f| %>
-
-      <%=f.label :email %>
-      <%=f.text_field :email %>
-
-      <%=f.label "first name or last name" %>
-      <%=f.text_field "first_name_or_last_name" %>
-
-      <%=f.label :from_birth_date %>
-      <%=f.text_field :birth_date_greater_than_equal_to %>
-
-      <%=f.label :to_age %>
-      <%=f.text_field :birth_date_less_than_equal_to %>
-
-      <%=f.label :state%>
-      <%=f.select "address.state_id", [['AL', 1], ...] %>  <!-- address is an association of model User -->
-
-      <%=f.label :post%>
-      <%=f.text_field "posts.comments.author" %>           <!-- the associations could go even deeper, isn't it POWERFUL? -->
-
-      <%=f.submit %>
-    <% end %>
-
-    <% @users.each do |user| %>
-     <%= # show the attributes of user %>
-    <% end %>
-
-5. Add route for the post to url "/xxxxxx" (config/route.rb)
-    post "/xxxxxx" => "yyyyyyy#zzzzzz"
-
-== Note
-
-For rails 2.x.x applications, you might want to use the version 0.9.0. 
-
-From version 0.9.1 to 0.9.7, Rails 3 is supported.
-
-From version 0.9.8 on, this gem started to support Rails 4. Version 0.9.8 is tested under Rails 4.1.1, and version 0.9.9 fixed an issue under
-Rails 4.2.
-
-From version 1.1.0 on, we started to support the "or" relation, e.g., we can use field like "first_name_or_last_name".
-
-From version 1.1.3 on, we started to support Rails 5.
-
-For Rails 7, please use version 1.1.7.
-
-There is a real demo application which you can download and run immediately: https://github.com/yzhanginwa/demo_app_for_rails_simple_search
-
-For Rails 7 demo, please see here: https://github.com/yzhanginwa/rails_simple_search_demo
-
-== License
-
-Copyright (c) 2012 [Yi Zhang], released under the MIT license