sumatra-rails 0.0.3.1 → 0.0.4

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NmFmY2ZmN2IxMWU4NjJkNWQ0ZTExODEzNGZhYTE5NjQ0Mzc2ZWFjZQ==
+    YzY4MTVkNTJhZWQ4OTQxNjUyYjhlNjc1MjlmM2YzNjFkZGIyOGM4OQ==
   data.tar.gz: !binary |-
-    ZTU2MzU3MmYxMzkzNWE3N2JhM2QxNThlZDA4MjE0YjJiZmQ5ODU2Nw==
+    OGEzMzc2NmQyNTg0MGU1NmUzODlhYmU3Mzk5N2UzOTZjMjBmYjI3Mg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    MDc4ZDRkZjdhZjBlYTQ1OTI4NjNmYzUzYjhjMTc3NWJkNWI3ZmY1N2IyNTg1
-    NGFkMWUxM2VmMzBlNGY2YjViMzI0MWQwYjhkNDRjZmY2ZjUxZGJiZmZmYTJj
-    OWU1Nzk2OWZhZGM4NzEyZGM3NTQ2YmY0YjkxODZhOGJlODYyODM=
+    YzU1ZGNjNjRmMWY5MGEyMjA5NzI0YTRkYjk2N2E2MjkxNzZlYjMzM2JlNTNj
+    YjQ0ZTQ4NjYxYmMwMDdiZGNjYWM5OGJkYzRkZDZiMDAwMGYzMjkzZTZmZjRm
+    ZWJhNjUyYmZjNjI2NTBlNTliMzZkYTNlOWRjMTcxYzRlYmY3YjU=
   data.tar.gz: !binary |-
-    Mjc4YmQ2MjdmZDU5NDY0NTRmMWE5NDQyZDVjNzU1ZWE0NGRjYjRlYmVkY2Rk
-    ZDJmOGVkNTYyNDlmOTg0MjZjYzM4YTc5YmUyNDBmMTU1OTJmYjZiNzAzYzMy
-    ZDhjOGM0ZjAxZGIyNDY1YTA1NDZjMmYxMjQ5ZDk1ZTA1YjFhMjY=
+    YTcyYmNkN2IwZjQ1MTAzODE1MWMyNTdkNDAwZjljZTQxN2NlZWI5YzQ5Yzk3
+    MDU1NWFiNmQ0MmRjNTkzOTExOTFiODYwYjZkMjgzNTM2OWJlZDNkZTVlNWZm
+    ZWFmZGQ2OGE0MTEwMzgzYmM2MzFmZjU3ZDczZjA3MzdkOGY4ZWE=

data/Gemfile.lock

@@ -1,20 +1,20 @@
 PATH
   remote: .
   specs:
-    sumatra-rails (0.0.3.1)
+    sumatra-rails (0.0.4)
       coffee-rails
       jquery-rails
-      rails (~> 3.2.12)
+      rails (~> 3.2)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    actionmailer (3.2.12)
-      actionpack (= 3.2.12)
-      mail (~> 2.4.4)
-    actionpack (3.2.12)
-      activemodel (= 3.2.12)
-      activesupport (= 3.2.12)
+    actionmailer (3.2.13)
+      actionpack (= 3.2.13)
+      mail (~> 2.5.3)
+    actionpack (3.2.13)
+      activemodel (= 3.2.13)
+      activesupport (= 3.2.13)
       builder (~> 3.0.0)
       erubis (~> 2.7.0)
       journey (~> 1.0.4)
@@ -22,19 +22,19 @@ GEM
       rack-cache (~> 1.2)
       rack-test (~> 0.6.1)
       sprockets (~> 2.2.1)
-    activemodel (3.2.12)
-      activesupport (= 3.2.12)
+    activemodel (3.2.13)
+      activesupport (= 3.2.13)
       builder (~> 3.0.0)
-    activerecord (3.2.12)
-      activemodel (= 3.2.12)
-      activesupport (= 3.2.12)
+    activerecord (3.2.13)
+      activemodel (= 3.2.13)
+      activesupport (= 3.2.13)
       arel (~> 3.0.2)
       tzinfo (~> 0.3.29)
-    activeresource (3.2.12)
-      activemodel (= 3.2.12)
-      activesupport (= 3.2.12)
-    activesupport (3.2.12)
-      i18n (~> 0.6)
+    activeresource (3.2.13)
+      activemodel (= 3.2.13)
+      activesupport (= 3.2.13)
+    activesupport (3.2.13)
+      i18n (= 0.6.1)
       multi_json (~> 1.0)
     arel (3.0.2)
     builder (3.0.4)
@@ -49,18 +49,18 @@ GEM
     execjs (1.4.0)
       multi_json (~> 1.0)
     hike (1.2.1)
-    i18n (0.6.4)
+    i18n (0.6.1)
     journey (1.0.4)
     jquery-rails (2.2.1)
       railties (>= 3.0, < 5.0)
       thor (>= 0.14, < 2.0)
     json (1.7.7)
-    mail (2.4.4)
+    mail (2.5.3)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
     mime-types (1.21)
-    multi_json (1.6.1)
+    multi_json (1.7.1)
     polyglot (0.3.3)
     rack (1.4.5)
     rack-cache (1.2)
@@ -69,17 +69,17 @@ GEM
       rack
     rack-test (0.6.2)
       rack (>= 1.0)
-    rails (3.2.12)
-      actionmailer (= 3.2.12)
-      actionpack (= 3.2.12)
-      activerecord (= 3.2.12)
-      activeresource (= 3.2.12)
-      activesupport (= 3.2.12)
+    rails (3.2.13)
+      actionmailer (= 3.2.13)
+      actionpack (= 3.2.13)
+      activerecord (= 3.2.13)
+      activeresource (= 3.2.13)
+      activesupport (= 3.2.13)
       bundler (~> 1.0)
-      railties (= 3.2.12)
-    railties (3.2.12)
-      actionpack (= 3.2.12)
-      activesupport (= 3.2.12)
+      railties (= 3.2.13)
+    railties (3.2.13)
+      actionpack (= 3.2.13)
+      activesupport (= 3.2.13)
       rack-ssl (~> 1.3.2)
       rake (>= 0.8.7)
       rdoc (~> 3.4)
@@ -93,7 +93,7 @@ GEM
       rack (~> 1.0)
       tilt (~> 1.1, != 1.3.0)
     thor (0.17.0)
-    tilt (1.3.5)
+    tilt (1.3.6)
     treetop (1.4.12)
       polyglot
       polyglot (>= 0.3.1)

data/lib/sumatra/rails/version.rb

@@ -1,5 +1,5 @@
 module Sumatra
   module Rails
-    VERSION = "0.0.3.1"
+    VERSION = "0.0.4"
   end
 end

data/sumatra-rails.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   s.files = `git ls-files`.split("\n")
   s.test_files = Dir["test/**/*"]
 
-  s.add_dependency "rails", "~> 3.2.12"
+  s.add_dependency "rails", "~> 3.2"
   s.add_dependency "jquery-rails"
   s.add_dependency "coffee-rails"
 end

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

@@ -1,121 +1 @@
-# 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
-    @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)
+#= require_tree sumatra/pkg

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

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

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

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

data/vendor/assets/javascripts/sumatra/Cakefile

@@ -0,0 +1,27 @@
+{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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,183 @@
+# 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