assignable_values 0.1.2 → 0.2.0

data/README.md

@@ -64,6 +64,16 @@ You can populate a `<select>` tag with pairs of internal values and human labels
 
     form.collection_select :genre, form.object.assignable_genres, :to_s, :humanized
 
+If you don't like to use your I18n dictionary for humanizations, you can also declare them directly in your model like this:
+
+    class Song < ActiveRecord::Base
+      assignable_values_for :genre do
+        { 'pop' => 'Pop music',
+          'rock' => 'Rock music',
+          'electronic' => 'Electronic music' }
+      end
+    end
+
 
 ### Defining default values
 
@@ -90,6 +100,20 @@ Defaults can be lambdas:
 The lambda will be evaluated in the context of the record instance.
 
 
+### Allowing blank values
+
+By default, an attribute *must* be assigned an value. If the value of an attribute is blank, the attribute
+will get a validation error.
+
+If you would like to change this behavior and allow blank values to be valid, use the `:allow_blank` option:
+
+    class Song < ActiveRecord::Base
+      assignable_values_for :genre, :default => 'rock', :allow_blank => true do
+        ['pop', 'rock', 'electronic']
+      end
+    end
+
+
 ### Values are only validated when they change
 
 Values are only validated when they change. This is useful when the list of assignable values can change during runtime:
@@ -174,16 +198,18 @@ The list of assignable values is generated at runtime. Since the given block is
     end
 
 
-Obtaining assignable values from a delegate
--------------------------------------------
+Obtaining assignable values from another source
+-----------------------------------------------
 
-The list of assignable values can be provided by a delegate. This is useful for authorization scenarios like [Consul](https://github.com/makandra/consul) or [CanCan](https://github.com/ryanb/cancan), where permissions are defined in a single class.
+The list of assignable values can be provided by any object that is accessible from your model. This is useful for authorization scenarios like [Consul](https://github.com/makandra/consul) or [CanCan](https://github.com/ryanb/cancan), where permissions are defined in a single class.
 
-    class Song < ActiveRecord::Base
+You can define the source of assignable values by setting the `:through` option to a lambda:
+
+    class Story < ActiveRecord::Base
       assignable_values_for :state, :through => lambda { Power.current }
     end
 
-`Power.current` must now respond to a method `assignable_song_states` or `assignable_song_states(song)` which returns an `Enumerable` of state strings:
+`Power.current` must now respond to a method `assignable_story_states` or `assignable_story_states(story)` which returns an `Enumerable` of state strings:
 
     class Power
 
@@ -193,7 +219,7 @@ The list of assignable values can be provided by a delegate. This is useful for
         @role = role
       end
 
-      def assignable_song_states(song)
+      def assignable_story_states(story)
         states = ['draft', 'pending']
         states << 'accepted' if @role == :admin
         states
@@ -203,30 +229,64 @@ The list of assignable values can be provided by a delegate. This is useful for
 
 Listing and validating works the same with delegation:
 
-    song = Song.new(:state => 'accepted')
+    story = Story.new(:state => 'accepted')
 
     Power.current = Power.new(:guest)
-    song.assignable_states # => ['draft', 'pending']
-    song.valid? # => false
+    story.assignable_states # => ['draft', 'pending']
+    story.valid? # => false
 
     Power.current = Power.new(:admin)
-    song.assignable_states # => ['draft', 'pending', 'accepted']
-    song.valid? # => true
+    story.assignable_states # => ['draft', 'pending', 'accepted']
+    story.valid? # => true
 
 Note that delegated validation is skipped when the delegate is `nil`. This way your model remains usable when there is no authorization context, like in batch processes or the console:
 
-    song = Song.new(:state => 'foo')
+    story = Story.new(:state => 'foo')
     Power.current = nil
-    song.valid? # => true
+    story.valid? # => true
+
+Think of this as enabling an optional authorization layer on top of your model validations, which can be switched on or off depending on the current context.
 
 Instead of a lambda you can also use the `:through` option to name an instance method:
 
-    class Song < ActiveRecord::Base
+    class Story < ActiveRecord::Base
       attr_accessor :power
       assignable_values_for :state, :through => :power
     end
 
 
+### Obtaining assignable values from a Consul power
+
+A common use case for the `:through` option is when there is some globally accessible object that knows about permissions for the current request. In practice you will find that it requires some effort to make sure such an object is properly instantiated and accessible.
+
+If you are using [Consul](https://github.com/makandra/consul), you will get a lot of this plumbing for free. Consul gives you a macro `current_power` to instantiate a so called "power", which describes what the current user may access:
+
+    class ApplicationController < ActionController::Base
+      include Consul::Controller
+
+      current_power do
+        Power.new(current_user)
+      end
+
+    end
+
+The code above will provide you with a helper method `current_power` for your controller and views. Everywhere else, you can simply access it from `Power.current`.
+
+You can now delegate validation of assignable values to the current power by saying:
+
+     class Story < ActiveRecord::Base
+       authorize_values_for :state
+     end
+
+This is a shortcut for saying:
+
+     class Story < ActiveRecord::Base
+       assignable_values_for :state, :through => lambda { Power.current }
+     end
+
+Head over to the [Consul README](https://github.com/makandra/consul) for details.
+
+
 Installation
 ------------
 
@@ -241,13 +301,13 @@ Development
 -----------
 
 - Fork the repository.
-- Push your changes with specs.
+- Push your changes with specs. There is a Rails 3 test application in `spec/app_root` if you need to test integration with a live Rails app.
 - Send me a pull request.
 
-I'm very eager to keep this gem leightweight and on topic. If you're unsure whether a change would make it into the gem, [talk to me beforehand](henning.koch@makandra.de).
+I'm very eager to keep this gem leightweight and on topic. If you're unsure whether a change would make it into the gem, [talk to me beforehand](mailto:henning.koch@makandra.de).
 
 
 Credits
 -------
 
-[Henning Koch](henning.koch@makandra.de) from [makandra](http://makandra.com/).
+[Henning Koch](mailto:henning.koch@makandra.de) from [makandra](http://makandra.com/).

data/assignable_values.gemspec

@@ -15,6 +15,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
+  s.add_dependency('activerecord')
+
   s.add_development_dependency('rails', '~>3.1')
   s.add_development_dependency('rspec', '~>2.8')
   s.add_development_dependency('rspec-rails', '~>2.8')

data/lib/assignable_values/active_record/restriction/base.rb

@@ -48,6 +48,10 @@ module AssignableValues
 
         private
 
+        def parse_values(values)
+          values.to_a
+        end
+
         def current_value(record)
           record.send(property)
         end
@@ -115,10 +119,11 @@ module AssignableValues
 
         def raw_assignable_values(record)
           if delegate?
-            assignable_values_from_delegate(record)
+            values = assignable_values_from_delegate(record)
           else
-            record.instance_eval(&@values)
-          end.to_a
+            values = record.instance_eval(&@values)
+          end
+          parse_values(values)
         end
 
         def delegate(record)

data/lib/assignable_values/active_record/restriction/scalar_attribute.rb

@@ -10,13 +10,26 @@ module AssignableValues
 
         def humanize_string_value(value)
           if value.present?
-            dictionary_key = "assignable_values.#{model.name.underscore}.#{property}.#{value}"
-            I18n.t(dictionary_key, :default => value.humanize)
+            if @hardcoded_humanizations
+              @hardcoded_humanizations[value]
+            else
+              dictionary_key = "assignable_values.#{model.name.underscore}.#{property}.#{value}"
+              I18n.t(dictionary_key, :default => value.humanize)
+            end
           end
         end
 
         private
 
+        def parse_values(values)
+          if values.is_a?(Hash)
+            @hardcoded_humanizations = values
+            values = values.keys
+          else
+            super
+          end
+        end
+
         def define_humanized_method
           restriction = self
           enhance_model do
@@ -44,7 +57,6 @@ module AssignableValues
           record.send("#{property}_was")
         end
 
-
       end
     end
   end

data/lib/assignable_values/version.rb

@@ -1,3 +1,3 @@
 module AssignableValues
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

data/spec/assignable_values/active_record_spec.rb

@@ -4,13 +4,11 @@ require 'ostruct'
 describe AssignableValues::ActiveRecord do
 
   def disposable_song_class(&block)
-    @klass = Class.new(Song, &block)
-    @klass.class_eval do
-      def self.name
-        'Song'
-      end
+    klass = Class.new(Song, &block)
+    def klass.name
+      'Song'
     end
-    @klass
+    klass
   end
 
   describe '.assignable_values' do
@@ -99,22 +97,22 @@ describe AssignableValues::ActiveRecord do
       it 'should validate that the association is allowed' do
         allowed_association = Artist.create!
         disallowed_association = Artist.create!
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :artist do
             [allowed_association]
           end
         end
-        @klass.new(:artist => allowed_association).should be_valid
-        @klass.new(:artist => disallowed_association).should_not be_valid
+        klass.new(:artist => allowed_association).should be_valid
+        klass.new(:artist => disallowed_association).should_not be_valid
       end
 
       it 'should allow a nil association if the :allow_blank option is set' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :artist, :allow_blank => true do
             []
           end
         end
-        record = @klass.new
+        record = klass.new
         record.artist.should be_nil
         record.should be_valid
       end
@@ -122,9 +120,9 @@ describe AssignableValues::ActiveRecord do
       it 'should allow a previously saved association even if that association is no longer allowed' do
         allowed_association = Artist.create!
         disallowed_association = Artist.create!
-        @klass = disposable_song_class
-        record = @klass.create!(:artist => disallowed_association)
-        @klass.class_eval do
+        klass = disposable_song_class
+        record = klass.create!(:artist => disallowed_association)
+        klass.class_eval do
           assignable_values_for :artist do
             [allowed_association]
           end
@@ -134,36 +132,36 @@ describe AssignableValues::ActiveRecord do
 
       it "should not load a previously saved association if the association's foreign key hasn't changed" do
         association = Artist.create!
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :artist do
             [association] # This example doesn't care about what's assignable. We're only interested in behavior up to the validation.
           end
         end
-        record = @klass.create!(:artist => association)
+        record = klass.create!(:artist => association)
         Artist.should_not_receive(:find_by_id)
         record.valid?
       end
 
       it 'should not fail or allow nil if a previously saved association no longer exists in the database' do
         allowed_association = Artist.create!
-        disposable_song_class.class_eval do
+        klass = disposable_song_class do
           assignable_values_for :artist do
             [allowed_association]
           end
         end
-        record = @klass.new
+        record = klass.new
         record.stub :artist_id_was => -1
         record.should_not be_valid
       end
 
       it 'should uncache a stale association before validating' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :artist do
             [] # This example doesn't care about what's assignable. We're only interested in behavior up to the validation.
           end
         end
         association = Artist.create!
-        record = @klass.new
+        record = klass.new
         record.stub(:artist => association, :artist_id => -1) # This is a stale association: The associated object's id doesn't match the foreign key. This can happen in Rails 2, not Rails 3.
         record.should_receive(:artist).ordered.and_return(association)
         record.should_receive(:artist).ordered.with(true).and_return(association)
@@ -171,13 +169,13 @@ describe AssignableValues::ActiveRecord do
       end
 
       it 'should not uncache a fresh association before validating' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :artist do
             [] # This example doesn't care about what's assignable. We're only interested in behavior up to the validation.
           end
         end
         association = Artist.create!
-        record = @klass.new
+        record = klass.new
         record.stub(:artist => association, :artist_id => association.id) # This is a fresh association: The associated object's id matches the foreign key.
         record.should_receive(:artist).with(no_args).and_return(association)
         record.valid?
@@ -188,35 +186,35 @@ describe AssignableValues::ActiveRecord do
     context 'when delegating using the :through option' do
 
       it 'should obtain allowed values from a method with the given name' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :through => :delegate
           def delegate
             OpenStruct.new(:assignable_song_genres => %w[pop rock])
           end
         end
-        @klass.new(:genre => 'pop').should be_valid
-        @klass.new(:genre => 'disallowed value').should_not be_valid
+        klass.new(:genre => 'pop').should be_valid
+        klass.new(:genre => 'disallowed value').should_not be_valid
       end
 
       it 'should be able to delegate to a lambda, which is evaluated in the context of the record instance' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :through => lambda { delegate }
           def delegate
             OpenStruct.new(:assignable_song_genres => %w[pop rock])
           end
         end
-        @klass.new(:genre => 'pop').should be_valid
-        @klass.new(:genre => 'disallowed value').should_not be_valid
+        klass.new(:genre => 'pop').should be_valid
+        klass.new(:genre => 'disallowed value').should_not be_valid
       end
 
       it 'should skip the validation if that method returns nil' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :through => :delegate
           def delegate
             nil
           end
         end
-        @klass.new(:genre => 'pop').should be_valid
+        klass.new(:genre => 'pop').should be_valid
       end
 
     end
@@ -224,25 +222,25 @@ describe AssignableValues::ActiveRecord do
     context 'with :default option' do
 
       it 'should allow to set a default' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :default => 'pop' do
             %w[pop rock]
           end
         end
-        @klass.new.genre.should == 'pop'
+        klass.new.genre.should == 'pop'
       end
 
       it 'should allow to set a default through a lambda' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :default => lambda { 'pop' } do
             %w[pop rock]
           end
         end
-        @klass.new.genre.should == 'pop'
+        klass.new.genre.should == 'pop'
       end
 
       it 'should evaluate a lambda default in the context of the record instance' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre, :default => lambda { default_genre } do
             %w[pop rock]
           end
@@ -250,7 +248,7 @@ describe AssignableValues::ActiveRecord do
             'pop'
           end
         end
-        @klass.new.genre.should == 'pop'
+        klass.new.genre.should == 'pop'
       end
 
     end
@@ -258,54 +256,25 @@ describe AssignableValues::ActiveRecord do
     context 'when generating methods to list assignable values' do
 
       it 'should generate an instance method returning a list of assignable values' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre do
             %w[pop rock]
           end
         end
-        @klass.new.assignable_genres.should == %w[pop rock]
-      end
-
-      it "should define a method #humanized on strings in that list, which return up the value's' translation" do
-        @klass = disposable_song_class do
-          assignable_values_for :genre do
-            %w[pop rock]
-          end
-        end
-        @klass.new.assignable_genres.collect(&:humanized).should == ['Pop music', 'Rock music']
-      end
-
-      it 'should use String#humanize as a default translation' do
-        @klass = disposable_song_class do
-          assignable_values_for :genre do
-            %w[electronic]
-          end
-        end
-        @klass.new.assignable_genres.collect(&:humanized).should == ['Electronic']
-      end
-
-      it 'should not define a method #humanized on values that are not strings' do
-        @klass = disposable_song_class do
-          assignable_values_for :year do
-            [1999, 2000, 2001]
-          end
-        end
-        years = @klass.new.assignable_years
-        years.should == [1999, 2000, 2001]
-        years.first.should_not respond_to(:humanized)
+        klass.new.assignable_genres.should == %w[pop rock]
       end
 
       it 'should call #to_a on the list of assignable values, allowing ranges and scopes to be passed as allowed value descriptors' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :year do
             1999..2001
           end
         end
-        @klass.new.assignable_years.should == [1999, 2000, 2001]
+        klass.new.assignable_years.should == [1999, 2000, 2001]
       end
 
       it 'should evaluate the value block in the context of the record instance' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre do
             genres
           end
@@ -313,30 +282,72 @@ describe AssignableValues::ActiveRecord do
             %w[pop rock]
           end
         end
-        @klass.new.assignable_genres.should == %w[pop rock]
+        klass.new.assignable_genres.should == %w[pop rock]
       end
 
       it 'should include a previously saved value, even if is no longer allowed' do
-        @klass = disposable_song_class do
+        klass = disposable_song_class do
           assignable_values_for :genre do
             %w[pop rock]
           end
         end
-        record = @klass.new(:genre => 'ballad')
+        record = klass.new(:genre => 'ballad')
         record.save!(:validate => false)
         record.assignable_genres.should =~ %w[pop rock ballad]
       end
 
+      context 'humanization' do
+
+        it "should define a method #humanized on strings in that list, which return up the value's' translation" do
+          klass = disposable_song_class do
+            assignable_values_for :genre do
+              %w[pop rock]
+            end
+          end
+          klass.new.assignable_genres.collect(&:humanized).should == ['Pop music', 'Rock music']
+        end
+
+        it 'should use String#humanize as a default translation' do
+          klass = disposable_song_class do
+            assignable_values_for :genre do
+              %w[electronic]
+            end
+          end
+          klass.new.assignable_genres.collect(&:humanized).should == ['Electronic']
+        end
+
+        it 'should not define a method #humanized on values that are not strings' do
+          klass = disposable_song_class do
+            assignable_values_for :year do
+              [1999, 2000, 2001]
+            end
+          end
+          years = klass.new.assignable_years
+          years.should == [1999, 2000, 2001]
+          years.first.should_not respond_to(:humanized)
+        end
+
+        it 'should allow to directly declare humanized values by passing a hash to assignable_values_for' do
+          klass = disposable_song_class do
+            assignable_values_for :genre do
+              { 'pop' => 'Pop music', 'rock' => 'Rock music' }
+            end
+          end
+          klass.new.assignable_genres.collect(&:humanized).should =~ ['Pop music', 'Rock music']
+        end
+
+      end
+
       context 'with :through option' do
 
         it 'should retrieve assignable values from the given method' do
-          @klass = disposable_song_class do
+          klass = disposable_song_class do
             assignable_values_for :genre, :through => :delegate
             def delegate
               @delegate ||= 'delegate'
             end
           end
-          record = @klass.new
+          record = klass.new
           record.delegate.should_receive(:assignable_song_genres).and_return %w[pop rock]
           record.assignable_genres.should == %w[pop rock]
         end
@@ -347,25 +358,25 @@ describe AssignableValues::ActiveRecord do
             record_received(record)
              %w[pop rock]
           end
-          @klass = disposable_song_class do
+          klass = disposable_song_class do
             assignable_values_for :genre, :through => :delegate
             define_method :delegate do
               delegate
             end
           end
-          record = @klass.new
+          record = klass.new
           delegate.should_receive(:record_received).with(record)
           record.assignable_genres.should ==  %w[pop rock]
         end
 
         it 'should raise an error if the given method returns nil' do
-          @klass = disposable_song_class do
+          klass = disposable_song_class do
             assignable_values_for :genre, :through => :delegate
             def delegate
               nil
             end
           end
-          expect { @klass.new.assignable_genres }.to raise_error(AssignableValues::DelegateUnavailable)
+          expect { klass.new.assignable_genres }.to raise_error(AssignableValues::DelegateUnavailable)
         end
 
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: assignable_values
 version: !ruby/object:Gem::Version 
-  hash: 31
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
   - 2
-  version: 0.1.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Henning Koch
@@ -15,12 +15,27 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-02-20 00:00:00 +01:00
+date: 2012-06-15 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
+  type: :runtime
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  name: activerecord
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  type: :development
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -31,11 +46,11 @@ dependencies:
         - 1
         version: "3.1"
   name: rails
-  version_requirements: *id001
-  type: :development
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -46,11 +61,11 @@ dependencies:
         - 8
         version: "2.8"
   name: rspec
-  version_requirements: *id002
-  type: :development
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -61,11 +76,11 @@ dependencies:
         - 8
         version: "2.8"
   name: rspec-rails
-  version_requirements: *id003
-  type: :development
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
+  type: :development
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -75,8 +90,7 @@ dependencies:
         - 0
         version: "0"
   name: sqlite3
-  version_requirements: *id004
-  type: :development
+  version_requirements: *id005
 description: Restrict the values assignable to ActiveRecord attributes or associations. Or enums on steroids.
 email: henning.koch@makandra.de
 executables: []
@@ -157,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.9.3
+rubygems_version: 1.3.9.4
 signing_key: 
 specification_version: 3
 summary: Restrict the values assignable to ActiveRecord attributes or associations. Or enums on steroids.