loosejs v1.0.0

Loosejs

loosejs is a listen oriented programming library. It focus on listening, not observing. It provides a clean communication between web components and the user interface (the outside environment).

Depedency

It depends on jquery (at least v.1.7) to emit and listen javascript event.

Caution

Only put non heavy loading codes inside a listener. System logic should be outside a listener.

Usage

Each web component class (or wrapper) should have at least one loose object.

var lc = require("loose")();

DOM event

lc.listen(
    function(values){
        this; // values is {}, 'this' is the DOM anchor element
    },  "click", "a.name" // listen to clicked on <a class='name'> event
);

lc.listenDocument(
    function(values){
        this; // values is {}, 'this' is the DOM document
    },  "click" // listen to clicked on DOM document
);

lc.listenElement(
    function(values){
        this; // values is {}, 'this' is the DOM element
    },  "click" // listen to clicked on DOM element
);

lc.listen(
    function(values){
        this; // values is {}, 'this' is the DOM document or DOM element
    },  "click" // listen to any clicked event
);

lc.listen(
    function(values){
	    this; // values is {}, the DOM li elemnt
	},  "mouseover", "li.name" // listen to mouseover on <li class='name'>
);

Custom event notify()

lc.notify( true, 'alert boolean event');

Listen to its own loose.

lc.listenSelf(
    function(values){
        console.log("I have send a boolean: " + values);
    },	"alert boolean event" // custom event
);

Listen to other loose.

lc.listenOthers(
    function(values){
        console.log("Other have just send a boolean: " + values);
    },  "alert boolean event" // custom event
);

Listen to all loose and the environment. In other words, all events.

lc.listen(
    function(values){
        console.log("A loose object just send a boolean: " + values);
    },  "alert boolean event" // custom event
);

lc.listen(
    function(values){
        console.log("some one just click");
    }, 
    "click",    // DOM event
    "a"         // DOM element
);

Enabled or disable

lc.disable();  // stop all activities of this loose

lc.enable();  // enable all activities of this loose

lc.isEnable();  // return boolean

Chaining listener, notifier

lc
.listen(callbackfunction,  'evet name', 'DOM element selector')
.listenSelf(allbackfunction,  'evet name')
.listenOthers(allbackfunction,  'evet name')
.notify(values, 'event name');

Dispose all event listening up to the moment of invocation

lc.dispose(); 

Dispose only registered dispose event listening up to the moment of invocation

First add true argument to the listener

lc.listen(true,	callbackfunction, 'click');

lc.listen(true,	callbackfunction, 'something happens');

lc.listenDocument(true,	callbackfunction, 'click');

lc.listenElement(true,	callbackfunction, 'click', 'a');

lc.listenSelf(true,	callbackfunction, 'submitfail event');

lc.listenOthers(true, callbackfunction, 'delete item success event');

lc.disposeRegistered();

Elaboration

Each web component class should have at least one loose object. listenwill pick an event based on the event signature. event signature has at least one argument (event name).

Two types of event. DOM event and custom event

DOM document or DOM element ==> DOM event

notify() ==> custom event

Three variations of event signature. They are:

('click', 'a.name'); // anchor clicked event

('click'); // all clicked event

('custom event'); // custom event

Listen to custom event.

listen(callbackfunction, 'custom event name');

Listen to DOM event. DOM event can have an optional DOM element selector.

listen(callbackfunction, 'DOM event name', 'DOM element selector');

DOM event can have multiple event names separated by space. This is based on jquery event triggering structure. e.g.

listen(callbackfunction, 'keydown mousedown', 'input');

There are four variations of listener, namely listen, listenDocument, listenSelf and listenOthers. Both listenSelf and listenOthers matches only the custom event (ignoring DOM element selector).

listen to click events on the \.

listen(callbackfunction, 'click', 'a.name');

listen to click events only from the DOM document.

listenDocument(callbackfunction, 'click');

listen to events all loose.

listen(callbackfunction, 'custom event');

listenSelf to events only from its own notify().

listenSelf(callbackfunction, 'custom event'); 

listenOthers to events only from other notify().

listenOthers(callbackfunction, 'custom event');

more on notify()

values of notify(values, 'event name') is either a simple type, or simple key/value pair object type. Sending null will be converted to {}. Sending undefined will cause error thrown.

Simple type as a string, number, boolean. Simple key/value pair object type as a {key1: simple type value 1, key2: simple type value 2, ...}. Any other type will be error thrown.

If setting a custom event to a DOM (or html5) event name, e.g. 'click', error will be thrown.

notify({id:'12'}, 'Success. Newly added id event');

notify({id:'12'}, 'click'); // error thrown!!!

API

(enable or disable);

Instantiation. Default is enable

var lc = require("loose")();

listen( is registered dispose, callbackfunction, 'event name', 'optional dom element selector');

e.g. Listen to anchor clicked event (e.g. ("click", "a.name") clicked \) values is {}. this is the clicked \ DOM element

listen(function(values){this;}, 'click', 'a.name');

Listen all clicked event values is {}. this is the DOM document

listen(function(values){this;}, 'click');

Listen to all custom event. values is {}. this is the DOM document

listen(function(values){this;}, 'custom event');

listenDocument([ is registered dispose, ] callbackfunction, 'custom event or DOM event', [, 'DOM element selector']);

Listen only to DOM document event. values is {} by default. this is the DOM document

listenDocument(function(values){this;}, 'click');

listenElement([ is registered dispose, ] callbackfunction, 'DOM event', 'DOM element selector');

Listen only to DOM element event. values is {} by default. this is the DOM element

listenElement(function(values){this;}, 'click', 'a');

listenSelf([ is registered dispose, ] callbackfunction, 'custom event');

Listen to its own custom event. values is {} by default. this is the DOM document

listenSelf(function(values){this;}, 'custom event');

listenOthers([ is registered dispose, ] function(values){}, 'custom event');

Listen to others' custom event. values is {}. this is the DOM document

listenOthers(function(values){this}, 'custom event');

notify(values, 'event name');

Send custom event values: if undefined, cause error thrown, if null, will be turned to {}.

notify({id:12}, 'just added a new person');

Disable temporary all the action and reaction

disable();

Enable all the action and reaction

enable();

Return boolean

isEnable();

Disconnect and remove all listener(s) that are up to the moment at invocation, Does not affect listening attached afterwards. Does not change the state of isEnable().

dispose();

Disconnect and remove all registered dispose listener(s) that are up to the moment at invocation, Does not affect listening attached afterwards. Does not change the state of isEnable().

lc.disposeRegistered();

Further development

This library is on its initial stage. A lot more can be implemented. We suggest following pending development.

1. eliminate circular event
2. elminate event competing