368 lines
12 KiB
JavaScript
368 lines
12 KiB
JavaScript
/*
|
|
* jquery.subscribe.1.1
|
|
*
|
|
* Implementation of publish/subcription framework for jQuery
|
|
* Requires use of jQuery. Tested with jQuery 1.3 and above
|
|
*
|
|
*
|
|
* Copyright (c) 2008 Eric Chijioke (obinna a-t g mail dot c o m)
|
|
*
|
|
*
|
|
* Dual licensed under the MIT and GPL licenses:
|
|
* http://www.opensource.org/licenses/mit-license.php
|
|
* http://www.gnu.org/licenses/gpl.html
|
|
*
|
|
* Release Notes:
|
|
*
|
|
* version 1.1:
|
|
*
|
|
* Fixed unexpected behavior which can occur when a script in a embedded page (page loaded in div,tab etc.) subscribes a handler for a topic using
|
|
* the jQuery subscribe ($.subscribe) or a no-id element but this subscribe plugin is not reloaded within that embedded page (for example, when
|
|
* script is included in containing page) . In this case, if the embedded page is reloaded without reloading the entire page (and plugin), the
|
|
* subscription could be made multiple times for the topic, which will call the handler multiple times each time the topic is published.
|
|
* Code has been added to prevent this when the subscription is made using the non-element subscribe ($.subscribe()), which assures that only one
|
|
* subscription is made for a topic for a given window/frame. To prevent this from happening for an element subscription ($elem.subscribe()), make
|
|
* sure that the element has an id attribute.
|
|
*/
|
|
|
|
|
|
(function($){
|
|
|
|
_subscribe_topics = {};
|
|
_subscribe_handlers = {};
|
|
|
|
_subscribe_getDocumentWindow = function(document){
|
|
|
|
return document.parentWindow || document.defaultView;
|
|
};
|
|
|
|
$.fn.extend({
|
|
|
|
/**
|
|
* Creates a new topic without any subscribers.
|
|
* Not usually used explicitly
|
|
*/
|
|
createTopic : function(topic) {
|
|
if(topic && !_subscribe_topics[topic]) {
|
|
|
|
_subscribe_topics[topic] = {};
|
|
_subscribe_topics[topic].objects = {};
|
|
_subscribe_topics[topic].objects['__noId__'] = [];
|
|
}
|
|
|
|
return this;
|
|
},
|
|
|
|
/**
|
|
* Destroy an existing topic and unsubscribe all subscribers
|
|
*/
|
|
destroyTopic : function(topic) {
|
|
|
|
if(topic && _subscribe_topics[topic]) {
|
|
|
|
for(i in _subscribe_topics[topic].objects) {
|
|
|
|
var object = _subscribe_topics[topic].objects[i];
|
|
|
|
if($.isArray(object)) { // handle '__noId__' elements
|
|
|
|
if(object.length > 0) {
|
|
|
|
for(j in object) {
|
|
|
|
object[j].unbind(topic);
|
|
}
|
|
}
|
|
|
|
} else {
|
|
|
|
object.unbind(topic,data);
|
|
}
|
|
}
|
|
}
|
|
|
|
delete _subscribe_topics[topic];
|
|
|
|
return this;
|
|
},
|
|
|
|
/**
|
|
* Subscribes an object to particular topic with a handler.
|
|
* When the topic is published, this handler will be executed.
|
|
*
|
|
* Parameters:
|
|
* -topic- is the string name of the topic
|
|
* -handler- is a handler function and is of the form function(event, data), in which the 'this' refers to the element itself.
|
|
* handler can be a function or can be a string referring to a function previously registered using the $.subscribeHandler() function
|
|
* Note: returning 'false' from the handler will prevent subsequent handlers from being executed on this element during
|
|
* this call.
|
|
* -data- (optional) is additional data that is passed to the event handler as event.data when the topic is published
|
|
*
|
|
* Note: Unexpected behavior can occur when a script in a embedded page (page loaded in div,tab etc.) subscribes a handler for a topic using
|
|
* the jQuery subscribe ($.subscribe) or a no-id element but this subscribe plugin is not reloaded within that embedded page (for example, when
|
|
* script is included in containing page) . In this case, if the embedded page is reloaded without reloading the entire page (and plugin), the
|
|
* subscription could be made multiple times for the topic, which will call the handler multiple times each time the topic is published.
|
|
* Code has been added to prevent this when the subscription is made using the non-element subscribe ($.subscribe()), which assures that only one
|
|
* subscription is made for a topic for a given window/frame. To prevent this from happening for an element subscription ($elem.subscribe()), make
|
|
* sure that the element has an id attribute.
|
|
*/
|
|
subscribe : function(topic, handler, data) {
|
|
|
|
if(this[0] && topic && handler) {
|
|
|
|
this.createTopic(topic);
|
|
|
|
if(this.attr('id')) {
|
|
|
|
_subscribe_topics[topic].objects[this.attr('id')] = this;
|
|
|
|
} else {
|
|
|
|
//do not subscribe the same window/frame document multiple times, this causes unexpected behavior of executing embedded scripts multiple times
|
|
var noIdObjects = _subscribe_topics[topic].objects['__noId__'];
|
|
|
|
if(this[0].nodeType == 9) { //if document is being bound (the case for non-element jQuery subscribing ($.subscribe)
|
|
|
|
for ( var index in noIdObjects) {
|
|
|
|
var noIdObject = noIdObjects[index];
|
|
|
|
if(noIdObject[0].nodeType == 9 && _subscribe_getDocumentWindow(this[0]).frameElement == _subscribe_getDocumentWindow(noIdObject[0]).frameElement ) {
|
|
|
|
return this;
|
|
}
|
|
}
|
|
}
|
|
|
|
var exists = false;
|
|
for(var i = 0; i < noIdObjects.length; i++){
|
|
if(noIdObjects[i] == this){
|
|
exists = true;
|
|
break;
|
|
}
|
|
}
|
|
|
|
if(!exists) {
|
|
|
|
_subscribe_topics[topic].objects['__noId__'].push(this);
|
|
}
|
|
}
|
|
|
|
if(typeof(handler) == 'function') {
|
|
|
|
this.bind(topic, data, handler);
|
|
|
|
} else if(typeof(handler) == 'string' && typeof(_subscribe_handlers[handler]) == 'function') {
|
|
|
|
this.bind(topic, data, _subscribe_handlers[handler]);
|
|
}
|
|
}
|
|
|
|
return this;
|
|
},
|
|
|
|
/**
|
|
* Remove a subscription of an element to a topic.
|
|
* This will unbind stop all handlers from executing on this element when the topic
|
|
* is published
|
|
*/
|
|
unsubscribe : function(topic) {
|
|
|
|
if(topic) {
|
|
|
|
if(_subscribe_topics[topic]) {
|
|
|
|
if(this.attr('id')) {
|
|
|
|
var object = _subscribe_topics[topic].objects[this.attr('id')];
|
|
|
|
if(object) {
|
|
|
|
delete _subscribe_topics[topic].objects[this.attr('id')];
|
|
}
|
|
|
|
} else {
|
|
|
|
var noIdObjects = _subscribe_topics[topic].objects['__noId__'];
|
|
|
|
for(var i = 0; i < noIdObjects.length; i++){
|
|
|
|
if(noIdObjects[i] == this){
|
|
|
|
subscribe_topics[topic].objects['__noId__'].splice(index,1);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
this.unbind(topic);
|
|
}
|
|
|
|
return this;
|
|
},
|
|
|
|
/**
|
|
* Publishes a topic (triggers handlers on all topic subscribers)
|
|
* This ends up calling any subscribed handlers which are functions of the form function (event, data)
|
|
* where: event - is a standard jQuery event object
|
|
* data - is the data parameter that was passed to this publish() method
|
|
* event.data - is the data parameter passed to the subscribe() function when this published topic was subscribed to
|
|
* event.target - is the dom element that subscribed to the event (or the document element if $.subscribe() was used)
|
|
*
|
|
* Parameters:
|
|
* -topic- is the string name of the topic
|
|
* -data- (optional) is additional data that is passed to the event handler 'data' parameter when the topic is published
|
|
* handler can be a function or can be a string referring to a function previously registered using the $.subscribeHandler() function
|
|
* -originalEvent- (optional) may be passed in a reference to an event which triggered this publishing. This will be passed as the
|
|
* 'originalEvent' field of the triggered event which will allow for controlling the propagation of higher level events
|
|
* from within the topic handler. In other words, this allows one to cancel execution of all subsequent handlers on the originalEvent
|
|
* for this element by return 'false' from a handler that is subscribed to the topic published here. This can be especially useful
|
|
* in conjunction with publishOnEvent(), where a topic is published when an event executes (such as a click) and we want our
|
|
* handler logic prevent additional topics from being published (For example if our topic displays a 'delete confirm' dialog on click and
|
|
* the user cancels, we may want to prevent subsequent topics bound to the original click event from being published).
|
|
*/
|
|
publish : function(topic, data, originalEvent) {
|
|
|
|
if(topic) {
|
|
|
|
this.createTopic(topic);
|
|
|
|
//if an orginal event exists, need to modify the event object to prevent execution of all
|
|
//other handlers if the result of the handler is false (which calls stopPropagation())
|
|
|
|
var subscriberStopPropagation = function(){
|
|
|
|
this.isImmediatePropagationStopped = function(){
|
|
return true;
|
|
};
|
|
|
|
(new $.Event).stopPropagation();
|
|
|
|
if(this.originalEvent) {
|
|
|
|
this.originalEvent.isImmediatePropagationStopped = function(){
|
|
return true;
|
|
};
|
|
|
|
this.originalEvent.stopPropagation = subscriberStopPropagation;
|
|
}
|
|
}
|
|
|
|
var event = jQuery.Event(topic);
|
|
$.extend(event,{originalEvent: originalEvent, stopPropagation: subscriberStopPropagation});
|
|
|
|
for(i in _subscribe_topics[topic].objects) {
|
|
|
|
var object = _subscribe_topics[topic].objects[i];
|
|
|
|
if($.isArray(object)) { // handle '__noId__' elements (if any)
|
|
|
|
if(object.length > 0) {
|
|
|
|
for(j in object) {
|
|
|
|
object[j].trigger( event,data);
|
|
}
|
|
}
|
|
|
|
} else {
|
|
|
|
object.trigger( event,data);
|
|
}
|
|
}
|
|
|
|
}
|
|
|
|
return this;
|
|
},
|
|
|
|
/**
|
|
* Binds an objects event handler to a publish call
|
|
*
|
|
* Upon the event triggering, this ends up calling any subscribed handlers which are functions of the form function (event, data)
|
|
* where: event- is a standard jQuery event object
|
|
* event.data- is the data parameter passed to the subscribe() function when this published topic was subscribed to
|
|
* data- is the data parameter that was passed to this publishOnEvent() method
|
|
* Parameters:
|
|
* -event- is the string name of the event upon which to publish the topic
|
|
* -topic- is the string name of the topic to publish when the event occurs
|
|
* -data- (optional) is additional data which will be passed in to the publish() method ant hen available as the second ('data')
|
|
* parameter to the topic handler
|
|
*/
|
|
publishOnEvent : function(event, topic, data) {
|
|
|
|
if(event && topic) {
|
|
|
|
this.createTopic(topic);
|
|
|
|
this.bind(event, data, function (e) {
|
|
|
|
$(this).publish(topic, e.data, e);
|
|
});
|
|
}
|
|
|
|
return this;
|
|
}
|
|
});
|
|
|
|
/**
|
|
* Make publish(), createTopic() and destroyTopic() callable without an element context
|
|
* Often don't need a context to subscribe, publish, create or destroy a topic.
|
|
* We will call from the document context
|
|
*/
|
|
$.extend({
|
|
|
|
/**
|
|
* Subscribe an event handler to a topic without an element context
|
|
*
|
|
* Note: Caution about subscribing using same document to topic multiple time (maybe by loading subscribe script multiple times)
|
|
*
|
|
*/
|
|
subscribe : function(topic, handler, data) {
|
|
return $(window).subscribe(topic, handler, data);
|
|
|
|
},
|
|
|
|
/**
|
|
* Unsubscribe an event handler for a topic without an element context
|
|
*
|
|
*/
|
|
unsubscribe : function(topic, handler, data) {
|
|
|
|
return $(window).unsubscribe(topic, handler, data);
|
|
|
|
},
|
|
|
|
/**
|
|
* Register a handler function which can then be referenced by name when calling subscribe()
|
|
*/
|
|
subscribeHandler: function(name, handler) {
|
|
|
|
if(name && handler && typeof(handler) == "function") {
|
|
|
|
_subscribe_handlers[name] = handler;
|
|
}
|
|
|
|
return $(window);
|
|
},
|
|
|
|
publish: function(topic, data) {
|
|
|
|
return $(window).publish(topic,data);
|
|
},
|
|
|
|
createTopic: function(topic) {
|
|
|
|
return $(window).createTopic(topic);
|
|
},
|
|
|
|
destroyTopic: function(topic) {
|
|
|
|
return $(window).destroyTopic(topic);
|
|
}
|
|
|
|
});
|
|
|
|
})(jQuery);
|