add documentation for Ox.parent, Ox.Event and Ox.Message

This commit is contained in:
rlx 2014-09-24 13:58:16 +02:00
parent 1cf1dea2f5
commit 3b8591c9a9

View file

@ -168,35 +168,61 @@
return this;
}
Ox.$parent = Ox.parent = (function() {
/*@
Ox.parent <o> Proxy to be used by iframes for messaging with outer window
@*/
Ox.parent = Ox.$parent = (function() {
var self = {messageCallbacks: {}},
that = {oxid: Ox.uid()};
/*@
bindMessage <f> Adds one or more message handlers
@*/
that.bindMessage = function() {
return Ox.Message.bind.apply(
this, [self].concat(Ox.slice(arguments))
);
};
/*@
bindMessageOnce <f> Adds one or more message handlers that run only once
@*/
that.bindMessageOnce = function() {
return Ox.Message.bindOnce.apply(
this, [self].concat(Ox.slice(arguments))
);
};
/*@
postMessage <f> Sends one or more messages
@*/
that.postMessage = function() {
if (window !== window.top) {
return Ox.Message.post.apply(this, arguments);
// There actually is an outer window
if (!Ox.oxid) {
// Inner window has not received init message yet
setTimeout(function() {
that.postMessage.apply(that, arguments);
}, 250);
} else {
return Ox.Message.post.apply(this, arguments);
}
}
};
/*@
triggerMessage <f> Triggers all handlers for one or more messages
@*/
that.triggerMessage = function() {
return Ox.Message.trigger.apply(
this, [self].concat(Ox.slice(arguments))
);
};
/*@
unbindMessage <f> Removes one or more message handlers
@*/
that.unbindMessage = function() {
return Ox.Message.unbind.apply(
this, [self].concat(Ox.slice(arguments))
@ -207,11 +233,31 @@
}());
/*@
Ox.Event <o> Event controller
@*/
Ox.Event = (function() {
var callbacks = {},
that = {};
/*@
bind <f> Adds one or more event handlers
([self, ]callback) -> <o> This method's `this` binding
Adds a catch-all handler
([self, ]event, callback) -> <o> This method's `this` binding
Adds a handler for a single event
([self, ]{event: callback, ...}) -> <o> This method's `this` binding
Adds handlers for multiple events
self <o> Object with `eventCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is global and is not bound to a specific `Ox.Element`
event <s> Event name
callback <f> Callback function
data <o> Event data (key/value pairs)
event <s> Event name
element <o> Element object (this method's `this` binding)
@*/
that.bind = function() {
var isElement = this !== that;
return bind.apply(this, [{
@ -219,6 +265,23 @@
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
/*@
bindOnce <f> Adds one or more event handlers that run only once
([self, ]callback) -> <o> This method's `this` binding
Adds a catch-all handler
([self, ]event, callback) -> <o> This method's `this` binding
Adds a handler for a single event
([self, ]{event: callback, ...}) -> <o> This method's `this` binding
Adds handlers for multiple events
self <o> Object with `eventCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is global and is not bound to a specific `Ox.Element`
event <s> Event name
callback <f> Callback function
data <o> Event data (key/value pairs)
event <s> Event name
element <o> Element object (this method's `this` binding)
@*/
that.bindOnce = function() {
var isElement = this !== that;
return bind.apply(this, [{
@ -227,12 +290,44 @@
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
that.trigger = function(self) {
/*@
trigger <f> Triggers all event handlers for one or more events
([self, ]event[, data]) -> <o> This method's `this` binding
Triggers one event, with optional event data
([self, ]{event: data, ...}) -> <o> This method's `this` binding
Triggers multiple events
self <o> Object with `eventCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is global and is not bound to a specific `Ox.Element`
event <s> Event name
data <o> Event data (key/value pairs)
@*/
that.trigger = function() {
var isElement = this !== that;
return trigger.apply(this, [{
callbacks: [callbacks, self.eventCallbacks || {}]
}].concat(Ox.slice(arguments, 1)));
callbacks: [
callbacks,
isElement ? arguments[0].eventCallbacks || {} : {}
]
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
/*@
unbind <f> Removes one or more event handlers
([self]) -> <o> This method's `this` binding
Unbinds all handlers
([self, ]callback) -> <o> This method's `this` binding
Unbinds a catch-all handler
([self, ]event, callback) -> <o> This method's `this` binding
Unbinds a handler for a single event
([self, ]{event: callback, ...}) -> <o> This method's `this` binding
Unbinds handlers for multiple events
self <o> Object with `eventCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is global and is not bound to a specific `Ox.Element`
event <s> Event name
callback <f> Event handler
@*/
that.unbind = function() {
var isElement = this !== that;
return unbind.apply(this, [{
@ -244,11 +339,31 @@
}());
/*@
Ox.Message <o> Message controller
@*/
Ox.Message = (function() {
var callbacks = {},
that = {};
/*@
bind <f> Adds one or more message handlers
([self, ]callback) -> <o> This method's `this` binding
Adds a catch-all handler
([self, ]message, callback) -> <o> This method's `this` binding
Adds a handler for a single message
([self, ]{message: callback, ...}) -> <o> This method's `this` binding
Adds handlers for multiple messages
self <o> Object with `messageCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is bound to the outer window (via `Ox.parent`)
message <s> Message name
callback <f> Callback function
data <o> Message data (key/value pairs)
message <s> Message name
element <o> Element object (this method's `this` binding)
@*/
that.bind = function() {
var isElement = this !== that;
return bind.apply(this, [{
@ -257,6 +372,23 @@
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
/*@
bindOnce <f> Adds one or more message handlers that run only once
([self, ]callback) -> <o> This method's `this` binding
Adds a catch-all handler
([self, ]message, callback) -> <o> This method's `this` binding
Adds a handler for a single message
([self, ]{message: callback, ...}) -> <o> This method's `this` binding
Adds handlers for multiple messages
self <o> Object with `messageCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is bound to the outer window (via `Ox.parent`)
message <s> Message name
callback <f> Callback function
data <o> Message data (key/value pairs)
message <s> Message name
element <o> Element object (this method's `this` binding)
@*/
that.bindOnce = function() {
var isElement = this !== that;
return bind.apply(this, [{
@ -266,36 +398,67 @@
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
/*@
post <f> Post a message into our out of an iframe
(message[, data]) -> <o> This method's `this` binding
Posts one message, with optional message data
({message: data, ...}) -> <o> This method's `this` binding
Posts multiple messages
message <s> Message name
data <o> Message data (key/value pairs)
@*/
that.post = function() {
var args = arguments,
isParent = this == Ox.parent,
target = isParent ? window.parent : this[0].contentWindow,
that = this;
if (isParent && !Ox.oxid) {
// posting to parent, but not yet initialized
setTimeout(function() {
that.post.apply(Ox.parent, args);
}, 250);
} else {
Ox.forEach(
Ox.makeObject(Ox.slice(args)),
function(data, event) {
target.postMessage(JSON.stringify({
data: data,
event: event,
target: isParent ? Ox.oxid : null
}), '*');
}
);
}
var isParent = this == Ox.parent,
target = isParent ? window.parent : this[0].contentWindow;
Ox.forEach(
Ox.makeObject(Ox.slice(arguments)),
function(data, event) {
target.postMessage(JSON.stringify({
data: data,
event: event,
target: isParent ? Ox.oxid : null
}), '*');
}
);
return this;
};
that.trigger = function(self) {
/*@
trigger <f> Triggers all message handlers for one or more messages
([self, ]message[, data]) -> <o> This method's `this` binding
Triggers one message, with optional message data
([self, ]{message: data, ...}) -> <o> This method's `this` binding
Triggers multiple messages
self <o> Object with `eventCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is global and is not bound to a specific `Ox.Element`
message <s> Message name
data <o> Message data (key/value pairs)
@*/
that.trigger = function() {
var isElement = this !== that;
return trigger.apply(this, [{
callbacks: [callbacks, self.messageCallbacks]
}].concat(Ox.slice(arguments, 1)));
callbacks: [
callbacks,
isElement ? arguments[0].messageCallbacks || {} : {}
]
}].concat(Ox.slice(arguments, isElement ? 1 : 0)));
};
/*@
unbind <f> Removes one or more message handlers
([self, ]callback) -> <o> This method's `this` binding
Removes a catch-all handler
([self, ]message, callback) -> <o> This method's `this` binding
Removes a handler for a single message
([self, ]{message: callback, ...}) -> <o> This method's `this` binding
Removes handlers for multiple messages
self <o> Object with `messageCallbacks` (`Ox.Element`'s `self`)
If `self` is missing and this method is not rebound, then the
handler is bound to the outer window (via `Ox.parent`)
message <s> Message name
callback <f> Message handler
@*/
that.unbind = function() {
var isElement = this !== that;
return unbind.apply(this, [{