opal-shimmer 0.1.2 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0464c42ab04492cc79b6fb4c626c6e9a7307eed9
-  data.tar.gz: 38d9ae5fe114dd33f1bde76bef21aefaf2bc96f7
+  metadata.gz: a1694f4e3a2e7065aa4b9fd21f3769dd112299ea
+  data.tar.gz: 769bb63b91b60ae4d167b8031376d5e40e71e0ce
 SHA512:
-  metadata.gz: 9dbfb8a69b88e8ce27d461c749417d7c73caaa1f561a9a4f53a6d70b91971feb94ee079ecf3348039b2b8f696ce6f3cb4eb03b96524a7e9f1ae85f0d2cffcbc1
-  data.tar.gz: fcc50acbc94b4f2a36de3e76909670c02a56467abacd16c1d0134e17aa974ed9ce7fd4243a07365e11b1047f76a9765ab6b1b66004d01fc4188745368c60f938
+  metadata.gz: 52ce8189f854edf7004589847e62b8ae47bfc094cf0b007707921b9779f5295bc85a7361692eec795aa18368f4dd5219e011d0cd64f32a22fed4f8b4586c57f8
+  data.tar.gz: b7023a2ff7b7f6073bfa8b900b706a52b4e8359caf7345b282d7a29317f14cc4dbd238db025e717c8c1f1694775659691041490c64df870a76ea347178495057

data/README.md

@@ -20,52 +20,93 @@ Or install it yourself as:
 
 Shimmer is very easy to use right out of the box. I'm assuming you'll be using it within the context of a Rails application for this tutorial. Make sure you add `//= require shimmer` to your application.js manifest file.
 
-    # Set up the config object:
-    config = Shimmer::Config.new
-    
-    # Set some values:
-    config.somevalue = "Wow"
-    config.othervalue = ['This', 'is', 'great!']
-    
-    # Get some values:
-    puts config.somevalue  # > "Wow"
-    
-    # Use namespaces to define very specific values:
-    config.several.levels.deep.stringvalue = "Your string here"
-    puts config.several.levels.deep.stringvalue  # > "Your string here"
-    
-    # Check whether a value exists:
-    puts config.foo.nil?
-    
-    # Set stuff in a namespace using a block:
-    config.really.deep.namespace do |c|
-      c.value1 = 1
-      c.value2 = 2
-    end
-    
-    # Persist values across sessions using localStorage:
-    config.persist(:cease_and_persist)
-    config.cease_and_persist = "abc123"
-    
-    config2 = Shimmer::Config.new  # this loads up a brand new object
-    config2.persist(:cease_and_persist)
-    
-    puts config2.cease_and_persist  # > "abc123"  Aha! it works!
-    
-    # An easier way to persist values by setting initial defaults
-    # and not overwriting values that get set differently later:
-    config.persist_defaults do |c|
-      c.somevalue = "abc"
-      c.othervalue = 123
-    end
-
-    # ...user triggers some action...
-    config.somevalue = "xyz"
-    
-    # ...days later on a subsquent browser session...
-    puts config.somevalue  # > "xyz"  not "abc" - Yay!
+```ruby
+# Set up the config object:
+config = Shimmer::Config.new
+
+# Set some values:
+config.somevalue = "Wow"
+config.othervalue = ['This', 'is', 'great!']
+
+# Get some values:
+puts config.somevalue  # > "Wow"
+
+# Use namespaces to define very specific values:
+config.several.levels.deep.stringvalue = "Your string here"
+puts config.several.levels.deep.stringvalue  # > "Your string here"
+
+# Check whether a value exists:
+puts config.foo.nil?
+
+# Set stuff in a namespace using a block:
+config.really.deep.namespace do |c|
+  c.value1 = 1
+  c.value2 = 2
+end
+```
+
+### Persist values across sessions using the browser's localStorage
+
+Normally when you set and retrieve values in a config object, those values are only stored in-memory, which means when you reload the browser the values are no longer available.
+
+Shimmer provides a `persist` method that allows you to specify that a value key should be stored in localStorage so that it will be automatically available in a later browser session (or even in the same session if you have a different config instance.
+
+```ruby
+# Persist values across sessions using localStorage:
+config.persist(:cease_and_persist)
+config.cease_and_persist = "abc123"
+
+config2 = Shimmer::Config.new  # this loads up a brand new object
+config2.persist(:cease_and_persist)
+
+puts config2.cease_and_persist  # > "abc123"  Aha! it works!
+```
+
+If you want to make sure you don't overwrite previous persisted values by setting default values, there is a `persist_defaults` method available. It creates a special block context where you can set numerous values, and those values will _only_ be set if the values aren't already saved in localStorage. Example:
+
+```ruby
+# An easier way to persist values by setting initial defaults
+# and not overwriting values that get set differently later:
+config.persist_defaults do |c|
+  c.somevalue = "abc"
+  c.othervalue = 123
+end
+
+# ...user triggers some action...
+config.somevalue = "xyz"
+
+# ...days later on a subsquent browser session...
+puts config.somevalue  # > "xyz"  not "abc" - Yay!
+```
+
+### Use Observers to execute code when config values change
+
+Shimmer lets you attach an observer (essentially an event handler) to a config object key. The observer will be notified when the value for that key changes, and will receive both the old and the new values as method arguments. Example:
+
+```ruby
+config = Shimmer::Config.new
+
+oldval = nil
+newval = nil
+
+config.watch do
+  on :somevalue do |new, old|
+    oldval = old
+    newval = new
+  end
+end
+
+config.somevalue = "Totally cool"
+
+puts newval  # > "Totally cool"
+
+config.somevalue = "Another cool thing"
+
+puts newval  # > "Another cool thing"
+puts oldval  # > "Totally cool"
+```
     
-For more examples, look at the `config_spec.rb` and `storage_spec.rb` files in the `spec` folder.
+For more examples, look at the `*_spec.rb` files in the `spec` folder.
 
 ## Contributing
 

data/lib/opal/shimmer/version.rb

@@ -1,5 +1,5 @@
 module Opal
   module Shimmer
-    VERSION = "0.1.2"
+    VERSION = "0.2"
   end
 end

data/opal-shimmer.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |spec|
   spec.name          = "opal-shimmer"
   spec.version       = Opal::Shimmer::VERSION
   spec.authors       = ["Jared White"]
-  spec.email         = ["jared@ealchemylabs.com"]
+  spec.email         = ["jared@jaredwhite.com"]
   spec.description   = %q{An application state and configuration management library built with Opal}
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/jaredcwhite/opal-shimmer"

data/opal/shimmer.rb

@@ -1,4 +1,5 @@
 require 'set'
 require 'json'
 require 'shimmer/storage'
-require 'shimmer/config'
+require 'shimmer/config'
+require 'shimmer/observer'

data/opal/shimmer/config.rb

@@ -9,6 +9,7 @@ module Shimmer
 	    @store = {}
 	    @persisted_storage = Shimmer::Storage.new(self)
 	    @in_persisting_block = false
+	    @observer = Shimmer::Observer.new(self)
 	  end
 	  
 	  def parent_level
@@ -23,19 +24,28 @@ module Shimmer
 
 	    if method_name[-1] == "="
 	      save_key = method_name[0..-2]
+	      
 	      if @in_persisting_block
   	      unless @persisted_storage.should_include?(save_key)
 	          @persisted_storage.should_include(save_key)
 	        end
 	        unless @persisted_storage.include?(save_key)
 	          @persisted_storage.save_value(save_key, args[0])
+	          @observer.call_watcher(save_key, nil, args[0])
+	        else
+	        	@observer.call_watcher(save_key, nil, @persisted_storage.load_value(save_key))
 	        end
 	      elsif !@in_persisting_block and @persisted_storage.should_include?(save_key)
+  	      old_value = @persisted_storage.load_value(save_key)
 	        @store[save_key] = args[0]
 	        @persisted_storage.save_value(save_key, args[0])
+  	      @observer.call_watcher(save_key, old_value, @store[save_key])
 	      else
+  	      old_value = @store[save_key]
 	        @store[save_key] = args[0]
+  	      @observer.call_watcher(save_key, old_value, @store[save_key])
 	      end
+	      
 	    else
 	      if include?(method_name)
 	      	yield @store[method_name] if block
@@ -122,6 +132,15 @@ module Shimmer
 	  def to_h
 	    @store
 	  end
+	  
+	  
+	  ### Observer setup
+	  def watch(&block)
+	    watchdsl = @observer.dsl
+      if block_given?
+        watchdsl.instance_eval(&block)
+      end
+	  end
 	end
 	
 end

data/opal/shimmer/observer.rb

@@ -0,0 +1,36 @@
+module Shimmer
+  class Observer
+    def initialize(config_object)
+      @config_object = config_object
+      @handlers = {}
+      @dsl = DSL.new(self)
+    end
+    
+    def add_watcher(key, block)
+      @handlers[key] = block
+    end
+    
+    def call_watcher(key, old, new)
+      if @handlers[key]
+        @handlers[key].call(new, old, @config_object)
+      end
+    end
+    
+    def dsl
+      @dsl
+    end
+    
+    class DSL
+      def initialize(observer)
+        @observer = observer
+      end
+      def on(key, passed_method=nil, &block)
+        if passed_method
+          @observer.add_watcher(key, passed_method)
+        else
+          @observer.add_watcher(key, block)
+        end
+      end
+    end
+  end
+end

data/spec/observer_spec.rb

@@ -0,0 +1,109 @@
+require 'spec_helper'
+
+class CallbackTest
+  attr_accessor :oldval, :newval
+  def initialize
+    self.oldval = "foo"
+    self.newval = "bar"
+  end
+  def check_values(new, old, value_config)
+    self.oldval = old
+    self.newval = new
+  end
+end
+
+describe "Shimmer::Observer" do
+  let(:config) { config = Shimmer::Config.new }
+  
+  it "can observe stuff" do
+    oldval = "foo"
+    newval = "bar"
+  
+    config.watch do
+      on :somevalue do |new, old|
+        oldval = old
+        newval = new
+      end
+    end
+    
+    config.somevalue = "Totally cool"
+    
+    expect(oldval).to eq(nil)
+    expect(newval).to eq("Totally cool")
+  end
+  it "can continually observe stuff and access other config values" do
+    oldval = "foo"
+    newval = "bar"
+  
+    config.watch do
+      on :somevalue do |new, old, value_config|
+        oldval = "#{value_config.anothervalue} #{old}"
+        newval = "#{new} #{value_config.anothervalue}"
+      end
+    end
+    
+    config.anothervalue = 10
+    config.somevalue = "Totally cool"
+    config.somevalue = 543
+    
+    expect(oldval).to eq("10 Totally cool")
+    expect(newval).to eq("543 10")
+  
+  end
+  it "can call a method of an object as the observer handler" do
+    callback_test = CallbackTest.new
+
+    config.callback_value = "Old stuff"
+  
+    config.watch do
+      on :callback_value, callback_test.method(:check_values)
+    end
+    
+    config.callback_value = "Totally awesome"
+    
+    expect(callback_test.oldval).to eq("Old stuff")
+    expect(callback_test.newval).to eq("Totally awesome")
+  end
+  it "works with persisted items as well" do
+    newval = "foo"
+    oldval = "bar"
+    newsomeval = "foo"
+    oldsomeval = "bar"
+    
+    config.watch do
+      on :somevalue  do |new, old|
+        newsomeval = new
+        oldsomeval = old
+      end
+      on :othervalue do |new, old|
+        newval = new
+        oldval = old
+      end
+    end
+  
+    `window.localStorage.removeItem('config.somevalue')`
+    `window.localStorage.removeItem('config.othervalue')`
+    
+    `window.localStorage['config.othervalue'] = 321`
+  
+    config.persist_defaults do |c|
+      c.somevalue = "abc"
+      c.othervalue = 123
+    end
+
+    expect(oldsomeval).to eq(nil)
+    expect(newsomeval).to eq("abc")
+  
+    expect(oldval).to eq(nil)
+    expect(newval).to eq(321)
+    
+    config.othervalue = 456
+    config.somevalue = "def"
+
+    expect(oldsomeval).to eq("abc")
+    expect(newsomeval).to eq("def")
+
+    expect(oldval).to eq(321)
+    expect(newval).to eq(456)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opal-shimmer
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: '0.2'
 platform: ruby
 authors:
 - Jared White
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-10 00:00:00.000000000 Z
+date: 2015-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -69,7 +69,7 @@ dependencies:
 description: An application state and configuration management library built with
   Opal
 email:
-- jared@ealchemylabs.com
+- jared@jaredwhite.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -87,8 +87,10 @@ files:
 - opal-shimmer.gemspec
 - opal/shimmer.rb
 - opal/shimmer/config.rb
+- opal/shimmer/observer.rb
 - opal/shimmer/storage.rb
 - spec/config_spec.rb
+- spec/observer_spec.rb
 - spec/spec_helper.rb
 - spec/storage_spec.rb
 homepage: https://github.com/jaredcwhite/opal-shimmer
@@ -117,5 +119,6 @@ specification_version: 4
 summary: An application state and configuration management library built with Opal
 test_files:
 - spec/config_spec.rb
+- spec/observer_spec.rb
 - spec/spec_helper.rb
 - spec/storage_spec.rb