attribute_ext 1.1.0 → 1.2.4

data/README.md

@@ -58,6 +58,44 @@ or
 	class User < ActiveRecord::Base
 	  safe_attributes :login, :if => Proc.new { |user,role| role == :admin }
 	end
+	
+Default role and role mapper:
+
+SafeAttributes provides helper for handling roles including a method to set
+a new default role as well as a method to map roles to other values. Changes to
+role will only affect SafeAttributes and will not be given to Rails 3.1 mass
+assignment authorizer.
+
+Set default role that will be used if given role is nil or :default.
+
+	AttributeExt::SafeAttributes.default_role = :new_default
+	
+Role values can be restricted to specific values using the role mapper.
+
+	AttributeExt::SafeAttributes.role_mapper = Proc.new do |role|
+	  [:guest, :user, :admin].include?(role) ? role : :guest
+	end
+	
+or
+
+	AttributeExt::SafeAttributes.role_mapper do |role|
+	  [:guest, :user, :admin].include?(role) ? role : :guest
+	end
+
+The role mapper is especially usefull if you want the current user model be the
+default role.
+
+	AttributeExt::SafeAttributes.role_mapper do |role|
+	  role.is_a?(User) ? role : User.current
+	end
+	
+You can perform checks like this now:
+
+	class User < ActiveRecord::Base
+	  safe_attribute :email, :if => Proc.new { |user,role| user == role or role.admin? }
+	end
+	
+Now the user can edit there own emails or everyons email if it is an admin.
 
 
 AttributeExt::HiddenAttributes
@@ -115,6 +153,12 @@ By default rules *do not* apply when serializing to hash.
 Changelog
 ---------
 
+Sep 24, 2011
+
+SafeAttributes provides methods to change default role and to map roles to 
+specific values before processing rules. Also added full documentation to 
+all public methods and methods that are usefull for testing own rules.
+
 Sep 22, 2011
 
 Nearly all features are successfully tested using a fake environment now.

data/attribute_ext.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "attribute_ext"
-  s.version     = "1.1.0"
+  s.version     = "1.2.4"
   s.authors     = ["Jan Graichen"]
   s.email       = ["jan.graichen@altimos.de"]
   s.homepage    = "https://github.com/jgraichen/attribute_ext"

data/init.rb

@@ -1,5 +1,4 @@
 
 require 'attribute_ext'
 
-ActiveRecord::Base.send :include, AttributeExt::HiddenAttributes
-ActiveRecord::Base.send :include, AttributeExt::SafeAttributes
+AttributeExt.setup

data/lib/attribute_ext.rb

@@ -2,3 +2,10 @@
 require 'attribute_ext/hidden_attributes'
 require 'attribute_ext/safe_attributes'
 require 'attribute_ext/railtie' if defined?(Rails)
+
+module AttributeExt
+  def AttributeExt.setup # :nodoc:
+    ActiveRecord::Base.send :include, AttributeExt::HiddenAttributes
+    ActiveRecord::Base.send :include, AttributeExt::SafeAttributes
+  end
+end

data/lib/attribute_ext/hidden_attributes.rb

@@ -1,6 +1,6 @@
 module AttributeExt
   module HiddenAttributes
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.extend(ClassMethods)
       base.alias_method_chain :to_xml, :hidden_attrs
       base.alias_method_chain :as_json, :hidden_attrs
@@ -8,6 +8,39 @@ module AttributeExt
     end
   
     module ClassMethods
+      # Adds attribute to a blacklist that will be hidden when serializing if optional conditions
+      # are true.
+      #
+      #   class User < ActiveRecord::Base
+      #     hide_attributes :password               # always hide
+      #     hide_attributes :email, :if => Proc.new { |user| user.hide_email? }
+      #     hide_attributes :not_in_json, :only => :json
+      #     hide_attributes :except_xml_hash, :except => [:xml, :hash]
+      #   end
+      # 
+      # All given conditions to a rule must be true if attributes should be hidden. Attributes can
+      # appear in more than one rule.
+      #
+      # Options:
+      # [:+if+]
+      #   Requires a Proc block to be true.
+      # 
+      # [:+unless+]
+      #   Requires a Proc block to be false.
+      #
+      # [:+only+]
+      #   Requires export format to be in given array. A non array object will be converted in to
+      #   an array only containing given object.
+      #
+      # [:+except+]
+      #   Requires export format to not be in given array. A non array object will be converted in 
+      #   to an array only containing given object.
+      # 
+      # [:+on_hash+]
+      #   By default rules will not be applied when serializing to hash when no :only or :except
+      #   rule is specified. If :on_hash is true rule will also apply to hash serialization. If an
+      #   :only or :except option is given :on_hash does nothing.
+      #
       def hide_attributes(*attrs)
         @hidden_attributes ||= []
         if attrs.empty?
@@ -34,14 +67,14 @@ module AttributeExt
       end
     end
   
-    def to_xml_with_hidden_attrs(options = nil, &block)
+    def to_xml_with_hidden_attrs(options = nil, &block) # :nodoc:
       options ||= {}
       options[:except] = hidden_attribute_names(:xml, options)
       
       to_xml_without_hidden_attrs(options)
     end
   
-    def as_json_with_hidden_attrs(options = nil, &block)
+    def as_json_with_hidden_attrs(options = nil, &block) # :nodoc:
       options ||= {}
       options[:except] = hidden_attribute_names(:json, options)
       options[:hidden_attributes_format] = :json
@@ -49,13 +82,20 @@ module AttributeExt
       as_json_without_hidden_attrs(options)
     end
   
-    def serializable_hash_with_hidden_attrs(options = nil)
+    def serializable_hash_with_hidden_attrs(options = nil) # :nodoc:
       options ||= {}
       options[:except] = hidden_attribute_names((options[:hidden_attributes_format] || :hash), options)
       
       serializable_hash_without_hidden_attrs(options)
     end
     
+    # Returns an array with attributes to hide from serialization.
+    # 
+    # This method should only be used to test own rules without need to run a formatter and
+    # validate the generated output. See AttributeExt specs for details.
+    # 
+    #   hidden_attribute_names :format, :options => :hash
+    # 
     def hidden_attribute_names(format, options = {})
       if options[:except].is_a?(Array)
         names = options[:except]

data/lib/attribute_ext/railtie.rb

@@ -1,10 +1,9 @@
 
 module AttributeExt
-  class Railtie < Rails::Railtie
+  class Railtie < Rails::Railtie # :nodoc:
     initializer 'attribute_ext' do |app|
       ActiveSupport.on_load :active_record do
-        ActiveRecord::Base.send :include, AttributeExt::HiddenAttributes
-        ActiveRecord::Base.send :include, AttributeExt::SafeAttributes
+        AttributeExt.setup
       end
     end
   end

data/lib/attribute_ext/safe_attributes.rb

@@ -1,11 +1,81 @@
 module AttributeExt
   module SafeAttributes
-    def self.included(base)
+    # Returns default role used by SafeAttributes.
+    # See SafeAttributes#default_role= for how to specify a default role.
+    def SafeAttributes.default_role
+      @default_role || :default
+    end
+    
+    # Sets SafeAttributes default role that will be used when given role
+    # is a nil value or the :default role. The SafeAttributes default role will
+    # only affect this extension and will not be given to Rails 3.1 mass 
+    # assignment authorizer.
+    def SafeAttributes.default_role=(role)
+      @default_role = role
+    end
+    
+    # Returns current role mapper block or sets role mapper if an block is
+    # given. By default no role mapper is active.
+    #
+    #   AttributeExt::SafeAttributes.role_mapper do |role|
+    #     [:guest, :user, :admin].include?(role) ? role : :guest
+    #   end
+    #
+    def SafeAttributes.role_mapper(&block)
+      self.role_mapper = block if block
+      @role_mapper
+    end
+    
+    # Sets current role mapper to given Proc or removes role mapper if
+    # a nil value is given. Any other value will do nothing.
+    # 
+    #   AttributeExt::SafeAttributes.role_mapper = Proc.new do |role|
+    #     [:guest, :user, :admin].include?(role) ? role : :guest
+    #   end
+    # 
+    # See SafeAttributes#role_mapper for an short way to set a role mapper.
+    def SafeAttributes.role_mapper=(role_mapper)
+      @role_mapper = role_mapper if role_mapper.is_a?(Proc)
+      @role_mapper = nil if role_mapper.nil?
+    end
+    
+    def self.included(base)  # :nodoc:
       base.extend(ClassMethods)
       base.alias_method_chain :mass_assignment_authorizer, :safe_attrs
     end
 
+    
     module ClassMethods
+      # Adds a whitelist rule that allows mass assignment for given attributes
+      # based on given optional conditions.
+      # 
+      #   class User < ActiveRecord::Base
+      #     # always mass assignable
+      #     safe_attributes :name, :email
+      #     # only when new record
+      #     safe_attributes :login, :if => Proc.new { |user| user.new_record? }
+      #     # only own password or as admin
+      #     safe_attributes :password, :if => Proc.new { |user,role| user == role }
+      #     safe_attributes :password, :as => :admin
+      #   end
+      # 
+      # All given conditions for one rule must be true to allow mass 
+      # assignment for given attributes. Attributes can be added in more than
+      # one rule to allow alternatives (like password above).
+      # 
+      # Available Options:
+      # [:+as+]
+      #   Attributes will be assignable if mass assignment role is equal (==) given object.
+      #
+      # [:+if+]
+      #   Makes attributes assignable if given Proc block returns true.
+      #
+      # [:+unless+]
+      #   Attributes cannot be mass assigned if Proc block evaluates to true.
+      #
+      # The :if and :unless options must be Proc block that will be executed each time the 
+      # mass assignment authorizer is called and they are called with current 
+      # model and role as parameters.
       def safe_attributes(*attrs)
         @safe_attributes ||= []
         if attrs.empty?
@@ -26,12 +96,34 @@ module AttributeExt
       end
     end
 
-    def mass_assignment_authorizer_with_safe_attrs(role = nil)
-      attrs = role.nil? ? mass_assignment_authorizer_without_safe_attrs : mass_assignment_authorizer_without_safe_attrs(role)
-      attrs += safe_attribute_names(role ? role : :default)
+    def mass_assignment_authorizer_with_safe_attrs(role = nil) # :nodoc:
+      if role.nil? 
+        attrs = mass_assignment_authorizer_without_safe_attrs +
+          safe_attribute_names
+      else
+        attrs = mass_assignment_authorizer_without_safe_attrs(role) +
+          safe_attribute_names(role)
+      end
+    end
+    
+    # Returns new mapped role for given role used by SafeAttributes.
+    # This method should only be used to test own role mapper implementations without need for a 
+    # full application. See AttributeExt specs for details.
+    # 
+    # See +role_mapper+ method in SafeAttributes module for how to set a role mapper.
+    def safe_attributes_role(role = nil)
+      return AttributeExt::SafeAttributes.role_mapper.call(role) unless AttributeExt::SafeAttributes.role_mapper.nil?
+      return AttributeExt::SafeAttributes.default_role if role.nil? or role == :default
+      role
     end
 
-    def safe_attribute_names(role = :default)
+    # Returns an array with attributes allowed to be mass assigned by given role. Role will be
+    # mapped before given to rules.
+    # This method should only be used to test own rules without need to create lots of records
+    # to test different situations. See AttributeExt specs for details.
+    def safe_attribute_names(role = nil)
+      role = safe_attributes_role(role)
+      
       names = []
       self.class.safe_attributes.collect do |attrs, options|
         next unless options[:as].empty? or options[:as].include?(role)

data/spec/safe_attributes_spec.rb

@@ -62,4 +62,61 @@ describe AttributeExt::HiddenAttributes do
     user = User.new
     user.mass_assignment_authorizer(:admin).should_not include('attribute_unless_admin')
   end
+  
+  it 'can provide a global default role' do
+    AttributeExt::SafeAttributes.default_role = :new_default
+    AttributeExt::SafeAttributes.default_role.should == :new_default
+    User.new.mass_assignment_authorizer.should include("new_default")
+  end
+  
+  context '#role_mapper' do
+    it 'is nil by default' do
+      AttributeExt::SafeAttributes.role_mapper.should be_nil
+    end
+    
+    it 'accept Procs' do
+      proc = Proc.new { |role| role }
+      AttributeExt::SafeAttributes.role_mapper = proc
+      AttributeExt::SafeAttributes.role_mapper.should equal(proc)
+    end
+    
+    it 'accept nil' do
+      AttributeExt::SafeAttributes.role_mapper = nil
+      AttributeExt::SafeAttributes.role_mapper.should be_nil
+    end
+    
+    it 'accept blocks' do
+      AttributeExt::SafeAttributes.role_mapper { |role| role }
+      AttributeExt::SafeAttributes.role_mapper.should be_an Proc
+    end
+  
+    it 'maps role according to given Proc' do
+      AttributeExt::SafeAttributes.role_mapper = Proc.new do |role|
+        [:guest, :user, :admin].include?(role) ? role : :guest
+      end
+      
+      User.new.safe_attributes_role.should == :guest
+      User.new.safe_attributes_role(:user).should == :user
+      User.new.safe_attributes_role(:admin).should == :admin
+      User.new.safe_attributes_role(:heinz).should == :guest
+    end
+    
+    it 'gives role to rules' do
+      AttributeExt::SafeAttributes.role_mapper = Proc.new do |role|
+        [:guest, :user, :admin].include?(role) ? role : :guest
+      end
+      
+      User.new.mass_assignment_authorizer.should include('role_mapper_guest')
+      User.new.mass_assignment_authorizer.should_not include('role_mapper_user')
+      User.new.mass_assignment_authorizer.should_not include('role_mapper_admin')
+      
+      User.new.mass_assignment_authorizer(:user).should_not include('role_mapper_guest')
+      User.new.mass_assignment_authorizer(:user).should include('role_mapper_user')
+      User.new.mass_assignment_authorizer(:user).should_not include('role_mapper_admin')
+      
+      User.new.mass_assignment_authorizer(:admin).should_not include('role_mapper_guest')
+      User.new.mass_assignment_authorizer(:admin).should_not include('role_mapper_user')
+      User.new.mass_assignment_authorizer(:admin).should include('role_mapper_admin')
+    end
+  end
 end

data/spec/support/stub.rb

@@ -54,6 +54,10 @@ class User < ActiveRecord::Base
     :if => Proc.new { |user,role| role == :admin}
   safe_attributes :attribute_unless_admin,
     :unless => Proc.new { |user,role| role == :admin}
+  safe_attributes :new_default, :as => :new_default
+  safe_attributes :role_mapper_guest, :if => Proc.new { |user,role| role == :guest }
+  safe_attributes :role_mapper_user, :as => :user
+  safe_attributes :role_mapper_admin, :if => Proc.new { |user,role| role == :admin }
   
   def initialize(opts = {})
     @opts = {
@@ -61,4 +65,4 @@ class User < ActiveRecord::Base
       :unless => true
     }.merge(opts.is_a?(Hash) ? opts : {})
   end
-end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: attribute_ext
 version: !ruby/object:Gem::Version 
-  hash: 19
+  hash: 23
   prerelease: 
   segments: 
   - 1
-  - 1
-  - 0
-  version: 1.1.0
+  - 2
+  - 4
+  version: 1.2.4
 platform: ruby
 authors: 
 - Jan Graichen
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-22 00:00:00 Z
+date: 2011-09-24 00:00:00 Z
 dependencies: []
 
 description: AttributeExt provides additional access control for rails model attributes.