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:

$ 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:

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:

$('#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.

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, 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...

$('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:

$ 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.