sumatra-rails 0.0.4.1 → 0.0.5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sumatra-rails (0.0.4.1)
+    sumatra-rails (0.0.5)
       coffee-rails
       jquery-rails
       rails (~> 3.2)
@@ -44,7 +44,7 @@ GEM
     coffee-script (2.2.0)
       coffee-script-source
       execjs
-    coffee-script-source (1.6.1)
+    coffee-script-source (1.6.2)
     erubis (2.7.0)
     execjs (1.4.0)
       multi_json (~> 1.0)
@@ -55,11 +55,10 @@ GEM
       railties (>= 3.0, < 5.0)
       thor (>= 0.14, < 2.0)
     json (1.7.7)
-    mail (2.5.3)
-      i18n (>= 0.4.0)
+    mail (2.5.4)
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
-    mime-types (1.21)
+    mime-types (1.23)
     multi_json (1.7.1)
     polyglot (0.3.3)
     rack (1.4.5)

data/lib/sumatra/rails/version.rb

@@ -1,5 +1,5 @@
 module Sumatra
   module Rails
-    VERSION = "0.0.4.1"
+    VERSION = "0.0.5"
   end
 end

data/vendor/assets/javascripts/sumatra.js.coffee

@@ -1 +1,122 @@
-#= require_tree ./sumatra/pkg
+# SumatraPlugin
+# -------------
+#
+# A prototype object for common actions when defining jQuery plugins
+# in the Sumatra framework. It is designed so that you never have to
+# override the constructor. Instead, the constructor sets up a common
+# method interface for both initialization (which would happen after
+# construction) and the binding of events, a common task in jQuery
+# plugins. This prototype even handles some of that for you, with
+# the default `bindEvents()` being bound to call the `perform()`
+# method (which must be defined by the object extending `SumatraPlugin`)
+# whenever the element it was constructed with triggers the event
+# defined by `action`.
+#
+# So essentially, you can define almost any jQuery plugin using this
+# interface, even though the only thing binding it to the `sumatra`
+# function is its constructor that takes 3 parameters.
+#
+# `SumatraPlugin` also has facilities for dealing with an options hash
+# and merging said options with defaults. You can define the default
+# options for your plugin like so:
+#
+#     sumatra 'clickToGo', ->
+#       class ClickToGo extends SumatraPlugin
+#         action: 'click'
+#         defaults: { to: 'http://google.com' }
+#         perform: (event) =>
+#           if confirm "Are you sure you want to go to #{@options.goTo}?"
+#             window.location = @options.goTo
+#
+# Then, when instantiating, just override them.
+#
+#     $('a').clickToGo(to: 'http://yahoo.com');
+#
+# This removes the need for writing that boilerplate options hash extend
+# code every time you write a jQuery plugin that takes options. All
+# plugins defined with `sumatra()` take an optional options hash, which is
+# `{}` by default, in case your plugin doesn't require options.
+class @SumatraPlugin
+  # The event to bind to if `perform()` is defined.
+  action: 'one'
+
+  # A hash of attributes that are extended with an options hash passed
+  # into the jQuery plugin upon instantiation. Useful for setting up
+  # data that is required.
+  defaults: {}
+
+  # Instantiate a `SumatraPlugin` and bind it to the current element
+  # with options. This also initiates the workflow.
+  #
+  # **DO NOT OVERRIDE!!**
+  constructor: (current_element, index_of_query, init_options) ->
+    @element = $(current_element)
+    @index = index_of_query
+    @options = @mergeDefaultsWith init_options
+    @element.data 'serviceObject', this
+    @initialize() and @bindEvents()
+
+  # Merge `options` hash with the `defaults` as set in the definition
+  # of this object.
+  mergeDefaultsWith: (options) ->
+    _.extend @defaults, @options
+
+  # Run custom constructor code, but blocks instantiation if this method
+  # returns `false`. This method was pretty much designed to be overridden.
+  initialize: ->
+    true
+
+  # Bind the `perform()` method to the `action` as set in the definition
+  # of this plugin. Overriding this method removes the guarantee that
+  # perform() will be called at all...
+  bindEvents: ->
+    if @action?
+      @element.on @action, @perform
+
+  # The event binding that handles `action`. Override this with your own
+  # method. You must override this method or the `bindEvents` method to
+  # get this plugin to do anything. It takes a single argument, `event`,
+  # which represents the given DOMEvent represented by `action` as passed
+  # in by `jQuery.on`.
+  perform: null
+
+# SumatraRuntime
+# --------------
+#
+# Defines a jQuery plugin using a service object with a nice,
+# consistent, CoffeeScript-style interface. Plugins can extend
+# `SumatraPlugin`, a prototype that makes defining plugins with
+# Sumatra easier.
+#
+# The runtime function returns the generated jQuery plugin to the
+# global scope so it can be used in your application code.
+#
+# Arguments:
+#
+# - **plugin_name:** The jQuery plugin name, called like `$('div').myPlugin();`
+# - **plugin_code:** A function that will be executed immediately and must return
+# a single object that takes 3 parameters in its constructor. These parameters
+# are the `element` being targeted by jQuery, the `index` at which it appears
+# in the query, and the `options` hash passed during the instantiation of the
+# jQuery plugin.
+#
+# Example:
+#
+#     sumatra 'myPlugin', ->
+#       class MyPlugin extends SumatraPlugin
+#         action: null
+#         initialize:
+#           alert 'loaded'
+#
+@sumatra = (plugin_name, plugin_code) ->
+  # Instantiate a PluginHelper and apply the current scope. This can
+  # be any object that responds to 3 parameters in its constructor
+  # and will be set to whatever is returned by `plugin_code()`.
+  PluginHelper = plugin_code.apply this
+
+  jQuery.fn[plugin_name] = (options={}) ->
+    @each (index, element) ->
+      # For each element, create a `PluginHelper` instance
+      # of the passed-in `plugin_code` and apply the jQuery
+      # plugin parameters to the constructor. 
+      new PluginHelper(element, index, options)

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: sumatra-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.4.1
+  version: 0.0.5
+  prerelease: 
 platform: ruby
 authors:
 - Tom Scott
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-19 00:00:00.000000000 Z
+date: 2013-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -20,6 +22,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -27,6 +30,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: jquery-rails
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -34,6 +38,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -41,6 +46,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: coffee-rails
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -48,6 +54,7 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -108,53 +115,35 @@ files:
 - test/sumatra_test.rb
 - test/test_helper.rb
 - vendor/assets/javascripts/sumatra.js.coffee
-- vendor/assets/javascripts/sumatra/.env.example
-- vendor/assets/javascripts/sumatra/.gitignore
-- vendor/assets/javascripts/sumatra/Cakefile
-- vendor/assets/javascripts/sumatra/LICENSE.md
-- vendor/assets/javascripts/sumatra/README.md
-- vendor/assets/javascripts/sumatra/component.json
-- vendor/assets/javascripts/sumatra/docs/docco.css
-- vendor/assets/javascripts/sumatra/docs/index.html
-- vendor/assets/javascripts/sumatra/docs/index.md
-- vendor/assets/javascripts/sumatra/docs/plugin.js.html
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-bold.eot
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-bold.ttf
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-bold.woff
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-light.eot
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-light.ttf
-- vendor/assets/javascripts/sumatra/docs/public/fonts/aller-light.woff
-- vendor/assets/javascripts/sumatra/docs/public/fonts/fleurons.eot
-- vendor/assets/javascripts/sumatra/docs/public/fonts/fleurons.ttf
-- vendor/assets/javascripts/sumatra/docs/public/fonts/fleurons.woff
-- vendor/assets/javascripts/sumatra/docs/public/fonts/novecento-bold.eot
-- vendor/assets/javascripts/sumatra/docs/public/fonts/novecento-bold.ttf
-- vendor/assets/javascripts/sumatra/docs/public/fonts/novecento-bold.woff
-- vendor/assets/javascripts/sumatra/docs/public/images/gray.png
-- vendor/assets/javascripts/sumatra/docs/public/stylesheets/normalize.css
-- vendor/assets/javascripts/sumatra/docs/runtime.js.html
 homepage: http://github.com/tubbo/sumatra-rails
 licenses: []
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1720138496632790677
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: 1720138496632790677
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Sumatra is a CoffeeScript framework for writing beautiful jQuery plugins.
 test_files:
 - test/dummy/app/assets/javascripts/application.js

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ODkxYTU2MjY5YjZlN2RmYjQ3OWJjMDQyMDM1Mjg3ZmRlNzlmNmM1ZQ==
-  data.tar.gz: !binary |-
-    ODI5MDY2OWRlMWIxZjZkYTQ4N2MxODAzYzFlOTI5MzEyMTI2Yjk2YQ==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    NDA3OTZiMjgzNzAzMjMyOTRhYmY1ZjQwMmNiMGUyOGFmNjFiMTA5ZTBjNmY3
-    MjgyYjU5NGJmMDFjNjYzMzg2YzE1Y2E1ODJkNDc4OTBmY2NlZjhlNDE2Nzkx
-    OTI1Y2JkZDYxNDIyNzRhZmEwZGIyYjM5MDk3ZTgwNTIxNDlmZTY=
-  data.tar.gz: !binary |-
-    MzNlMjZhM2QyMDAyZmY3MjMzZjgzZTBhMDRkZTRlYjgwZWNjOThiYzdlMzc0
-    NzhlZTg1MzZmY2U4NWVlMGRjZjdhNzdiZmYxY2E1MzliZDI0NzJjMDBkYTVj
-    ZGI3NmJmNjQ4NjY0MmFkZmNmZjI0OTdhMjg5Yjg3YjA2OGEzYWQ=

data/vendor/assets/javascripts/sumatra/.env.example

@@ -1 +0,0 @@
-PATH=node_modules/.bin:$PATH

data/vendor/assets/javascripts/sumatra/.gitignore

@@ -1,2 +0,0 @@
-node_modules
-components/sumatra/

data/vendor/assets/javascripts/sumatra/Cakefile

@@ -1,27 +0,0 @@
-{exec} = require 'child_process'
-
-task 'build:javascript', "Compile Sumatra into JavaScript", ->
-  exec 'coffee --join pkg/sumatra.js --compile lib/sumatra/*.coffee'
-
-task 'build:coffeescript', "Compile Sumatra into CoffeeScript", ->
-  fs = require 'fs'
-  src = fs.readFileSync 'lib/sumatra/plugin.js.coffee'
-  src += fs.readFileSync 'lib/sumatra/runtime.js.coffee'
-  fs.writeFile 'pkg/sumatra.coffee', src, (err) ->
-    throw err if err
-  true
-
-task 'build', "Compile Sumatra into both languages", ->
-  invoke 'build:coffeescript'
-  invoke 'build:javascript'
-
-task 'test', "Run all tests", ->
-  exec "NODE_ENV=test
-    mocha
-    --compilers coffee:coffee-script
-    --require coffee-script
-    --require test/test_helper.js.coffee
-    --colors
-  ", (err, output) ->
-    throw err if err
-    console.log output

data/vendor/assets/javascripts/sumatra/LICENSE.md

@@ -1,20 +0,0 @@
-Copyright 2013 Tom Scott
-
-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/vendor/assets/javascripts/sumatra/README.md

@@ -1,183 +0,0 @@
-# Sumatra
-
-Sumatra is a CoffeeScript framework for writing jQuery plugins harder,
-better, faster, stronger.
-
-You should use Sumatra if you...
-
-- Encapsulate complex jQuery plugins in a service object and call an
-  instance of that service object for each DOM element the plugin
-  selector is passed
-- Enjoy test-driven development, clear code, and convention over
-  configuration
-- Believe unicorns are real
-
-## Why?
-
-A lot of jQuery plugins are written to encapsulate a simple bit of
-functionality used throughout the application. But jQuery's syntax was
-designed to improve the way people write JavaScript. CoffeeScript has a
-similar goal, but approaches it from a different angle, it compiles its
-syntax into JavaScript but does so in a safe, syntactically correct and
-(mostly) readable way. This framework unites the two, and finally allows
-jQuery developers to build plugins in CoffeeScript without making their
-code look, well, downright ugly!
-
-## Installation
-
-### Requirements
-
-- jQuery
-- CoffeeScript if you want to develop it..
-
-We recommend Bower for installing Sumatra as a component:
-
-```bash
-$ bower install sumatra
-```
-
-However, you can also install Sumatra manually by just including the
-`pkg/sumatra.js` file in your javascripts directory.
-
-## Usage
-
-Sumatra values convention over configuration, and its usage revolves
-around an established pattern that hopefully others will find useful.
-
-### Defining a Basic Plugin
-
-After loading Sumatra, you can build jQuery plugins that are both clear
-and superbly terse:
-
-```coffeescript
-sumatra 'clickMe', ->
-  class ClickMe extends SumatraPlugin
-    action: 'click'
-    perform: (event) =>
-      element_id = @element.attr('id') || '<div>'
-      alert "You just clicked #{element_id}!"
-```
-
-All this plugin does is show an `alert()` when the element is clicked.
-You can define a single action with `action:` and then define the
-`perform()` event handler that binds to whatever action you've set
-on the element.
-
-To bind an element to this event, just call it like any normal
-jQuery plugin:
-
-```coffeescript
-$('#my_element').clickMe();
-```
-
-### Parameters
-
-You can also make plugins that pass in options. All Sumatra plugins
-take an `options` hash as their only argument, regardless of whether
-the service object uses them or not.
-
-```coffeescript
-sumatra 'ajaxSubmit', ->
-  class AjaxSubmit extends SumatraPlugin
-    action: 'submit'
-    mergeOptions: ->
-      @defaults = @_getFormDefaults()
-      _.extend(@options, @defaults)
-
-    perform: (event) =>
-      event.preventDefault()
-      event.stopPropagation()
-      $.ajax @options
-
-    _getFormDefaults: ->
-      {
-        url: @element.attr('action')
-        type: @element.attr('method')
-        error: (message, status, xhr) ->
-          console.log status, message, xhr
-          alert "#{status}: #{message}"
-      }
-```
-
-This is an example of [ajaxSubmit from the jQuery.form plugin][jqform],
-implemented using Sumatra. It would especially be useful when rendering
-an inline response with JSON, using something such as Handlebars to
-compile the JSON data into a logic-less client-side template...
-
-```coffeescript
-$('form').ajaxSubmit \
-  dataType: 'json'
-  success: (context) =>
-    template = Handlebars.compile $('#response_template')
-    response = template(context)
-    @element.html response
-```
-
-### Basic Properties
-
-As a by-product of the jQuery instantation process, each `SumatraPlugin`
-comes with the following three properties, for free:
-
-- **element:** References a single jQuery DOM Object, which can perform
-  basic functionality on the page. It is obtained from the collection of
-  objects which matched the plugin's selector upon instantiation.
-- **index:** The index of the jQuery DOM Object in the collection of
-  objects which matched the plugin's selector upon instantiation.
-- **options:** A Hash-notated Object obtained as the only argument in
-  the jQuery plugin when instantiated. This object is then merged with
-  the `defaults` hash, which are default params in the plugin's
-  definition, before initialization occurs.
-
-### Workflow
-
-Each SumatraPlugin has a "workflow" that is expressed as a series of
-methods, all run in the `constructor` of the object. The constructor
-is responsible for setup of the object's basic properties. This method
-should never be overridden, instead, each step of the instantiation
-process can be controlled by overriding one of the following methods:
-
-- **mergeOptions:** Merge the options with the defaults hash. You can
-  override this to use attributes from `@element` as defaults instead.
-- **initialize:** The main override of the constructor method, this is
-  where one would actually "construct" the objects they are going to be
-  using in this plugin instance, bind events, and call helper methods.
-- **bindEvents:** This is where the `action:` event should be bound in
-  some way. In many cases, this is overridden to bind other events as
-  well as the `action:`, or binding the event as a `$(document).on`.
-- **perform:** The event handler of the plugin, this is normally called
-  when the `action:` event is fired, but it must be defined if it is
-  called or it will throw an error.
-
-You can define more methods, but these are the only public methods that
-should be overridden. Any method beginning with `_` is considered
-"private" and should not be overridden. Please carry this convention
-to your own code as well.
-
-## Development
-
-You can build this code into JavaScript by running the following
-command at the root dir:
-
-```bash
-$ npm install && cake build
-```
-
-### Contributions
-
-Contributions will be accepted via Git/GitHub pull requests, as long as
-you write tests that prove your contributions work. We use Jasmine to
-write tests in CoffeeScript (you know, for the actual framework?) and
-RSpec to write tests for the Rails helpers.
-
-### Releases
-
-All releases will be made in both CoffeeScript and JavaScript, and
-available simultaneously on the Bower and RubyGems package managers.
-We use Bower to manage the standalone JavaScript code which has no
-dependency on Sprockets, Rails, or anything Ruby.
-
-This code is released under the [MIT License][LICENSE].
-
-[jqform]: http://jquery.malsup.com/form
-[LICENSE]: https://github.com/tubbo/sumatra/blob/master/LICENSE.md
-[engine]: http://github.com/tubbo/sumatra-rails

data/vendor/assets/javascripts/sumatra/component.json

@@ -1,30 +0,0 @@
-{
-  "name": "sumatra",
-  "version": "0.0.0",
-  "main": "./pkg/sumatra.js",
-  "dependencies": {
-    "jquery": "~1.9.1",
-    "underscore": "~1.4.4",
-    "bootstrap.css": "~2.1.1"
-  },
-  "devDependencies": {
-    "coffee-script": "~1.6.2"
-  },
-  "ignore": [
-    "components/**",
-    "test/**",
-    "lib/**",
-    "package.json",
-    "index.html"
-  ],
-  "gitHead": "c7f52b1ad87c6d4c516eafc8307d8ecb5b132e9b",
-  "readme": "# Sumatra\n\nSumatra is a CoffeeScript framework for writing jQuery plugins harder,\nbetter, faster, stronger.\n\nYou should use Sumatra if you...\n\n- Encapsulate complex jQuery plugins in a service object and call an\n  instance of that service object for each DOM element the plugin\n  selector is passed\n- Enjoy test-driven development, clear code, and convention over\n  configuration\n- Believe unicorns are real\n\n## Why?\n\nA lot of jQuery plugins are written to encapsulate a simple bit of\nfunctionality used throughout the application. But jQuery's syntax was\ndesigned to improve the way people write JavaScript. CoffeeScript has a\nsimilar goal, but approaches it from a different angle, it compiles its\nsyntax into JavaScript but does so in a safe, syntactically correct and\n(mostly) readable way. This framework unites the two, and finally allows\njQuery developers to build plugins in CoffeeScript without making their\ncode look, well, downright ugly!\n\n## Installation\n\n### Requirements\n\n- jQuery\n- CoffeeScript if you want to develop it..\n\nWe recommend Bower for installing Sumatra as a component:\n\n```bash\n$ bower install sumatra\n```\n\nHowever, you can also install Sumatra manually by just including the\n`pkg/sumatra.js` file in your javascripts directory.\n\n## Usage\n\nSumatra values convention over configuration, and its usage revolves\naround an established pattern that hopefully others will find useful.\n\n### Defining a Basic Plugin\n\nAfter loading Sumatra, you can build jQuery plugins that are both clear\nand superbly terse:\n\n```coffeescript\nsumatra 'clickMe', ->\n  class ClickMe extends SumatraPlugin\n    action: 'click'\n    perform: (event) =>\n      element_id = @element.attr('id') || '<div>'\n      alert \"You just clicked #{element_id}!\"\n```\n\nAll this plugin does is show an `alert()` when the element is clicked.\nYou can define a single action with `action:` and then define the\n`perform()` event handler that binds to whatever action you've set\non the element.\n\nTo bind an element to this event, just call it like any normal\njQuery plugin:\n\n```coffeescript\n$('#my_element').clickMe();\n```\n\n### Parameters\n\nYou can also make plugins that pass in options. All Sumatra plugins\ntake an `options` hash as their only argument, regardless of whether\nthe service object uses them or not.\n\n```coffeescript\nsumatra 'ajaxSubmit', ->\n  class AjaxSubmit extends SumatraPlugin\n    action: 'submit'\n    mergeOptions: ->\n      @defaults = @_getFormDefaults()\n      _.extend(@options, @defaults)\n\n    perform: (event) =>\n      event.preventDefault()\n      event.stopPropagation()\n      $.ajax @options\n\n    _getFormDefaults: ->\n      {\n        url: @element.attr('action')\n        type: @element.attr('method')\n        error: (message, status, xhr) ->\n          console.log status, message, xhr\n          alert \"#{status}: #{message}\"\n      }\n```\n\nThis is an example of [ajaxSubmit from the jQuery.form plugin][jqform],\nimplemented using Sumatra. It would especially be useful when rendering\nan inline response with JSON, using something such as Handlebars to\ncompile the JSON data into a logic-less client-side template...\n\n```coffeescript\n$('form').ajaxSubmit \\\n  dataType: 'json'\n  success: (context) =>\n    template = Handlebars.compile $('#response_template')\n    response = template(context)\n    @element.html response\n```\n\n### Basic Properties\n\nAs a by-product of the jQuery instantation process, each `SumatraPlugin`\ncomes with the following three properties, for free:\n\n- **element:** References a single jQuery DOM Object, which can perform\n  basic functionality on the page. It is obtained from the collection of\n  objects which matched the plugin's selector upon instantiation.\n- **index:** The index of the jQuery DOM Object in the collection of\n  objects which matched the plugin's selector upon instantiation.\n- **options:** A Hash-notated Object obtained as the only argument in\n  the jQuery plugin when instantiated. This object is then merged with\n  the `defaults` hash, which are default params in the plugin's\n  definition, before initialization occurs.\n\n### Workflow\n\nEach SumatraPlugin has a \"workflow\" that is expressed as a series of\nmethods, all run in the `constructor` of the object. The constructor\nis responsible for setup of the object's basic properties. This method\nshould never be overridden, instead, each step of the instantiation\nprocess can be controlled by overriding one of the following methods:\n\n- **mergeOptions:** Merge the options with the defaults hash. You can\n  override this to use attributes from `@element` as defaults instead.\n- **initialize:** The main override of the constructor method, this is\n  where one would actually \"construct\" the objects they are going to be\n  using in this plugin instance, bind events, and call helper methods.\n- **bindEvents:** This is where the `action:` event should be bound in\n  some way. In many cases, this is overridden to bind other events as\n  well as the `action:`, or binding the event as a `$(document).on`.\n- **perform:** The event handler of the plugin, this is normally called\n  when the `action:` event is fired, but it must be defined if it is\n  called or it will throw an error.\n\nYou can define more methods, but these are the only public methods that\nshould be overridden. Any method beginning with `_` is considered\n\"private\" and should not be overridden. Please carry this convention\nto your own code as well.\n\n## Development\n\nYou can build this code into JavaScript by running the following\ncommand at the root dir:\n\n```bash\n$ npm install && cake build\n```\n\n### Contributions\n\nContributions will be accepted via Git/GitHub pull requests, as long as\nyou write tests that prove your contributions work. We use Jasmine to\nwrite tests in CoffeeScript (you know, for the actual framework?) and\nRSpec to write tests for the Rails helpers.\n\n### Releases\n\nAll releases will be made in both CoffeeScript and JavaScript, and\navailable simultaneously on the Bower and RubyGems package managers.\nWe use Bower to manage the standalone JavaScript code which has no\ndependency on Sprockets, Rails, or anything Ruby.\n\nThis code is released under the [MIT License][LICENSE].\n\n[jqform]: http://jquery.malsup.com/form\n[LICENSE]: https://github.com/tubbo/sumatra/blob/master/LICENSE.md\n[engine]: http://github.com/tubbo/sumatra-rails\n",
-  "readmeFilename": "README.md",
-  "_id": "sumatra@0.0.4",
-  "description": "Sumatra is a CoffeeScript framework for writing jQuery plugins harder, better, faster, stronger.",
-  "commit": "c7f52b1ad87c6d4c516eafc8307d8ecb5b132e9b",
-  "repository": {
-    "type": "git",
-    "url": "git://github.com/tubbo/sumatra.git"
-  }
-}