has_scope 0.2 → 0.3

data/README.rdoc

@@ -40,8 +40,56 @@ Then for each request:
 You can retrieve all the scopes applied in one action with <tt>current_scopes</tt> method.
 In the last case, it would return: { :featured => true, :by_degree => "phd" }.
 
-<tt>has_scope</tt> support several options (:only, :except, :as, :if, :unless, :default
-and :type), please check the documentation for a detailed description.
+== Installation
+
+HasScope is available as gem on Gemcutter, so just run the following:
+
+    sudo gem install has_scope
+
+If you want it as plugin, just do:
+
+    script/plugin install git://github.com/plataformatec/has_scope.git
+
+== Options
+
+HasScope support several options:
+
+  * <tt>:type</tt> - Checks the type of the parameter sent. If set to :boolean
+                     it just calls the named scope, without any argument. By default,
+                     it does not allow hashes or arrays to be given, except if type
+                     :hash or :array are set.
+
+  * <tt>:only</tt> - In which actions the scope is applied.
+
+  * <tt>:except</tt> - In which actions the scope is not applied.
+
+  * <tt>:as</tt> - The key in the params hash expected to find the scope.
+                   Defaults to the scope name.
+
+  * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+                   if the scope should apply
+
+  * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
+                       if the scope should NOT apply.
+
+  * <tt>:default</tt> - Default value for the scope. Whenever supplied the scope
+                        is always called.
+
+  * <tt>:allow_blank</tt> - Blank values are not sent to scopes by default. Set to true to overwrite.
+
+== Block usage
+
+has_scope also accepts a block. The controller, current scope and value are yielded
+to the block so the user can apply the scope on its own. This is useful in case we
+need to manipulate the given value:
+
+  has_scope :category do |controller, scope, value|
+    value != "all" ? scope.by_category(value) : scope
+  end
+
+  has_scope :not_voted_by_me, :type => :boolean do |controller, scope|
+    scope.not_voted_by(controller.current_user.id) 
+  end
 
 == Bugs and Feedback
 

data/Rakefile

@@ -27,7 +27,7 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |s|
     s.name = "has_scope"
-    s.version = "0.2"
+    s.version = "0.3"
     s.summary = "Maps controller filters to your resource scopes"
     s.email = "contact@plataformatec.com.br"
     s.homepage = "http://github.com/plataformatec/has_scope"

data/init.rb

@@ -0,0 +1 @@
+require 'has_scope'

data/lib/has_scope.rb

@@ -4,6 +4,7 @@ module HasScope
   ALLOWED_TYPES = {
     :array   => [ Array ],
     :hash    => [ Hash ],
+    :boolean => [ Object ],
     :default => [ String, Numeric ]
   }
 
@@ -43,7 +44,23 @@ module HasScope
     # * <tt>:default</tt> - Default value for the scope. Whenever supplied the scope
     #                       is always called.
     #
-    def has_scope(*scopes)
+    # * <tt>:allow_blank</tt> - Blank values are not sent to scopes by default. Set to true to overwrite.
+    #
+    # == Block usage
+    #
+    # has_scope also accepts a block. The controller, current scope and value are yielded
+    # to the block so the user can apply the scope on its own. This is useful in case we
+    # need to manipulate the given value:
+    #
+    #   has_scope :category do |controller, scope, value|
+    #     value != "all" ? scope.by_category(value) : scope
+    #   end
+    #
+    #   has_scope :not_voted_by_me, :type => :boolean do |controller, scope|
+    #     scope.not_voted_by(controller.current_user.id) 
+    #   end
+    #
+    def has_scope(*scopes, &block)
       options = scopes.extract_options!
       options.symbolize_keys!
 
@@ -51,13 +68,13 @@ module HasScope
         options[:type] ||= :boolean
         ActiveSupport::Deprecation.warn(":boolean => true is deprecated, use :type => :boolean instead", caller)
       end
-      options.assert_valid_keys(:type, :only, :except, :if, :unless, :default, :as)
+      options.assert_valid_keys(:type, :only, :except, :if, :unless, :default, :as, :allow_blank)
 
       options[:only]   = Array(options[:only])
       options[:except] = Array(options[:except])
 
       scopes.each do |scope|
-        self.scopes_configuration[scope] ||= { :as => scope, :type => :default }
+        self.scopes_configuration[scope] ||= { :as => scope, :type => :default, :block => block }
         self.scopes_configuration[scope].merge!(options)
       end
     end
@@ -88,22 +105,34 @@ module HasScope
         value = value.call(self) if value.is_a?(Proc)
       end
 
-      target = apply_scope_by_type(options[:type], key, scope, value, target) if call_scope
+      if call_scope && (value.present? || options[:allow_blank])
+        set_current_scope(options[:type], key, value)
+        target = apply_scope_by_type(options[:type], scope, target, current_scopes[key], options[:block])
+      end
     end
 
     target
   end
 
-  # Apply the scope taking into account its type.
-  def apply_scope_by_type(type, key, scope, value, target) #:nodoc:
+  # Set the real value for the current scope if type check.
+  def set_current_scope(type, key, value) #:nodoc:
     if type == :boolean
       current_scopes[key] = TRUE_VALUES.include?(value)
-      current_scopes[key] ? target.send(scope) : target
     elsif ALLOWED_TYPES[type].none?{ |klass| value.is_a?(klass) }
       raise "Expected type :#{type} in params[:#{key}], got :#{value.class}"
     else
       current_scopes[key] = value
-      target.send(scope, value)
+    end
+  end
+
+  # Apply the scope taking into account its type.
+  def apply_scope_by_type(type, scope, target, value, block) #:nodoc:
+    return target if type == :boolean && value == false
+
+    if type == :boolean
+      block ? block.call(self, target) : target.send(scope)
+    else
+      block ? block.call(self, target, value) : target.send(scope, value)
     end
   end
 
@@ -140,4 +169,4 @@ module HasScope
   end
 end
 
-ApplicationController.send :include, HasScope
+ActionController::Base.send :include, HasScope

data/test/has_scope_test.rb

@@ -6,12 +6,20 @@ end
 class TreesController < ApplicationController
   has_scope :color, :unless => :show_all_colors?
   has_scope :only_tall, :type => :boolean, :only => :index, :if => :restrict_to_only_tall_trees?
-  has_scope :shadown_range, :default => 10, :except => [ :index, :show, :destroy, :new ]
-  has_scope :root_type, :as => :root
+  has_scope :shadown_range, :default => 10, :except => [ :index, :show, :new ]
+  has_scope :root_type, :as => :root, :allow_blank => true
   has_scope :calculate_height, :default => proc {|c| c.session[:height] || 20 }, :only => :new
   has_scope :paginate, :type => :hash
   has_scope :categories, :type => :array
 
+  has_scope :only_short, :type => :boolean do |controller, scope|
+    scope.only_really_short!(controller.object_id)
+  end
+
+  has_scope :by_category do |controller, scope, value|
+    scope.by_given_category(controller.object_id, value + "_id")
+  end
+
   def index
     @trees = apply_scopes(Tree).all
   end
@@ -50,7 +58,7 @@ class HasScopeTest < ActionController::TestCase
     assert_equal({ :only_tall => true }, current_scopes)
   end
 
-  def test_boolean_scope_is_called_when_boolean_param_is_false
+  def test_boolean_scope_is_not_called_when_boolean_param_is_false
     Tree.expects(:only_tall).never
     Tree.expects(:all).returns([mock_tree])
     get :index, :only_tall => 'false'
@@ -100,6 +108,22 @@ class HasScopeTest < ActionController::TestCase
     assert_equal({ :color => 'blue' }, current_scopes)
   end
 
+  def test_scope_is_not_called_if_blank
+    Tree.expects(:color).never
+    Tree.expects(:all).returns([mock_tree]).in_sequence
+    get :index, :color => ''
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ }, current_scopes)
+  end
+
+  def test_scope_is_called_when_blank_if_allow_blank_is_given
+    Tree.expects(:root_type).with('').returns(Tree)
+    Tree.expects(:all).returns([mock_tree]).in_sequence
+    get :index, :root => ''
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ :root => '' }, current_scopes)
+  end
+
   def test_multiple_scopes_are_called
     Tree.expects(:only_tall).with().returns(Tree)
     Tree.expects(:color).with('blue').returns(Tree)
@@ -172,6 +196,22 @@ class HasScopeTest < ActionController::TestCase
     assert_equal({ :calculate_height => 100 }, current_scopes)
    end
 
+   def test_scope_with_boolean_block
+     Tree.expects(:only_really_short!).with(@controller.object_id).returns(Tree)
+     Tree.expects(:all).returns([mock_tree])
+     get :index, :only_short => 'true'
+     assert_equal([mock_tree], assigns(:trees))
+     assert_equal({ :only_short => true }, current_scopes)
+   end
+
+   def test_scope_with_other_block_types
+     Tree.expects(:by_given_category).with(@controller.object_id, 'for_id').returns(Tree)
+     Tree.expects(:all).returns([mock_tree])
+     get :index, :by_category => 'for'
+     assert_equal([mock_tree], assigns(:trees))
+     assert_equal({ :by_category => 'for' }, current_scopes)
+   end
+
   protected
 
     def mock_tree(stubs={})

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: has_scope
 version: !ruby/object:Gem::Version 
-  version: "0.2"
+  version: "0.3"
 platform: ruby
 authors: 
 - "Jos\xC3\xA9 Valim"
@@ -22,10 +22,10 @@ extensions: []
 extra_rdoc_files: 
 - README.rdoc
 files: 
-- CHANGELOG.rdoc
 - MIT-LICENSE
 - README.rdoc
 - Rakefile
+- init.rb
 - lib/has_scope.rb
 has_rdoc: true
 homepage: http://github.com/plataformatec/has_scope