findable_by 0.1.0 → 0.1.1

data/README.markdown

@@ -1,7 +1,9 @@
 findable_by
 =
 
-findable_by is a simple Rails 3 plugin to improve a way how you search for records. You can pass the search form parameters directly to the find_with method in your relation, and the plugin will take care to build a correct query in a safer way.
+findable_by is a simple Rails 3 plugin to improve a way how you search for records. You can pass the search form parameters directly to the find_with method in your relation, by example. The plugin will take care to build a correct query in a safer way. This plugin doesn't modify the default behaviour of query engine of Rails3, but gives a new way to do your queries. You can use the both ways at same time without problems.
+
+This plugin is designed to improve a way how to find records when you have a search forms, and in a standardized, cleaner and safer way to link the parameters from search form to model that declares how to search them.
 
 See below how it's works.
 
@@ -15,32 +17,54 @@ In your Gemfile:
 Usage
 -
 
+In your model you need to declare what the attributes you want to make "findable". For each, you can declare the way how it is "findable". You can declare more to one attribute in same line that use same way.
+
     class Person < ActiveRecord::Base
       scope :gender, proc { |value| where(:gender => value) }
+      scope :by_department_name, proc { |value| joins(:department).where(:department => { :name => value }) }
   
       findable_by :first_name,          :using => :like
       findable_by :last_name,           :using => UpcaseFinder
       findable_by :primary_contact_id,  :using => :equals
       findable_by :number1_fan,         :using => proc { |attribute, value| where("1=1") }
       findable_by :gender,              :using => proc { |attribute, value| gender(value) }
-      findable_by :age,                 :using => :between, :with => [ :min, :max ]
-      findable_by :birth_date,          :using => :between, :with => [ :min, :max ]
+      findable_by :age, :birth_date,    :using => :between, :with => [ :min, :max ]
+      
+      belongs_to :department
+      
+      # When department_name is setted "findable_by" will call :by_department_name named scope
+      # passing the value by parameter.
+      findable_by :department_name,     :through => :by_department_name
     end
     
 And now you can search:
 
     relation = Person.scoped
-    relation = relation.find_with(params[:search])
-    relation.all
+    relation = relation.find_with(params[:search]) # :search => { :first_name => "Jose", :last_name => "Lito", 
+                                                   #              :age => { :min => 25, :max => 45 } }
+
+    relation.where(:gender => 'M').limit(1).all
   
-TODO
+You can create your own finders. Just create a class in your lib/ that extends Finder and respond_to "build_condition". Example, if you need to create a finder that upcase the value before creation the condition, you finder looks like this:
+
+    class UpcaseFinder < Finder
+      def build_condition(relation, attribute, value, params)
+        relation.where(attribute => value.upcase!)
+      end
+    end
+
+You can do much more! By example, create finders that sanitize or normalize inputs, scaling your productivity. In some cases too, you need to call a DB-specific function in where clause, you can write and Finder to do it and maintain your model more cleaner.
+
+Help wanted for...
 -
 
-README and some documentation.
+To make a better documentation and improve testing. Pull requests are welcome.
 
 Bugs and Feedback
 -
 
+If you see any bugs or if you have a comment to do, please, write a issue here:
+
 http://github.com/thiagomoretto/findable_by/issues
 
 MIT License. Copyright 2010.

data/lib/findable_by.rb

@@ -49,16 +49,28 @@ module FindableBy
         def findable_by(*attr_names)
           options = attr_names.extract_options!
           options.merge!(:attributes => attr_names.flatten)
-          options[:using] = :equals if not options.key?(:using)
           options[:attributes].each do |attribute|
-            using_what = options[:using]
+            using, through = options[:using], options[:through]
+            if not using.blank? and not through.blank?
+              raise ArgumentError, "You cannot use :using and :through at same time" 
+            end
             
-            if using_what.is_a?(Class)
-              self._finders[attribute] = using_what.new(options)
-            elsif using_what.is_a?(Proc)
-              self._finders[attribute] = ProcFinder.new(options, using_what)
+            options[:using] = :equals if through.blank? and using.blank?
+
+            if not through.blank?
+              self._finders[attribute] = ScopeFinder.new(options, through)
             else
-              self._finders[attribute] = Kernel.const_get("#{options[:using]}_finder".classify).new(options)
+              self._finders[attribute] =
+              case using
+              when Class
+                using.send(:new, options)
+              when Proc
+                ProcFinder.new(options, using)
+              when Symbol
+                Kernel.const_get("#{options[:using]}_finder".classify).new(options)
+              else
+                raise ArgumentError, ":using must be: a Class, a Proc or a Symbol"
+              end
             end
           end
         end

data/lib/findable_by/finders/scope_finder.rb

@@ -0,0 +1,11 @@
+class ScopeFinder < Finder
+  attr_accessor :named_scope
+  def initialize(options, named_scope)
+    super(options)
+    self.named_scope = named_scope
+  end
+  
+  def build_condition(relation, attribute, value, params)
+    relation.send(named_scope, value) if relation.respond_to?(named_scope)
+  end
+end

data/lib/findable_by/version.rb

@@ -1,3 +1,3 @@
 module FindableBy
-  VERSION = "0.1.0".freeze
+  VERSION = "0.1.1".freeze
 end

data/test/findable_by_test.rb

@@ -6,13 +6,13 @@ class FindableByTest < ActiveRecord::TestCase
 
   test "should generate a SQL to find a person by first name using like" do
     with_scoped(Person) do |person|
-      assert_not_nil person.find_with(:first_name => "OMG!").to_sql
+      assert_not_nil person.find_with(:first_name => "OMG!").to_sql =~ /LIKE/
     end
   end
   
   test "should generate a SQL to find a person using a proc" do
     with_scoped(Person) do |person|
-      assert_not_nil person.find_with(:number1_fan => "Don't care").to_sql
+      assert_not_nil person.find_with(:number1_fan => "Don't care").to_sql =~ /1=1/
     end
   end
 
@@ -25,13 +25,13 @@ class FindableByTest < ActiveRecord::TestCase
   
   test "should generate a SQL to find a person calling 'find_with' chained" do
     with_scoped(Person) do |person|
-      assert_not_nil person.find_with(:first_name => "OMG!").find_with(:gender => 'F').to_sql
+      assert_not_nil person.find_with(:first_name => "OMG!").find_with(:gender => 'F').to_sql =~ /first_name/
     end
   end
   
   test "should generate a SQL to find a person by primary_contact_id using equals" do
     with_scoped(Person) do |person|
-      assert_not_nil person.find_with(:primary_contact_id => 1).to_sql
+      assert_not_nil person.find_with(:primary_contact_id => 1).to_sql =~ /primary_contact_id/
     end
   end
   
@@ -54,9 +54,15 @@ class FindableByTest < ActiveRecord::TestCase
       assert person.find_with(params).to_sql =~ /BETWEEN/
     end
   end
+  
+  test "should generate a SQL to find people by department name using like" do
+    with_scoped(Person) do |person|
+      assert_not_nil person.find_with(:department_name => "hr").to_sql =~ /"department"."name" = 'hr'/
+    end
+  end
+  
 private
   def with_scoped(model, &block)
     block.call(model.send(:scoped))
   end
-  
 end

data/test/schema/schema.rb

@@ -5,9 +5,14 @@ ActiveRecord::Schema.define do
     t.string     :last_name
     t.references :primary_contact
     t.string     :gender, :limit => 1
-    t.references :number1_fan
+    t.integer    :number1_fan
+    t.references :department
     t.integer    :age, :limit => 3
     t.integer    :lock_version, :null => false, :default => 0
   end  
   
+  create_table :departments, :force => true do |t|
+    t.string    :name, :null => false
+  end
+  
 end

data/test/support/models.rb

@@ -6,15 +6,19 @@ end
 
 class Person < ActiveRecord::Base
   scope :gender, proc { |value| where(:gender => 'F') }
+  scope :by_department_name, proc { |value| joins(:department).where(:department => { :name => value }) }
   
   findable_by :first_name,          :using => :like
   findable_by :last_name,           :using => UpcaseFinder
   findable_by :primary_contact_id,  :using => :equals
   findable_by :number1_fan,         :using => proc { |attribute, value| where("1=1") }
-  findable_by :gender,              :using => proc { |attribute, value| gender(value) }
+  findable_by :gender,              :through => :gender
   findable_by :age,                 :using => :between, :with => [ :min, :max ]
   findable_by :birth_date,          :using => :between, :with => [ :min, :max ]
   
-  # TODO: findable_by :gender,              :through => :gender     # uses scope :gender
-  # TODO: findable_by :gender                                       # uses (:using => :equals)
-end
+  belongs_to :department
+  
+  findable_by :department_name,     :through => :by_department_name
+end
+
+class Department < ActiveRecord::Base; end 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: findable_by
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Thiago Moretto
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-12 00:00:00 -03:00
+date: 2010-11-17 00:00:00 -03:00
 default_executable: 
 dependencies: []
 
@@ -34,6 +34,7 @@ files:
 - lib/findable_by/finders/equals_finder.rb
 - lib/findable_by/finders/like_finder.rb
 - lib/findable_by/finders/proc_finder.rb
+- lib/findable_by/finders/scope_finder.rb
 - lib/findable_by/version.rb
 - README.markdown
 - test/connection/native_sqlite3/in_memory_connection.rb