has_setting 0.5 → 0.6

data/{README → README.md}

@@ -1,78 +1,72 @@
-==What is it?
+(This is now the official repository for the Simplificator [has_setting gem](https://github.com/simplificator/has_setting))
+
+# What is it?
+
 has_setting is a simple extension that enables ActiveRecord models to
-store settings in a separate settings table as key/value pairs where the key and value are stored as Strings.
+store settings in a separate settings table as key/value pairs where the key and value are stored as strings.
 
-==History
- * 0.4.3:
-   * Changed behaviour of :boolean formatters: Now they treat '0', 0, false, nil and '' as false, everything else as true
-     This is not the same behaviour as ruby (treating only nil and false as false) but should help with input from web forms (i.e. checkboxes)
-     If you want strict ruby boolean behaviour, then use :strict_boolean as :type
- * 0.4.2:
-   * bug fixes for boolean types default values
- * 0.3.10:
-   * added boolean and booleans formatters
- * 0.3.9:
-   * added type :strings, :floats, :ints. They store the contents of an array as a comma separated string. 
- * 0.3.8:
-   * added dependent destroy option. no more zombie settings lingering around.
- * 0.3.7: 
-   * Gem is now built using jeweler... after messing around and bumping versions and getting 
-     strange errors, this is 'it works' feeling coming back
- * 0.3.4: 
-   * Added custom formatter support. no new formatters though...
- * 0.3.1: 
-   * Bug Fixed: has_many(:settings) is not added to ActiveRecord::Base but only to the classes with has_setting
-   * Bug Fixed: options are not shared between classes
-   * Again changed the way settings are saved. Save is now done on parent.save with an after_save callback. (like this the settings are treated as if they were attributes of the owner)
- * 0.2.x: 
-   * Added :default option
-   * changed way settings are saved so that unsaved parents can have settings too
-   * changed nameing scheme of setting names (incompatible with versions prior 0.2.x but since nobody uses the gem i dont care :-))
- * 0.1.x: First Version
 
+# Installation
+
+Add has_setting to your gemfile:
 
-==Installation
-sudo gem install simplificator-has_setting
+    gem 'has_setting'
+
+# Setup
 
-==Setup
  * Add a migration that looks more or less like the one in <em>help/001_create_settings.rb</em>
  * Make sure the gem is loaded when your application starts
 
-==Config
+# Config
+
 The model you want to hold settings (i.e. User, Profile, ...):
-<tt>has_setting(:name_of_the_setting)</tt>
+
+    has_setting(:name_of_the_setting)
+
 This will create the following methods for you on the owner class:
- * <tt>name_of_the_setting=(value)</tt> a standard setter
- * <tt>name_of_the_setting()</tt> a standard getter (the getter method takes an optional hash to override some options, possible values are the same as the options in has_setting())
+ * `name_of_the_setting=(value)` a standard setter
+ * `name_of_the_setting()` a standard getter (the getter method takes an optional hash to override some options, possible values are the same as the options in has_setting())
  
-<tt>has_setting(name, options)</tt> takes an optional hash of options. Following options are supported:
-<em>:type</em> allows you to convert the value:
-  * <em>:string</em> (default) Uses the StringFormatter to convert from/to String (actually this formatter just leaves the value as it is)
-  * <em>:int</em> Uses the IntFormatter to convert from/to int values.
-  * <em>:boolean</em> Uses the BooleanFormatter to convert from/to boolean values; treating 0, '0', false, '' and nil as false.
-  * <em>:strict_boolean</em> Uses the StrictBooleanFormatter to convert from/to boolean values; treating false, and nil as false.
-  * <em>:float</em> Uses the FloatFormatter to convert from/to float values.
-  * <em>:ints</em> Uses the IntsFormatter to convert from/to int[]
-  * <em>:floats</em> Uses the FloatsFormatter to convert from/to float[]
-  * <em>:strings</em> Uses the StringsFormatter to convert from/to string[]
-  * <em>:booleans</em> Uses the BooleansFormatter to convert from/to boolean[]
-  * <em>:strict_booleans</em> Uses the BooleansFormatter to convert from/to boolean[]
-<em>:default</em> allows you to specify a default value that will be returned if the setting does not exist (i.e. has never been written). Note that the default value is _ignored_ if the setting exists, no matter what the value of the setting is. The default value is returned as is, no type conversion takes place.
-
-
-
-==How it works
+`has_setting(name, options)` takes an optional hash of options. Following options are supported:
+
+*:type* allows you to convert the value:
+
+  * *:string* (default) Uses the StringFormatter to convert from/to String (actually this formatter just leaves the value as it is)
+  * *:int* Uses the IntFormatter to convert from/to int values.
+  * *:boolean* Uses the BooleanFormatter to convert from/to boolean values; treating 0, '0', false, '' and nil as false.
+  * *:strict_boolean* Uses the StrictBooleanFormatter to convert from/to boolean values; treating false, and nil as false.
+  * *:float* Uses the FloatFormatter to convert from/to float values.
+  * *:ints* Uses the IntsFormatter to convert from/to int[]
+  * *:floats* Uses the FloatsFormatter to convert from/to float[]
+  * *:strings* Uses the StringsFormatter to convert from/to string[]
+  * *:booleans* Uses the BooleansFormatter to convert from/to boolean[]
+  * *:strict_booleans* Uses the BooleansFormatter to convert from/to boolean[]
+  * *:default* allows you to specify a default value that will be returned if the setting does not exist (i.e. has never been written). Note that the default value is _ignored_ if the setting exists, no matter what the value of the setting is. The default value is returned as is, no type conversion takes place.
+
+
+
+# How it works
+
 A polymorphic parent-child relation is created between Setting and the parent/owning class.
 Getters/setters are added through meta-programming-magic. If the setter is invoked on a unsafed parent then the setting is not saved until the parent is saved, else setting is saved upon creation (i.e. first time the setter is called) / change (subsequent calls).
 The getters/setters can be used in standard AR validations, Rails mass assignments/form helpers and so on.
 
-==Gotchas
+
+# Locale Awareness
+
+has_setting has basic locale awareness. So when getting a setting, has_setting looks for the setting with the current locale. If it doesn't find it, it just grabs the first setting it finds, ignoring the locale.
+When setting a setting, has_setting will look if a setting exists with the current locale and if not create a new settings record for the current locale.
+
+
+# Gotchas
+
  * Values are stored as Strings in the DB. Values are converted with one of the formatters (depending on selected :type). If you try to store an unsupported type or anything other than the type you selected there might be an exception (i.e. if you try to store "foobar" as an :type => :int)
  * Currently there are no length validations on the 'name' and 'value' column of Setting. Take care not to store values to big. Especially when using the array formatters (:floats, :ints, :strings)
  
  
-==Example
-<code>
+# Example
+
+```
 class Foo < ActiveRecord::Base
   has_setting(:string_setting)
   has_setting(:another_string_setting, :type => :string)
@@ -101,12 +95,43 @@ foo.float_setting
 foo.float_setting = nil
 foo.float_setting
 => nil
-
-</code>
+```
 
    
-==Todo
+# Todo
+
 has_setting should stay as simple as possible... still some ideas are around:
  * Custom formatter (to convert arbitrary objects, i.e. Date/Time/DateTime...)
  * Add validation options
 
+# History
+
+ * 0.5:
+   * Added basic locale awareness. If you update from a previous version, you need to add a locale column to the settings table.
+ * 0.4.3:
+   * Changed behaviour of :boolean formatters: Now they treat '0', 0, false, nil and '' as false, everything else as true
+     This is not the same behaviour as ruby (treating only nil and false as false) but should help with input from web forms (i.e. checkboxes)
+     If you want strict ruby boolean behaviour, then use :strict_boolean as :type
+ * 0.4.2:
+   * bug fixes for boolean types default values
+ * 0.3.10:
+   * added boolean and booleans formatters
+ * 0.3.9:
+   * added type :strings, :floats, :ints. They store the contents of an array as a comma separated string. 
+ * 0.3.8:
+   * added dependent destroy option. no more zombie settings lingering around.
+ * 0.3.7: 
+   * Gem is now built using jeweler... after messing around and bumping versions and getting 
+     strange errors, this is 'it works' feeling coming back
+ * 0.3.4: 
+   * Added custom formatter support. no new formatters though...
+ * 0.3.1: 
+   * Bug Fixed: has_many(:settings) is not added to ActiveRecord::Base but only to the classes with has_setting
+   * Bug Fixed: options are not shared between classes
+   * Again changed the way settings are saved. Save is now done on parent.save with an after_save callback. (like this the settings are treated as if they were attributes of the owner)
+ * 0.2.x: 
+   * Added :default option
+   * changed way settings are saved so that unsaved parents can have settings too
+   * changed nameing scheme of setting names (incompatible with versions prior 0.2.x but since nobody uses the gem i dont care :-))
+ * 0.1.x: First Version
+

data/lib/has_setting/ar_extensions.rb

@@ -11,7 +11,7 @@ module HasSetting
       self.class_eval do
         unless @has_setting_options # define only once
           # AR association to settings
-          has_many( :settings, :as => :owner, :class_name => 'HasSetting::Setting', 
+          has_many( :settings, :as => :owner, :class_name => 'HasSetting::Setting',
                     :foreign_key => :owner_id, :dependent => :destroy)
           after_save(:save_has_setting_association)
           @has_setting_options = {}
@@ -33,8 +33,7 @@ module HasSetting
 
       # default options
       type = options[:type] || :string    # treat as string
-        # default could be false, thats why we use has_key?
-      default = options[:default] || (options.has_key?(:default) ? options[:default] : nil) # no default
+      options[:localize] ||= false
       self.has_setting_options[name] = options
 
       # setter
@@ -46,8 +45,8 @@ module HasSetting
       # getter
       define_method(name) do |*args|
         setting = read_setting(name)
-        options = args.first || self.class.has_setting_options[name]
-        return options[:default] if setting.nil? 
+        options = args.first || has_setting_option(name)
+        return options[:default] if setting.nil?
         formatter = Formatters.for_type(options[:type] || type)
         formatter.to_type(setting.value)
       end
@@ -56,16 +55,36 @@ module HasSetting
 
   def write_setting(name, value)
     # find an existing setting or build a new one
-    setting = self.settings.detect() {|item| item.name == name and item.locale.to_s == I18n.locale.to_s }
-    setting = self.settings.build(:name => name, locale: I18n.locale.to_s) if setting.blank?
+    locale = localize?(name) ? I18n.locale : nil
+    setting = self.settings.detect() {|item| item.name == name and item.locale.to_s == locale.to_s }
+    setting = self.settings.build(:name => name, locale: locale) if setting.blank?
     setting.value = value
   end
 
   def read_setting(name)
-    # use detect instead of SQL find. like this the 'cached' has_many-collection is inited 
+    # use detect instead of SQL find. like this the 'cached' has_many-collection is inited
     # only once
-    s = self.settings.detect() {|item| item.name == name and item.locale.to_s == I18n.locale.to_s} # first see if there is a setting with current locale
+    locale = localize?(name) ? I18n.locale.to_s : nil
+    s = self.settings.detect() {|item| item.name == name and item.locale.to_s == locale} # first see if there is a setting with current locale
     s ||= self.settings.detect() {|item| item.name == name} # then if not found, take the first setting with matching name (TODO: add locale fallbacks)
     s
   end
+
+  def localize? name
+    options = has_setting_option name
+    options ? options[:localize] : false
+  end
+
+  def has_setting_option name
+    klass = self.class
+    option = klass.has_setting_options ? klass.has_setting_options[name] : nil
+    while option.nil? and
+          klass.superclass != ActiveRecord::Base and
+          klass.superclass.respond_to?(:has_setting_options)
+      klass = klass.superclass
+      option = klass.has_setting_options[name]
+    end
+    option
+  end
+
 end

data/lib/has_setting/version.rb

@@ -1,3 +1,3 @@
 module HasSetting
-  VERSION = "0.5"
+  VERSION = "0.6"
 end

data/test/bar.rb

@@ -1,4 +1,4 @@
 class Bar < ActiveRecord::Base
-  has_setting(:setting_1)
+  has_setting(:setting_1, localize: true)
   has_setting(:setting_2, :type => :int)
 end

data/test/test_helper.rb

@@ -5,9 +5,9 @@ require 'test/unit'
 require File.dirname(__FILE__) + '/../lib/has_setting'
 
 
-ActiveRecord::Base.establish_connection(  
-  :adapter  => 'sqlite3',   
-  :database => 'test.sqlite3',   
+ActiveRecord::Base.establish_connection(
+  :adapter  => 'sqlite3',
+  :database => 'test.sqlite3',
   :timeout => 5000
 )
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: has_setting
 version: !ruby/object:Gem::Version
-  version: '0.5'
+  version: '0.6'
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-10 00:00:00.000000000 Z
+date: 2013-06-07 00:00:00.000000000 Z
 dependencies: []
 description: Stores settings as key/value pairs in a settings table and provides accessors
   for them on the owning object
@@ -22,11 +22,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- README
+- README.md
 - Rakefile
 - VERSION.yml
 - has_setting.gemspec
 - help/001_create_settings.rb
+- lib/.DS_Store
 - lib/has_setting.rb
 - lib/has_setting/ar_extensions.rb
 - lib/has_setting/formatters.rb
@@ -59,7 +60,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: Simple setting extension to AR