acts-as-optionable 0.0.0 → 0.1.1

data/README.rdoc

@@ -0,0 +1,116 @@
+= ActsAsOptionable
+
+*Warning* I don't recommend using this yet since I'm going to make a couple core changes shortly.  Very alpha.
+
+Support to add options, as well as specify default options, to ActiveRecord models.  It's currently a very basic approach, and allows you to fetch options from an ActiveRecord model via an association, or via a hash or object where options are callable as methods.  It doesn't support any advanced finder options.
+
+It works by creating an options table which is polymorphic to ActiveRecord models which call acts_as_optionable.
+
+The plugin also grants the ability to specify default options for a class, or pass in defaults to an instance at runtime.
+
+== Installation
+
+Available as a gem:
+
+  gem install acts-as-optionable
+
+=== Post Installation
+
+This creates an Option model in you app.
+
+1. script/generate option
+2. Rake db:migrate
+
+== Usage
+
+=== Adding options to a model
+
+  class Style < ActiveRecord::Base
+    acts_as_optionable
+  end
+  
+=== Setting, getting, and deleting options
+
+Use #get_option, #set_option, and #delete_option for interacting with options.
+
+  style = Style.create
+  style.set_option("color", "red")
+  style.get_option("color").value => "red"
+  style.delete_option("color")
+  style.get_option("color") => nil
+
+
+=== Specifying default options at the class level
+
+  class StyleWithDefaults < ActiveRecord::Base
+    acts_as_optionable
+  
+    specify_option :background_color, :default => "white"
+    specify_option :color, :default => "black"
+  end
+  
+  style = StyleWithDefaults.create
+  style.get_option("background_color").value => "white"
+  
+=== Specifying instance options at runtime
+
+  style.instance_specified_options = { :foo => {:default => "FOO"} }
+  style.get_option("foo").value => "FOO"
+
+=== Persisting options specific to a record
+
+You can persist numeric, boolean, or string values for storage.
+
+  style.set_option("color", "red")
+  style.get_option("color").value => "red"
+  
+  style.set_option("active", false)
+  style.get_option("active").value => false
+  
+  style.set_option("max_time", 3600)
+  style.get_option("max_time").value => 3600 
+
+=== Option precedence
+
+Options are preferred in the following order:
+
+1. Stored options specific for this record
+2. Runtime options provided to the instance
+3. Class options specified at load time.
+
+Example:
+
+  class StyleWithDefaults < ActiveRecord::Base
+    acts_as_optionable
+
+    specify_option :background_color, :default => "white"
+    specify_option :color, :default => "black"
+  end
+  
+  style = StyleWithDefaults.create
+  style.instance_specified_options = { :color => { :default => "green" } }
+  style.get_option("background_color").value => "white"
+  style.get_option("color").value => "green"
+  style.set_option("color", "blue")
+  style.get_option("color").value => "blue"
+  
+
+=== Easy options and values retrieval
+
+Use #options_values_struct to grab a struct to allow for method based calls for all default and set options:
+
+  style = StyleWithDefaults.create
+  options = style.options_values_struct
+  options.color => "black"
+  
+This is useful, for instance, for passing a set of options into a liquid template.
+
+== TODO
+
+* Thinking about finding a way to optionally associate the option with an asset table.  This would be useful for allowing user defined stylesheet options referencing S3 assets.
+* Add in a way to return an option value straight away.
+* Assign multiple settings at a time.
+
+
+
+Copyright (c) 2010 Brendon Murphy, released under the MIT license

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.1

data/lib/acts_as_optionable/acts_as_optionable.rb

@@ -15,6 +15,7 @@ module ActiveRecord
       end
     
       module IntanceMethods
+        # Store an option persistently and override default option
         def set_option(name, value)
           option = get_stored_option(name) || options.build(:name => name.to_s)
           return if new_option_matches_current?(option)
@@ -24,19 +25,13 @@ module ActiveRecord
           ret
         end
         
+        # Get a stored option, or fall back to a default option
         def get_option(name)
           get_stored_option(name) ||
           get_default_option(name)
-        end
-        
-        def get_default_option(name)
-          instance_specified_option(name) || self.class.get_specified_option(name)
-        end
-        
-        def get_default_options
-          self.class.optionable_specified_options.merge(instance_specified_options || {})
-        end
+        end        
         
+        # Delete a stored option.
         def delete_option(name)
           if option = options(:reload).find_by_name(name.to_s)
             option = option.destroy
@@ -46,26 +41,53 @@ module ActiveRecord
         end
         
         def options_and_defaults
-          options_as_hash = options.inject({}) do |memo, option|
-            memo[option.name.to_s] = option
-            memo
-          end
           get_default_options.merge(options_as_hash)
         end
-      
-        def specified_options
-          raise "TODO"
-        end
         
+        # Returns an instance of options where option names are callable as methods
+        #
+        # Example:
+        #   # Where foo is 'FOO' & bar is 'BAR'
+        #   options = foo.options_values_struct 
+        #   options.foo => "FOO"
+        #   options.bar => "BAR"
+        def options_values_struct
+          options = {}
+          options_and_defaults.each do |name, option|
+            options[name.to_s] = option.value
+          end        
+          OpenStruct.new(options)
+        end
+                
         protected
         
+        # Gets the default option if set.  Prefers instance default over class default.
+        def get_default_option(name)
+          instance_specified_option(name) || self.class.get_specified_option(name)
+        end
+        
+        # Get a hash of all default options, with option names as keys.
+        def get_default_options
+          self.class.optionable_specified_options.merge(instance_specified_options || {})
+        end
+        
+        # Find the stored option in the database
         def get_stored_option(name)
           options.detect { |option| option.name.to_s == name.to_s }
         end
         
+        # Check if a new value provided is the same as the default option.
         def new_option_matches_current?(option)
           (!option.new_record? && option.value == value) || (get_default_option(name).value == value rescue nil)
         end
+        
+        # Return the stored options as a hash, with the option names as keys.
+        def options_as_hash
+          options.inject({}) do |memo, option|
+            memo[option.name.to_s] = option
+            memo
+          end
+        end
       end
     end
   end  

data/lib/acts_as_optionable/specify_option.rb

@@ -3,14 +3,17 @@ module ActiveRecord
     module Optionable
       module SpecifyOption
         module ClassMethods
+          # Setup a default value at the class level.
           def specify_option(option_name, opts = {})
             optionable_specified_options[option_name.to_s] = Option.new_readonly(:name => option_name.to_s, :default => opts[:default])
           end
           
+          # Returns a hash of options specified at the class level
           def optionable_specified_options
             @optionable_specified_options ||= {}
           end
 
+          # Get an option specified at the class level.
           def get_specified_option(option_name)
             optionable_specified_options[option_name.to_s]
           end          
@@ -19,12 +22,20 @@ module ActiveRecord
         module InstanceMethods
           attr_reader :instance_specified_options
 
+          # Return an option specified for this instance
           def instance_specified_option(option_name)
             instance_specified_options[option_name.to_s] if instance_specified_options
           end
 
+          # Setup instance options.  Pass in a hash of options as such:
+          #   instance_options = {
+          #     :foo => { :default => "FOO" },
+          #     :bar => { :default => "BAR" }
+          #   }
+          #   foo.instance_specified_options = instance_options
+          #
+          # These options only persist in the instance, and aren't stored to database.
           def instance_specified_options=(opts)
-            opts.symbolize_keys!
             @instance_specified_options = {}
             opts.each do |option_name, attributes|
               attributes.symbolize_keys!

data/spec/acts_as_optionable_spec.rb

@@ -63,7 +63,7 @@ describe "ActsAsOptionable" do
   
   describe "specifying options at class level" do
     it "should have the proper number of options set" do
-      @optionable.get_default_options.length.should == 2
+      @optionable.options_and_defaults.keys.length.should == 2
     end
     
     it "should have the expected options set" do
@@ -229,4 +229,25 @@ describe "ActsAsOptionable" do
       end
     end
   end
+  
+  describe "fetching an object with option names and values" do
+    it "should have a method to fetch option names and values" do
+      lambda { @optionable.options_values_struct }.should_not raise_error(NoMethodError)
+    end
+    
+    it "should return an object that lets us retreive values by calling a method named for the option" do
+      option_values = @optionable.options_values_struct
+      option_values.foo.should == "FOOFOO"
+      option_values.bar.should == "BARBAR"
+    end
+    
+    it "should contain both set and default options" do
+      @optionable.instance_specified_options = @options_template
+      @optionable.set_option("example_option", 99)
+      option_values = @optionable.options_values_struct
+      option_values.foo.should == "FOOFOO"
+      option_values.fizz.should == "FIZZFIZZ"
+      option_values.example_option.should == 99
+    end
+  end
 end

data/spec/spec.opts

@@ -0,0 +1,5 @@
+--colour
+--format progress
+--loadby mtime
+--reverse
+--drb

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 0
-  - 0
-  version: 0.0.0
+  - 1
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Brendon Murphy
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-22 00:00:00 -07:00
+date: 2010-04-23 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -25,10 +25,10 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
 - MIT-LICENSE
-- README
+- README.rdoc
 - Rakefile
 - VERSION
 - lib/acts-as-optionable.rb
@@ -38,6 +38,7 @@ files:
 - lib/acts_as_optionable/specify_option.rb
 - rails/init.rb
 - spec/acts_as_optionable_spec.rb
+- spec/spec.opts
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/bemurphy/acts_as_optionable

data/README

@@ -1,13 +0,0 @@
-ActsAsOptionable
-================
-
-I don't recommend using this yet since I'm going to make a couple core changes shortly.  Very alpha.
-
-
-Example
-=======
-
-Example goes here.
-
-
-Copyright (c) 2010 [name of plugin creator], released under the MIT license