1 files changed, 64 insertions, 95 deletions

diff --git a/node_modules/montage/ui/popup/popup.reel/popup.js b/node_modules/montage/ui/popup/popup.reel/popup.js
index f13a6aed..2a61e75e 100755
--- a/node_modules/montage/ui/popup/popup.reel/popup.js
+++ b/node_modules/montage/ui/popup/popup.reel/popup.js
@@ -27,6 +27,10 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
     // A Delegate to control positioning (and other features, in future) of the popup in a custom manner
     delegate: {value: null},
 
+    /**
+        Internal property.
+        @private
+    */
     contentEl: {
         value: null
     },
@@ -34,66 +38,24 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
         Description TODO
         @type {Property}
         @default {Container} null
+        @private
     */
     containerEl: {
         value: null
     },
 
-/**
-  Description TODO
-  @private
-*/
-    _pointer: {
-        value: true
-    },
-/**
-        Description TODO
-        @type {Function}
-        @default {Boolean} true
-    */
-    pointer: {
-        get: function() {
-            return this._pointer;
-        },
-        set: function(value) {
-            if (this._pointer !== value) {
-                this._pointer = value;
-                this.needsDraw = true;
-            }
-        }
-    },
-/**
-  Description TODO
-  @private
-*/
-    _boxed: {
-        value: true
-    },
-/**
-        Description TODO
-        @type {Function}
-        @default {Boolean} true
-    */
-    boxed: {
-        get: function() {
-            return this._boxed;
-        },
-        set: function(value) {
-            if (this._boxed !== value) {
-                this._boxed = value;
-                this.needsDraw = true;
-            }
-        }
-    },
+
 /**
   Description TODO
   @private
 */
     _slot: {value: null},
 /**
+
         Description TODO
         @type {Function}
         @default null
+    @private
     */
     slot: {
         get: function() {
@@ -112,7 +74,8 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
 */
     _content: {value: null},
 /**
-        Description TODO
+        The Montage component that will be shown in this popup.
+
         @type {Function}
         @default null
     */
@@ -137,7 +100,8 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
 */
     _modal: { value: false },
 /**
-        Description TODO
+        If true, the Popup will be rendered as a Modal.
+
         @type {Function}
         @default {Boolean} false
     */
@@ -156,8 +120,10 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
         }
     },
 
-    // An Object wtih values {top, left}. Set it only if the popup should display at a
-    // given location instead of anchoring it to a anchor element or at the center of the screen.
+    /**
+        An Object wtih values {top, left}. Set it only if the popup should display at a
+        given location always.
+    */
     _position: {value: null},
     position: {
         get: function() {
@@ -169,8 +135,12 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
         }
     },
 
+    /**
+    * Number of milliseconds after which the Popup must be dismissed. Default is 0.
+    */
     autoDismiss: { value: 0 },
 
+    /** @private */
     _displayed: { value: false },
     displayed: {
         get: function() {
@@ -204,9 +174,10 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
 
 
     /**
+     Internal method.
      @private
      */
-    _getPosition: {
+    _getElementPosition: {
         value: function(obj) {
             var curleft = 0, curtop = 0, curHt = 0, curWd = 0;
             if (obj.offsetParent) {
@@ -222,16 +193,21 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
         }
     },
 
-    _calculatePosition: {
+    _positionPopup: {
         value: function() {
-            var pos, delegate = this.delegate, anchor = this.anchor, type = this.type;
+            var position, delegate = this.delegate, anchor = this.anchor, type = this.type;
 
-            if(delegate && (typeof delegate.positionPopup === 'function')) {
+            // if a delegate is provided, use that to get the position
+            if(delegate && (typeof delegate.willPositionPopup === 'function')) {
                 var anchorPosition;
                 if(anchor) {
-                    anchorPosition = this._getPosition(anchor);
+                    anchorPosition = this._getElementPosition(anchor);
                 }
-                pos = delegate.positionPopup(this, anchor, anchorPosition);
+                position = delegate.willPositionPopup(this, anchor, anchorPosition);
+            } else if(this.position !== null) {
+                // If a position has been specified but no delegate has been provided
+                // we assume that the position is static and hence use that
+                position = this.position;
             } else {
                 // @todo - advanced positioning support
                 var $el = this.contentEl || this.content.element;
@@ -243,67 +219,55 @@ var Popup = exports.Popup = Montage.create(Component, { /** @lends module:"modul
                 var viewportWidth = window.innerWidth;
 
                 if (anchor) {
+                    // if an anchor is provided, we position the popup relative to the anchor
+                    //
                     if (anchor.nodeName) {
                         // if anchor is an element
-                        var elPosition = this._getPosition(anchor);
+                        var elPosition = this._getElementPosition(anchor);
                         var tgtHeight = parseFloat(anchor.style.height || 0) || anchor.offsetHeight || 0;
                         var tgtWidth = parseFloat(anchor.style.width || 0) || anchor.offsetWidth || 0;
 
-                        pos = {
+                        position = {
                             top: elPosition[1] + tgtHeight + 20 /* pointer */,
                             left: elPosition[0] + (tgtWidth / 2) - (elWidth / 2)
                         };
 
-                        if (pos.left < 0) {
+