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

source/Ox.UI/js/Core/Event.js

@@ -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 || {}]
+                callbacks: [
-            }].concat(Ox.slice(arguments, 1)));
+                    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,
+            var isParent = this == Ox.parent,
-                isParent = this == Ox.parent,
+                target = isParent ? window.parent : this[0].contentWindow;
-                target = isParent ? window.parent : this[0].contentWindow,
+            Ox.forEach(
-                that = this;
+                Ox.makeObject(Ox.slice(arguments)),
-            if (isParent && !Ox.oxid) {
+                function(data, event) {
-                // posting to parent, but not yet initialized
+                    target.postMessage(JSON.stringify({
-                setTimeout(function() {
+                        data: data,
-                    that.post.apply(Ox.parent, args);
+                        event: event,
-                }, 250);
+                        target: isParent ? Ox.oxid : null
-            } else {
+                    }), '*');
-                Ox.forEach(
+                }
-                    Ox.makeObject(Ox.slice(args)),
+            );
-                    function(data, event) {
+            return this;
-                        target.postMessage(JSON.stringify({
-                            data: data,
-                            event: event,
-                            target: isParent ? Ox.oxid : null
-                        }), '*');
-                    }
-                );
-            }
         };
 
-        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]
+                callbacks: [
-            }].concat(Ox.slice(arguments, 1)));
+                    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, [{