A framework for defining beautiful jQuery plugins in CoffeeScript.
Sumatra is a CoffeeScript framework for writing jQuery plugins harder, better, faster, stronger.
You should use Sumatra if you...
We recommend Bower for installing Sumatra as a component:
$ bower install sumatra
However, you can also install Sumatra manually by just including the
Sumatra values convention over configuration, and its usage revolves around an established pattern that hopefully others will find useful.
After loading Sumatra, you can build jQuery plugins that are both clear and superbly terse:
sumatra 'clickMe'->action: 'click':element_id = @elementattr'id' || '<div>'alert "You just clicked !"
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:
You can also make plugins that pass in options. All Sumatra plugins
options hash as their only argument, regardless of whether
the service object uses them or not.
sumatra 'ajaxSubmit'->action: 'submit': ->@defaults = @_getFormDefaults_extend@options@defaults:eventpreventDefaulteventstopPropagation$ajax @options: ->url: @elementattr'action'type: @elementattr'method':consolelog statusmessagexhralert ": "
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':template = Handlebarscompile $'#response_template'response = templatecontext@elementhtml response
As a by-product of the jQuery instantation process, each
comes with the following three properties, for free:
defaultshash, which are default params in the plugin's definition, before initialization occurs.
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:
@elementas defaults instead.
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
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.
$ npm install && cake build
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.
This code is released under the MIT License.