settingcrazy 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rvmrc

@@ -0,0 +1 @@
+rvm use 1.9.3@settingcrazy --create

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in settingcrazy.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Dan Draper
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,245 @@
+# Settingcrazy
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'settingcrazy'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install settingcrazy
+
+Finally, create a migration and run:
+
+    $ rails g settingcrazy:setting_values_migration
+    $ rake db:migrate
+
+## Usage
+
+To use simply include the SettingCrazy module in any ActiveRecord model that you want to have settings:
+
+    class User < ActiveRecord::Base
+      include SettingCrazy
+    end
+
+Your model will now have a settings method which you can use to get and set values.
+
+    user = User.first
+    user.settings => {}
+    user.settings.my_setting = "foo"
+    user.settings.my_setting => "foo"
+    user.settings => { "my_setting" => "foo" }
+
+To persist, call save or save! on the parent. Eg;
+
+    user.save
+
+### Serializable Values
+
+TODO
+
+### Setting Inheritance
+
+Your settings can inherit from the settings of a parent.
+
+    class House < ActiveRecord::Base
+      include SettingCrazy
+      has_many :rooms
+    end
+
+    class Room < ActiveRecord::Base
+      include SettingCrazy
+      belongs_to :house
+      settings_inherit_via :house
+    end
+
+    house = House.create(...)
+    house.settings.color = "blue"
+    house.save!
+
+    room = house.rooms.create
+    room.settings.color => "blue"
+
+### Setting Templates
+
+Available settings are specified through the use of setting templates. These tell settingcrazy the options that exist, and what possible values they can take.
+
+    class House < ActiveRecord::Base
+      include SettingCrazy
+      has_many :rooms
+      use_setting_template Settings::House
+    end
+
+use_setting_template can also be passed a block, in case your model needs to use different templates, depending on the record itself.
+
+    class Room < ActiveRecord::Base
+      include SettingCrazy
+      belongs_to :house
+      settings_inherit_via :house
+
+      # Use the template associated with the room type of this room
+      use_setting_template do |record|
+        record.room_type.template
+      end
+    end
+
+####Enums
+
+The template itself is a collection of enums. Any attempt to get or set a setting that is not defined in a template will result in an ActiveRecord::UnknownAttributeError.
+The basic structure of an enum is:
+
+    enum :key, 'name', validation_options do
+      value 'value', 'key'
+      ...
+    end
+
+    class Settings::House < SettingCrazy::Template::Base
+      enum :bedroom_count, 'Room Count', {} do
+        value 1, 'One'
+        value 2, 'Two'
+        value 3, 'Three'
+      end
+    end
+
+    house = House.create(...)
+    house.settings.bedroom_count => nil
+    house.settings.bedroom_count = 1
+    house.save!
+
+####Validation
+
+Note: Validation does not work with namespaces yet.
+
+Settingcrazy always validates whether the value for an option is defined in the enums. There are a number of additional validation options available.
+
+    multiple (boolean) - Whether it is valid to save more than one entry for a single key
+    required (boolean) - Whether a value must be set for this enum
+    dependent ({ enum_key: setting_value }) - A value may only be set for this option if all of the options it is dependent on are set to the specified values
+    type (string) - Only current available value is 'text'. This causes settingcrazy to skip the range validation, so any value for this option will be valid.
+
+    class Settings::House < SettingCrazy::Template::Base
+      enum :is_furnished, 'Furnished', { multiple: false, required: true } do
+        value false, 'Not Furnished'
+        value true, 'Is Furnished'
+      end
+
+      enum :has_dining_table, 'Has Dining Table', { dependent: { is_furnished: true } } do
+        value false, 'No Dining Table'
+        value true, 'Dining Table'
+      end
+    end
+
+    house = House.create(...)
+    house.valid? => false
+    house.errors => { :is_furnished => ["Setting, 'Furnished', is required"] }
+    house.settings.is_furnished = false
+    house.valid? => true
+    house.settings.has_dining_table = false
+    house.valid? => false ("'Has Dining Table' can only be specified if 'Furnished' is set to 'Not Furnished'")
+    house.settings.is_furnished = true
+    house.valid? => true
+    house.settings.has_dining_table = 3
+    house.valid? => false ("'3' is not a valid setting for 'Has Dining Table'")
+
+
+#####Defaults
+
+Defaults enable both the ability to ensure the user starts with a valid object, and  that the most common values are set on creation. To define defaults, create a class method in your template that returns a hash of default settings.
+
+    class Settings::House < SettingCrazy::Template::Base
+      # Assuming the enums for all these settings are defined below
+      def self.defaults
+        {
+          bedroom_count: 2,
+          is_furnished: false
+        }
+      end
+    end
+
+    house = House.create(...)
+    house.settings => {}
+    house.settings.bedroom_count => 2
+    house.settings.bedroom_count = 3
+    house.settings => { :bedroom_count => 3 }
+    house.is_furnished => false
+    house.has_dining_table => nil
+
+### Mass Assignment and Usage in Forms
+
+You can easily bulk set settings using a hash.
+
+    house.settings = { :foo => "bar", :fruit => "apple" }
+
+This extends to mass assignment:
+
+    house.attributes = {
+      :settings => { :foo => "bar", :fruit => "apple" }
+    }
+
+If using in a form you can use fields for (eg in Haml):
+
+    = form.fields_for :settings, @house.settings do |setting|
+      = setting.text_field :foo
+
+### Setting Namespaces
+
+If you have a model that needs settings to be divided in some way (perhaps by functional area) you can use a namespace.
+
+    class Scenario < ActiveRecord::Base
+      include SettingCrazy
+
+      setting_namespace :weekdays
+      setting_namespace :weekends
+    end
+
+Now you can access your settings like so:
+
+    scenario = Scenario.find(...)
+    scenario.settings.weekends.foo = "bar"
+    scenario.settings.weekends.foo => "bar"
+    scenario.settings.weekdays.foo => nil
+
+    scenario.settings.weekends => { :foo => "bar" }
+
+Not providing a namespace still works and will access all settings:
+
+    scenario.settings.foo => "bar"
+
+Setting namespaces work with bulk setting and mass assignment too:
+
+    scenario.settings.weekends = { :foo => "bar" }
+
+    scenario.attributes = {
+      :settings => {
+        :weekends => {
+          :foo => "bar
+        },
+      },
+    }
+
+You can also set templates to work per namespace:
+
+    setting_namespace :weekdays, :template => WeekDayTemplate
+
+When inheriting via a parent with namespaces you may like to specify a namespace to inherit from instead of just the settings as a whole.
+
+    settings_inherit_via :house, :namespace => :a_namespace
+
+Or, you can even use a proc
+
+    settings_inherit_via :house, :namespace => Proc.new { |room| room.parent_setting_namespace }
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/TODO

@@ -0,0 +1,10 @@
+* think some more about saving and record consistency. Settings don't get saved until we save the parent record. That may be OK but calling a getter should perhaps return the correct (albeit unsaved) value?
+  - implement new_record? changed? (maybe even changes) methods
+  - active record makes this hard to do in current form. We would actually need to build a second setting value when we change something and then replace the entire collection when we save the owner
+* RDoc
+* Serialize only for arrays (reject blanks too) - may need to add a serialize column
+* Template Validators
+* Template docs
+* More validations in validator
+ - an enum_value is only available if another enum_value matches certain criteria, e.g, delivery_method can be set to 'ACCELERATED' only if bid_setting is 'manualCPC'
+ - validates format, e.g daily_budget and initial_key_cpc can only be decimals

data/lib/generators/settingcrazy/setting_values_migration/setting_values_migration_generator.rb

@@ -0,0 +1,18 @@
+require 'rails'
+
+module Settingcrazy
+  module Generators
+    class SettingValuesMigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      source_root File.expand_path('../../../../../lib/generators/settingcrazy/setting_values_migration/templates/', __FILE__)
+
+      def self.next_migration_number(path)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def create_setting_values_migration_file
+        migration_template 'migration.rb', 'db/migrate/create_settings_values'
+      end
+    end
+  end
+end

data/lib/generators/settingcrazy/setting_values_migration/templates/migration.rb

@@ -0,0 +1,15 @@
+class CreateSettingsValues < ActiveRecord::Migration
+  def self.up
+    create_table :setting_values do |t|
+      t.string :value
+      t.string :key
+      t.string :namespace
+      t.references :settable, :polymorphic => true
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :setting_values
+  end
+end

data/lib/settingcrazy.rb

@@ -0,0 +1,23 @@
+autoload :ActiveRecord, 'active_record'
+
+require "settingcrazy/version"
+require "settingcrazy/namespace"
+require "settingcrazy/settings_proxy"
+require "settingcrazy/namespaced_settings_proxy"
+require "settingcrazy/setting_value"
+require "settingcrazy/class_methods"
+require "settingcrazy/instance_methods"
+require "settingcrazy/inheritor"
+require "settingcrazy/template"
+require "settingcrazy/settings_validator"
+
+module SettingCrazy
+  def self.included(base)
+    base.class_eval <<-EVAL
+      has_many :setting_values, :class_name => "SettingCrazy::SettingValue", :as => :settable, :autosave => true
+      validates_with SettingsValidator
+    EVAL
+    base.extend ClassMethods
+    base.send(:include, InstanceMethods)
+  end
+end

data/lib/settingcrazy/class_methods.rb

@@ -0,0 +1,32 @@
+module SettingCrazy
+  module ClassMethods
+    def use_setting_template(template = nil, &block)
+      @template = template || block
+    end
+
+    def settings_inherit_via(reflection, options = {})
+      @inheritor = Inheritor.new(reflection, options)
+    end
+
+    def setting_namespace(name, options = {})
+      @setting_namespaces ||= {}
+      @setting_namespaces[name.to_sym] = Namespace.new(name, options)
+    end
+
+    def _inheritor
+      @inheritor
+    end
+
+    def _setting_namespaces
+      @setting_namespaces
+    end
+
+    def setting_template(record)
+      case @template
+        when String  then @template.constantize
+        when Class   then @template
+        when Proc    then @template.call(record)
+      end
+    end
+  end
+end

data/lib/settingcrazy/inheritor.rb

@@ -0,0 +1,31 @@
+
+module SettingCrazy
+  class Inheritor
+    def initialize(via, options = {})
+      # TODO: Do a reflection look up to make sure its valid
+      @via              = via
+      @parent_namespace = options[:namespace]
+    end
+
+    # Returns the appropriate parent settings
+    def parent_settings_for(model)
+      return nil if model.send(@via).blank?
+      association = model.send(@via)
+      if pn = parent_namespace(model)
+        association.settings.send(pn)
+      else
+        association.settings
+      end
+    end
+
+    protected
+      def parent_namespace(model)
+        case @parent_namespace
+          when nil then nil
+          when String, Symbol then @parent_namespace
+          when Proc
+            @parent_namespace.call(model)
+        end
+      end
+  end
+end

data/lib/settingcrazy/instance_methods.rb

@@ -0,0 +1,20 @@
+
+module SettingCrazy
+  module InstanceMethods
+    def assign_attributes(values, options = {})
+      if values.has_key?(:settings)
+        self.settings = values.delete(:settings)
+      end
+
+      super(values, options)
+    end
+
+    def settings
+      @settings ||= SettingsProxy.new(self, self.class.setting_template(self))
+    end
+
+    def settings=(attributes)
+      settings.bulk_assign(attributes)
+    end
+  end
+end