delayed_form_observer 0.1.0 → 0.2.0

data/.specification

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: delayed_form_observer
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Coroutine
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-29 00:00:00 -05:00
+date: 2010-07-30 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,19 +52,18 @@ dependencies:
         version: 2.3.4
   type: :development
   version_requirements: *id002
-description: Delayed Form Observer provides Rails with timed form observers that do not create race conditions.
+description: Delayed Form Observer provides Rails with timed form observers that do not create race conditions. The gem extends Prototype and adds a Rails PrototypeHelper to use this new object.
 email: gems@coroutine.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
 - .gitignore
 - .specification
 - MIT-LICENSE
-- README
 - Rakefile
 - VERSION
 - delayed_form_observer.gemspec
@@ -76,8 +75,9 @@ files:
 - lib/generators/delayed_form_observer/delayed_form_observer_generator.rb
 - lib/generators/delayed_form_observer/templates/prototype_extension.js
 - rails/init.rb
-- test/delayed_form_observer_test.rb
+- test/delayed_form_observer/helpers_test.rb
 - test/test_helper.rb
+- README.rdoc
 has_rdoc: true
 homepage: http://github.com/coroutine/delayed_form_observer
 licenses: []
@@ -113,6 +113,6 @@ signing_key:
 specification_version: 3
 summary: Delayed Form Observer provides Rails with timed form observers that do not create race conditions.
 test_files: 
-- test/delayed_form_observer_test.rb
+- test/delayed_form_observer/helpers_test.rb
 - test/test_helper.rb
 

data/README.rdoc

@@ -0,0 +1,110 @@
+= Delayed Form Observer
+
+Delayed Form Observer eliminates a race condition in a common Rails search implementation.
+
+Large lists are often made more manageable by positioning a search textbox above the list 
+and attaching a Prototype timed observer to the textbox.  A javascript object is checking 
+the textbox for changes and remotely submitting the search form every so many milliseconds.
+The user experiences this as a list whose items change with every keystroke.
+
+The pattern works fine as long as the search query is working against a simple dataset. The
+asynchronous requests come back in the same order they are sent.
+
+But if the dataset is not simple, search #1 might return *after* search #2.  A user who types
+in "J" then "o" initiates two searches against a list of contacts.  "J" matches both Jim and
+John; "Jo" only matches John.  But since it is easier for the database to return fewer records,
+what if we get [John] before we get [Jim,John]?  The textbox will show "Jo" but the list will
+show Jim and John.  Oops.
+
+
+== A Gap in Prototype
+
+The problem exists primarily because Prototype only offers two basic kinds of observers: timed 
+observers and event-driven observers.  
+
+We've already explained the issue with the timed observer.
+
+Event-driven observers don't result in race conditions but they cause far too many search 
+requests. Every keystroke would result in a query.
+
+What we want is an event-driven observer with a delay before the request is made.  If a new 
+event arrives during the delay window, the previous event is abandoned and delay counter is 
+reset.
+
+Allow me to introduce you to Delayed Form Observer.
+
+
+== Usage
+
+The generator that comes with this gem adds the required Prototype extension to your application's 
+public javascripts directory. It also adds an ActionView Prototype helper for creating a form 
+observer that uses this new Prototype object.
+
+The helper uses the same arguments as <tt>observe_form</tt>.
+
+    # Observe changes to the search form
+    <%= delayed_observe_form 	"MySearchForm", :url => { :action => :index }, :method => :get, :frequency => 0.5
+
+
+If you need more help than that, maybe you should just look at the source code.  There are a ton of comments 
+in there.
+
+
+
+== Helpful Links
+
+* <b>Repository:</b> http://github.com/coroutine/delayed_form_observer
+* <b>Gem:</b> http://rubygems.org/gems/delayed_form_observer
+* <b>Authors:</b> http://coroutine.com
+
+
+
+== Prerequisites
+
+As you might have guessed, a gem that extends Prototype requires Prototype.  
+
+But since the gem was designed as a Rails extension, chances are Prototype 
+is already included.
+
+* <b>Prototype:</b> http://prototypejs.org
+
+
+
+== Installation & Generators
+
+Install as a gem from RubyGems.org and add a gem dependency in the appropriate file.
+
+	$ gem install delayed_form_observer
+
+Or install as a plugin.
+
+	$ script/plugin install git://github.com/coroutine/delayed_form_observer.git
+
+Either way, then generate the required javascript file.
+
+	$ script/generate delayed_form_observer
+	
+
+
+== License
+
+Copyright (c) 2010 {Coroutine LLC}[http://coroutine.com].
+
+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/Rakefile

@@ -29,7 +29,7 @@ end
 begin
   Jeweler::Tasks.new do |gemspec|
     gemspec.authors           = ["Coroutine", "Tim Lowrimore", "John Dugan"]
-    gemspec.description       = "Delayed Form Observer provides Rails with timed form observers that do not create race conditions."
+    gemspec.description       = "Delayed Form Observer provides Rails with timed form observers that do not create race conditions. The gem extends Prototype and adds a Rails PrototypeHelper to use this new object."
     gemspec.email             = "gems@coroutine.com"
     gemspec.homepage          = "http://github.com/coroutine/delayed_form_observer"
     gemspec.name              = "delayed_form_observer"
@@ -39,7 +39,7 @@ begin
     gemspec.add_development_dependency("activesupport", ">=2.3.4")
     
     gemspec.files.include("generators/**/*", "lib/**/*")
-    gemspec.files.include("test/**/*.rb")
+    gemspec.files.include("test/**/*")
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/delayed_form_observer.gemspec

@@ -5,21 +5,20 @@
 
 Gem::Specification.new do |s|
   s.name = %q{delayed_form_observer}
-  s.version = "0.1.0"
+  s.version = "0.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Coroutine", "Tim Lowrimore", "John Dugan"]
-  s.date = %q{2010-07-29}
-  s.description = %q{Delayed Form Observer provides Rails with timed form observers that do not create race conditions.}
+  s.date = %q{2010-07-30}
+  s.description = %q{Delayed Form Observer provides Rails with timed form observers that do not create race conditions. The gem extends Prototype and adds a Rails PrototypeHelper to use this new object.}
   s.email = %q{gems@coroutine.com}
   s.extra_rdoc_files = [
-    "README"
+    "README.rdoc"
   ]
   s.files = [
     ".gitignore",
      ".specification",
      "MIT-LICENSE",
-     "README",
      "Rakefile",
      "VERSION",
      "delayed_form_observer.gemspec",
@@ -28,6 +27,8 @@ Gem::Specification.new do |s|
      "init.rb",
      "lib/delayed_form_observer.rb",
      "lib/delayed_form_observer/helpers.rb",
+     "lib/generators/delayed_form_observer/delayed_form_observer_generator.rb",
+     "lib/generators/delayed_form_observer/templates/prototype_extension.js",
      "rails/init.rb",
      "test/delayed_form_observer/helpers_test.rb",
      "test/test_helper.rb"

data/lib/generators/delayed_form_observer/delayed_form_observer_generator.rb

@@ -0,0 +1,20 @@
+require "rails/generators"
+
+
+class DelayedFormObserverGenerator < Rails::Generators::Base
+
+  # This call establishes the path to the templates directory.
+  #
+  def self.source_root 
+    File.join(File.dirname(__FILE__), "templates")
+  end
+
+
+  # This method copies javascript files to the corresponding 
+  # public directories.
+  #
+  def generate_assets
+    copy_file "prototype_extension.js", "public/javascripts/prototype_delayed_form_observer.js"
+  end
+  
+end

data/lib/generators/delayed_form_observer/templates/prototype_extension.js

@@ -0,0 +1,20 @@
+Form.DelayedObserver = Class.create(Form.Observer, {
+    initialize: function($super, element, frequency, callback) {
+        $super(element, frequency, callback);
+        this.invocationPending = false;
+    },
+    
+    // Overrides Abstract.TimedObserver.execute
+    execute: function() {
+        var value = this.getValue();
+        if (Object.isString(this.lastValue) && Object.isString(value) ?
+                this.lastValue != value : String(this.lastValue) != String(value)) {
+            this.lastValue = value;
+            this.invocationPending = true;
+        } else if(this.invocationPending) {
+            this.invocationPending = false;
+            this.callback(this.element, value);
+            this.lastValue = value;
+        }
+    }
+});

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: delayed_form_observer
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Coroutine
@@ -17,7 +17,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-29 00:00:00 -05:00
+date: 2010-07-30 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -52,19 +52,18 @@ dependencies:
         version: 2.3.4
   type: :development
   version_requirements: *id002
-description: Delayed Form Observer provides Rails with timed form observers that do not create race conditions.
+description: Delayed Form Observer provides Rails with timed form observers that do not create race conditions. The gem extends Prototype and adds a Rails PrototypeHelper to use this new object.
 email: gems@coroutine.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- README
+- README.rdoc
 files: 
 - .gitignore
 - .specification
 - MIT-LICENSE
-- README
 - Rakefile
 - VERSION
 - delayed_form_observer.gemspec
@@ -73,9 +72,12 @@ files:
 - init.rb
 - lib/delayed_form_observer.rb
 - lib/delayed_form_observer/helpers.rb
+- lib/generators/delayed_form_observer/delayed_form_observer_generator.rb
+- lib/generators/delayed_form_observer/templates/prototype_extension.js
 - rails/init.rb
 - test/delayed_form_observer/helpers_test.rb
 - test/test_helper.rb
+- README.rdoc
 has_rdoc: true
 homepage: http://github.com/coroutine/delayed_form_observer
 licenses: []

data/README

@@ -1,13 +0,0 @@
-DelayedFormObserver
-===================
-
-Introduction goes here.
-
-
-Example
-=======
-
-Example goes here.
-
-
-Copyright (c) 2010 [name of plugin creator], released under the MIT license