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
- 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
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'->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:
- 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
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:
- mergeOptions: Merge the options with the defaults hash. You can
override this to use attributes from
@elementas 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
- perform: The event handler of the plugin, this is normally called
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.