rooble 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6c2be4d76fd38aaa62e61fb049d0f2f96416f389
-  data.tar.gz: f5d3645b00bee7dc2f3889fa2d81a835dc01e870
+  metadata.gz: 48792701842c670bc199dec1e90fc047aab59f7d
+  data.tar.gz: a88e321916bd3e9c96b6c891ce29058555b52206
 SHA512:
-  metadata.gz: 20661aae7465f984802c1db7e7d3b6f411164b7f418f7330da53046121969d597e3ab5d80e24885e4443968f69d7eb5015e5e6dc7fd2f625f4a33d748bdee406
-  data.tar.gz: 944cd7cbef4b35670202245083c6e21c4de9c343bab3c470b257e74b73b63b628ed73fcac1e8df9a93658735bf263d9b33bc47878ea46b621474af8d20b2703f
+  metadata.gz: 3d7db4a396a694b043bbdeb60d5aaaa1c0aac32a8577c410ca1df963a84e1e1abee644b265dc36ebd08c79351f114e3d5ccaf02f2993859231ad2dbfe5eb06b4
+  data.tar.gz: 15d4aa0ee364a70140363a277e0e0e354c5fdea107661eac6de01218e461a3558c6f8b80a7583b0d5cdab4885988a608a791ac45e132b35a2aa93c1f8ff3dda3

data/README.md

@@ -2,55 +2,181 @@
 
 Yet another unnecessary and selfishly-created pagination and search gem for rails.
 
-## Why?
+ **But... Why?**
 
 Because its a fun way for me to learn rails. There are other, more complex and full featured solutions like [Kaminari](https://github.com/amatsuda/kaminari) but this works fine too.
 
-## How?
+This gem does not use any special classes or modules, instead it will extend ActiveRecord functionality so that you can use the pagination and search methods directly in your ActiveRecord associations so you can even chain them!
 
-Add this to your Gemfile:
+## Installation and configuration
 
-`gem 'rooble'`
+First add this to your Gemfile:
+
+ `gem 'rooble'`
 
 Then do the usual dance:
 
-`bundle install`
+ `bundle install`
+
+Finally create a configuration file by running
+
+ `rails g rooble:config`
+
+That will create a `config/initializers/rooble.rb` file and setup the default value for `max_records_per_page` to a sane number, you don't want to make it a high number though as it will pull that many records per page.
+
+Please note that you can create the initializer manually if you'd like to, this is the basic template:
 
-## Using it
+``` ruby
+Rooble.configure do |config|
+  config.max_records_per_page = 5
+end
+```
 
-First create a configuration file by running `rails g rooble:config` which will create `config/initializers/rooble.rb` and setup the default value for `max_records_per_page` to a sane number, you don't want to make it a high number.
+## Pagination
 
-There are three main methods:
+There are two methods for pagination that you can use directly to your ActiveRecord associations and models:
+
+``` ruby
+Model.pages(max_records_per_page=nil)
+```
+
+**Arguments:**
+
+ - `max_records_per_page` overrides the default value and sets how many records to divide per page
 
 `Model.pages` without any parameters will give you the number of available pages considering the `max_records_per_page` default. You can override it and pass the number of max records that should be counted per page so you get the total count of pages for such number doing something like `Model.pages(10)` if you want the count of pages with 10 records per page.
 
-`Model.paginate(1)` will give you records for the first page. You can override the `max_records_per_page` config option on the second argument so that you paginate a specific page with a different amount of max records, for instance `Model.paginate(1, 10)` would grab the 10 records for the 1st page.
+For instance given that we have a `states` table with the 48 _contiguous_ US states and our `max_records_per_page` is set to `10`:
+
+``` ruby
+ State.pages
+ # => 5
+```
+
+We can override the `max_records_per_page` as well on the first argument which is optional so we get a count of pages for a diferent amount of records per page:
+
+``` ruby
+ State.pages(20)
+ # => 3
+```
+
+``` ruby
+Model.paginate(page=1, max_records_per_page=nil)
+```
+
+ **Arguments:**
+
+ - `page` the page to pull records from
+ - `max_records_per_page` how many records to generate per page, this overrides the initializer option
+
+`Model.paginate` will pull records for the first page. The first argument is the page number and you can also override the `max_records_per_page` config option on the second argument so that you paginate a specific page with a different amount of max records, for instance:
+
+``` ruby
+ State.paginate
+ # => pulls 10 records corresponding to the 1st page
+```
+
+``` ruby
+ State.paginate(2)
+ # => pulls 10 records corresponding to the 2nd page
+```
+
+``` ruby
+ State.paginate(2, 5)
+ # => pulls only 5 records corresponding to the 2nd page
+```
+
+Note that in the 3rd example we override the `max_records_per_page` so we will get more pages since we lowered the number of records.
 
-`Model.search("John", [:name])` will look for records which have **John** within the `name` attribute.
+## Search
+
+The search method will lookup for keyword matches within columns or records that match a given id, this means that you can essentially use it only to search in text fields or in the primary key. So for instance if you try to search against numeric columns it won't work but for that type of specific search you are better off using ActiveRecord directly. The rational behind this is that most application _open_ searches will lookup for id's, names or codes, rarely against numeric values.
+
+``` ruby
+Model.search(fields, search_term, options={})
+```
+
+ **Arguments:**
+
+ - `fields` a string with a field name or string array with field names to make the query against
+ - `search_term` string with the term to search
+ - `options` a hash with a set of options. Please se below for more info.
+
+`Model.search("name", "John")` will look for records which have **John** within the `name` attribute.
 
 There is an extra options hash that you can pass to this method, the options are:
 
- * `case_sensitive: false` whether you want to make the search case sensitive. Default is false.
- * `type: all` type of match, beginning, end or the whole string. Default is all.
+ * `case_sensitive: false` whether you want to make the search case sensitive. Default is false. Note that this relies on the database engine defaults so if the column or table schema is set to be case insensitive it won't mater what you set here.
+ * `match_type: all` type of match, `beginning`, `end`, `all` string or `none`. Default is all.
  * `include` an array/hash of symbols if you want to include other relations on the model. Same as with default rails include.
  * `join` an array/hash of symbols if you want to join other relations on the model. Same as with default rails join.
 
-If you want to search for attributes in joint models you would do something like this:
+**Examples**
+
+Simple search for a specific state:
+
+``` ruby
+ State.search("name", "California")
+ # => Yields 1 result
+```
+
+Searching for substrings:
+
+``` ruby
+ State.search("name", "New")
+ # => Yields 4 results: New Mexico, New Jersey, New Hampshire, New York
+```
+
+Searching for patterns:
+
+``` ruby
+ State.search("name", "Ma", match_type: :beginning)
+ # => Yields 3 results where the value starts with Ma: Maine, Maryland and Massachusetts
+```
+
+``` ruby
+ State.search("name", "Ma", match_type: :end)
+ # => Yields 2 results where the value ends with ma: Alabama, Oklahoma
+```
+
+Searching in several fields
+
+``` ruby
+ State.search(["id", "name"], "California")
+ # => Yields 1 result which is California
+```
+
+The above may not make much sense right? But what happens if you want your users to be able to search from a simple input or search box and allow them to either search states by name or the id? Bingo!:
+
+``` ruby
+ State.search(["id", "name"], 4)
+ # => Yields 1 result which is California
+```
+
+This means that you can allow input for both id's or text and still try to filter by either, you just pass on the second argument whatever input you get from the user.
+
+Now lets do a more complicated search. Say you want to search for attributes in joint models, like searching for the first state where the country name is "USA":
 
-`State.search("USA", "countries.name", join: [:country]).first`
+``` ruby
+ State.search("countries.name", "USA", join: [:country]).first
+```
 
-Or if you want to search for the first city of the USA:
+Do note the string notation for the relation.
 
-`City.search("USA", "countries.name", join: {state: :country}).first`
+You can even do multi-level joins, for instance if you want to search for the first city of the USA:
 
-That would search the first state that has a country named USA. Do note the string notation for the relation.
+``` ruby
+City.search("countries.name", "USA", join: {state: :country}).first
+```
 
 Oh yes, you can chain the methods so you could do something like paginating search results:
 
-`State.search("USA", "countries.name", join: [:country]).paginate(2)`
+``` ruby
+State.search("countries.name", "USA", join: [:country]).paginate(2)
+```
 
 That's it for now.
 
 ## Other features
 
-I will/may add a view helper to generate the pagination navigation.
+I will/may add a rails view helper to generate the pagination navigation.

data/lib/rooble.rb

@@ -20,39 +20,6 @@ module Rooble
     yield(configuration) if block_given?
   end
 
-  def self.build_query(search_term, fields, options={})
-
-    # Set whether we want case sensitive search
-    operator = "ILIKE"
-    if options.has_key? :case_sensitive
-      operator = "LIKE" if options[:case_sensitive]
-    end
-
-    search_beginning = "%"
-    search_end = "%"
-    if options.has_key? :type
-      case options[:type]
-      when "beginning"
-        search_end = ""
-      when "end"
-        search_beginning = ""
-      end
-    end
-
-    # Loop through fields and build query
-    query = ""
-    or_cond = ""
-    fields = [].push(fields) unless fields.is_a? Array
-    fields.each_with_index do |v,i|
-      if i > 0
-        or_cond = "OR"
-      end
-      query += " #{or_cond} #{v} #{operator} '#{search_beginning}#{search_term}#{search_end}' "
-    end
-
-    query
-  end
-
   module ClassMethods
     ##
     # Returns the amount of available pages to do pagination.
@@ -85,30 +52,97 @@ module Rooble
     # Searches through records for the given fields
     #
 
-    def search(search_term, fields, options={})
+    def search(fields, search_term, options={})
       if search_term.nil?
         raise Rooble::Error.new "You need to give a search term"
       end
 
-      if fields.empty?
+      if fields.nil? || fields.empty?
         raise Rooble::Error.new "You need to give at least one field to search"
       end
 
       raise Rooble::Error.new("You can only include or join relations, not both!") if ([:include, :join] - options.keys ).empty?
 
-      # Build the query
-      query = Rooble::build_query(search_term, fields, options)
-
+      # check if we are joining/including other models first
       if options.has_key? :include
-        records = self.includes(options[:include]).where(query)
+        model = self.includes(options[:include])
       elsif options.has_key? :join
-        records = self.joins(options[:join]).where(query)
+        model = self.joins(options[:join])
       else
-        records = self.where(query)
+        model = self
+      end
+
+      search_beginning = "%"
+      search_end = "%"
+      fields = [].push(fields) unless fields.is_a? Array
+      search_values = []
+      query = ''
+      case_sensitive = false
+      or_cond = ''
+
+      if options.has_key? :case_sensitive
+        if options[:case_sensitive]
+          case_sensitive = true
+        end
+      end
+
+      fields.each_with_index do |field,index|
+        # set the OR if we have more than one field
+        if index > 0
+          or_cond = "OR"
+        end
+
+        # lets find out if we are looking for the ID, we can't
+        # use like for integers so we use equality instead
+        if field.downcase == "id"
+          # check that the serch term is actually a number
+          operator = "="
+          search_values.push(search_term.to_i)
+        else
+
+          # set the type of search wether just beginning of string
+          # the end or as a whole
+          if options.has_key? :match_type
+            case options[:match_type].to_s
+            when "beginning"
+              search_beginning = nil
+            when "end"
+              search_end = nil
+            when "all"
+              search_beginning = "%"
+              search_end = "%"
+            when "none"
+              search_beginning = nil
+              search_end = nil
+            end
+          end
+
+          # set whether we want case sensitive search
+          case ActiveRecord::Base.connection.adapter_name
+          when "PostgreSQL"
+            case_sensitive ? operator = "LIKE" : operator = "ILIKE"
+            search_value = search_term
+          when "MySQL", "Mysql2", "SQLite"
+            operator = "LIKE"
+            if case_sensitive
+              search_value = search_term
+            else
+              field = "LOWER(#{field})"
+              search_value = search_term.downcase
+            end
+          end
+
+          # downcase the search term if we are doing case insensitive search so
+          # the value of downcasing the column matches
+          search_values.push("#{search_beginning}#{search_value}#{search_end}")
+        end
+
+        query += " #{or_cond} #{field} #{operator} ? "
       end
 
-      records
+      records = model.where(query, *search_values)
     end
+
   end
 
   ActiveRecord::Base.send(:include, Rooble)

data/lib/rooble/version.rb

@@ -1,3 +1,3 @@
 module Rooble
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rooble
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Gustavo Rubio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-22 00:00:00.000000000 Z
+date: 2016-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport