sauron
v1.1.0Sauron
Mediator pattern for Halo, a client-side MVC framework.
Synopsis
Sauron was designed as a core component of Halo; providing a loose channel system for talking between models and controllers.
Getting Started
Download the production version (vanilla or requirejs) or the development version (vanilla or requirejs).
In your web page:
<script src="jquery.js"></script>
<script src="dist/Sauron.min.js"></script>
<script>
// Start the main controller on the home page
Sauron.start().controller('main', {'page': 'home'});
</script>
Documentation
Sauron can talk in the controller
, model
, or no namespace.
Within all namespaces, we can modify events to be subscriptions, on
, unsubscriptions, off
, or emissions/triggers, voice
. By default, if a namespace has a terminating method called (e.g. start
for controller
) and there is no modifier, voice
will be called.
Terminating methods for the controller
namespace are start
and stop
.
Sauron.start().controller('home', {'some': 'data'});
Terminating methods for the model
namespace are create
, retrieve
, update
, delete
, createEvent
, updateEvent
, and deleteEvent
.
Sauron.model('app').retrieve({'id': 1}, function (err, app) {
// Inspect app
});
Examples
Listening for an event
Sauron.on().controller('home').start(function () {
console.log('A home controller has been started');
});
Triggering an event
Sauron.model('user').create({'name': 'John Doe'});
Unsubscribing from an event internally
Sauron.on().model('page').createEvent(function () {
console.log('New page created');
this.off();
});
Unsubscribing from an event externally
var subFn = function () {
console.log('Stop was called');
};
Sauron.on().controller('about').stop(subFn);
Sauron.off().controller('about').stop(subFn);
API
Sauron.channel([raw]);
/**
* Retrieval function for the current channel
* @param {Boolean} [raw] If true, prefixing will be skipped
* @returns {String}
*/
Sauron.of(subchannel);
/**
* Adds a new subchannel to the current channel
* @param {String} subchannel
* @returns {this.clone}
*/
Sauron.on([subchannel], [fn]);
/**
* Subscribing function for event listeners
* @param {String} [subchannel] Subchannel to listen to
* @param {Function} [fn] Function to subscribe with
* @returns {this.clone}
*/
Sauron.off([subchannel], [fn]);
/**
* Unsubscribing function for event listeners
* @param {String} [subchannel] Subchannel to unsubscribe from to
* @param {Function} [fn] Function to remove subscription on
* @returns {this.clone}
*/
Sauron.voice(subchannel, [param1], [param2], ...);
/**
* Voice/emit command for Sauron
* @param {String|null} subchannel Subchannel to call on. If it is falsy, it will be skipped
* @param {Mixed} [param] Parameter to voice to the channel. There can be infinite of these
* @returns {Sauron}
*/
Sauron.clone();
/**
* Returns a cloned copy of this
* @returns {this.clone}
*/
Sauron.once([subchannel], [fn]);
/**
* Sugar subscribe function that listens to an event exactly once
* @param {String} [subchannel] Subchannel to listen to
* @param {Function} [fn] Function to subscribe with
* @returns {this.clone}
*/
Sauron.noError(fn);
/**
* Helper function for error first callbacks. If an error occurs, we will log it and not call the function.
* @param {Function} fn Function to remove error for
* @returns {Function}
*/
// CONTROLLER METHODS
Sauron.controller(controller);
/**
* Fluent method for calling out a controller
* @param {String} controller Name of the controller to invoke
* @param {Mixed} * If there are any arguments, they will be passed to (on, off, once, voice) for invocation
* @returns {Mixed} If there are more arguments than controller, the (on, off, once, voice) response will be returned. Otherwise, this.clone
*/
Sauron.createController(controller);
/**
* Method for creating controllers
* @param {String} controller Controller to use name for
* This will ALWAYS call the (on, off, once, voice) function.
*/
Sauron.start([param1], [param2], ...);
Sauron.stop([param1], [param2], ...);
/**
* Methods for starting/stopping controllers. Will call previous action if there was any (e.g. on, off, once).
*/
// MODEL METHODS
Sauron.model(model);
// Same as Sauron.controller except for models
Sauron.createModel(model);
// Same as Sauron.createController except for models
Sauron.(create|retrieve|update|delete)(Event)?([param1], [param2], ...);
// Same as Sauron.start except for models
// Names expand to create, createEvent, retrieve, ..., deleteEvent
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint your code using grunt and test via the instructions below.
Also, please don't edit files in the "dist" or "stage" subdirectories as they are generated via grunt. You'll find source code in the "lib" subdirectory!
Testing
The test suite is written in Mocha (with a crossbones wrapper) for in-browser testing. Start up the server, navigate to the test page, and the test will begin.
# If you do not have serve installed, install it
sudo npm install -g serve
# Begin hosting a server
serve
# Navigate to the test page
{{browser}} http://localhost:3000/src-test/Sauron.test.html
License
Copyright (c) 2013 Ensighten Licensed under the MIT license.