API Docs for: 3.8.0
Show:

File: widget-position-constrain/js/Widget-PositionConstrain.js

  1. /**
  2.  * Provides constrained xy positioning support for Widgets, through an extension.
  3.  *
  4.  * It builds on top of the widget-position module, to provide constrained positioning support.
  5.  *
  6.  * @module widget-position-constrain
  7.  */
  8. var CONSTRAIN = "constrain",
  9.     CONSTRAIN_XYCHANGE = "constrain|xyChange",
  10.     CONSTRAIN_CHANGE = "constrainChange",

  12.     PREVENT_OVERLAP = "preventOverlap",
  13.     ALIGN = "align",
  14.     
  15.     EMPTY_STR = "",

  17.     BINDUI = "bindUI",

  19.     XY = "xy",
  20.     X_COORD = "x",
  21.     Y_COORD = "y",

  23.     Node = Y.Node,

  25.     VIEWPORT_REGION = "viewportRegion",
  26.     REGION = "region",

  28.     PREVENT_OVERLAP_MAP;

  30. /**
  31.  * A widget extension, which can be used to add constrained xy positioning support to the base Widget class,
  32.  * through the <a href="Base.html#method_build">Base.build</a> method. This extension requires that 
  33.  * the WidgetPosition extension be added to the Widget (before WidgetPositionConstrain, if part of the same 
  34.  * extension list passed to Base.build).
  35.  *
  36.  * @class WidgetPositionConstrain
  37.  * @param {Object} User configuration object
  38.  */
  39. function PositionConstrain(config) {
  40.     if (!this._posNode) {
  41.         Y.error("WidgetPosition needs to be added to the Widget, before WidgetPositionConstrain is added"); 
  42.     }
  43.     Y.after(this._bindUIPosConstrained, this, BINDUI);
  44. }

  46. /**
  47.  * Static property used to define the default attribute 
  48.  * configuration introduced by WidgetPositionConstrain.
  49.  *
  50.  * @property ATTRS
  51.  * @type Object
  52.  * @static
  53.  */
  54. PositionConstrain.ATTRS = {

  56.     /**
  57.      * @attribute constrain
  58.      * @type boolean | Node
  59.      * @default null
  60.      * @description The node to constrain the widget's bounding box to, when setting xy. Can also be
  61.      * set to true, to constrain to the viewport.
  62.      */
  63.     constrain : {
  64.         value: null,
  65.         setter: "_setConstrain"
  66.     },

  68.     /**
  69.      * @attribute preventOverlap
  70.      * @type boolean
  71.      * @description If set to true, and WidgetPositionAlign is also added to the Widget, 
  72.      * constrained positioning will attempt to prevent the widget's bounding box from overlapping 
  73.      * the element to which it has been aligned, by flipping the orientation of the alignment
  74.      * for corner based alignments  
  75.      */
  76.     preventOverlap : {
  77.         value:false
  78.     }
  79. };

  81. /**
  82.  * @property _PREVENT_OVERLAP
  83.  * @static
  84.  * @protected
  85.  * @type Object
  86.  * @description The set of positions for which to prevent
  87.  * overlap.
  88.  */
  89. PREVENT_OVERLAP_MAP = PositionConstrain._PREVENT_OVERLAP = {
  90.     x: {
  91.         "tltr": 1,
  92.         "blbr": 1,
  93.         "brbl": 1,
  94.         "trtl": 1
  95.     },
  96.     y : {
  97.         "trbr": 1,
  98.         "tlbl": 1,
  99.         "bltl": 1,
  100.         "brtr": 1
  101.     }
  102. };

  104. PositionConstrain.prototype = {

  106.     /**
  107.      * Calculates the constrained positions for the XY positions provided, using
  108.      * the provided node argument is passed in. If no node value is passed in, the value of 
  109.      * the "constrain" attribute is used.
  110.      * 
  111.      * @method getConstrainedXY
  112.      * @param {Array} xy The xy values to constrain
  113.      * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
  114.      * @return {Array} The constrained xy values
  115.      */
  116.     getConstrainedXY : function(xy, node) {
  117.         node = node || this.get(CONSTRAIN);

  119.         var constrainingRegion = this._getRegion((node === true) ? null : node),
  120.             nodeRegion = this._posNode.get(REGION);

  122.         return [
  123.             this._constrain(xy[0], X_COORD, nodeRegion, constrainingRegion),
  124.             this._constrain(xy[1], Y_COORD, nodeRegion, constrainingRegion)
  125.         ];
  126.     },

  128.     /**
  129.      * Constrains the widget's bounding box to a node (or the viewport). If xy or node are not 
  130.      * passed in, the current position and the value of "constrain" will be used respectively.
  131.      * 
  132.      * The widget's position will be changed to the constrained position.
  133.      *
  134.      * @method constrain 
  135.      * @param {Array} xy Optional. The xy values to constrain
  136.      * @param {Node | boolean} node Optional. The node to constrain to, or true for the viewport
  137.      */
  138.     constrain : function(xy, node) {
  139.         var currentXY, 
  140.             constrainedXY,
  141.             constraint = node || this.get(CONSTRAIN);

  143.         if (constraint) {
  144.             currentXY = xy || this.get(XY);
  145.             constrainedXY = this.getConstrainedXY(currentXY, constraint);

  147.             if (constrainedXY[0] !== currentXY[0] || constrainedXY[1] !== currentXY[1]) {
  148.                 this.set(XY, constrainedXY, { constrained:true });
  149.             }
  150.         }
  151.     },

  153.     /**
  154.      * The setter implementation for the "constrain" attribute.
  155.      *
  156.      * @method _setConstrain
  157.      * @protected
  158.      * @param {Node | boolean} val The attribute value 
  159.      */
  160.     _setConstrain : function(val) {
  161.         return (val === true) ? val : Node.one(val);
  162.     },

  164.     /**
  165.      * The method which performs the actual constrain calculations for a given axis ("x" or "y") based
  166.      * on the regions provided.
  167.      * 
  168.      * @method _constrain
  169.      * @protected
  170.      * 
  171.      * @param {Number} val The value to constrain
  172.      * @param {String} axis The axis to use for constrainment
  173.      * @param {Region} nodeRegion The region of the node to constrain
  174.      * @param {Region} constrainingRegion The region of the node (or viewport) to constrain to
  175.      * 
  176.      * @return {Number} The constrained value
  177.      */
  178.     _constrain: function(val, axis, nodeRegion, constrainingRegion) {
  179.         if (constrainingRegion) {

  181.             if (this.get(PREVENT_OVERLAP)) {
  182.                 val = this._preventOverlap(val, axis, nodeRegion, constrainingRegion);
  183.             }

  185.             var x = (axis == X_COORD),

  187.                 regionSize    = (x) ? constrainingRegion.width : constrainingRegion.height,
  188.                 nodeSize      = (x) ? nodeRegion.width : nodeRegion.height,
  189.                 minConstraint = (x) ? constrainingRegion.left : constrainingRegion.top,
  190.                 maxConstraint = (x) ? constrainingRegion.right - nodeSize : constrainingRegion.bottom - nodeSize;

  192.             if (val < minConstraint || val > maxConstraint) {
  193.                 if (nodeSize < regionSize) {
  194.                     if (val < minConstraint) {
  195.                         val = minConstraint;
  196.                     } else if (val > maxConstraint) {
  197.                         val = maxConstraint;
  198.                     }
  199.                 } else {
  200.                     val = minConstraint;
  201.                 }
  202.             }
  203.         }

  205.         return val;
  206.     },

  208.     /**
  209.      * The method which performs the preventOverlap calculations for a given axis ("x" or "y") based
  210.      * on the value and regions provided.
  211.      * 
  212.      * @method _preventOverlap
  213.      * @protected
  214.      *
  215.      * @param {Number} val The value being constrain
  216.      * @param {String} axis The axis to being constrained
  217.      * @param {Region} nodeRegion The region of the node being constrained
  218.      * @param {Region} constrainingRegion The region of the node (or viewport) we need to constrain to
  219.      * 
  220.      * @return {Number} The constrained value
  221.      */
  222.     _preventOverlap : function(val, axis, nodeRegion, constrainingRegion) {

  224.         var align = this.get(ALIGN),
  225.             x = (axis === X_COORD),
  226.             nodeSize,
  227.             alignRegion,
  228.             nearEdge,
  229.             farEdge,
  230.             spaceOnNearSide, 
  231.             spaceOnFarSide;

  233.         if (align && align.points && PREVENT_OVERLAP_MAP[axis][align.points.join(EMPTY_STR)]) {

  235.             alignRegion = this._getRegion(align.node);

  237.             if (alignRegion) {
  238.                 nodeSize        = (x) ? nodeRegion.width : nodeRegion.height;
  239.                 nearEdge        = (x) ? alignRegion.left : alignRegion.top;
  240.                 farEdge         = (x) ? alignRegion.right : alignRegion.bottom;
  241.                 spaceOnNearSide = (x) ? alignRegion.left - constrainingRegion.left : alignRegion.top - constrainingRegion.top;
  242.                 spaceOnFarSide  = (x) ? constrainingRegion.right - alignRegion.right : constrainingRegion.bottom - alignRegion.bottom;
  243.             }
  244.  
  245.             if (val > nearEdge) {
  246.                 if (spaceOnFarSide < nodeSize && spaceOnNearSide > nodeSize) {
  247.                     val = nearEdge - nodeSize;
  248.                 }
  249.             } else {
  250.                 if (spaceOnNearSide < nodeSize && spaceOnFarSide > nodeSize) {
  251.                     val = farEdge;
  252.                 }
  253.             }
  254.         }

  256.         return val;
  257.     },

  259.     /**
  260.      * Binds event listeners responsible for updating the UI state in response to 
  261.      * Widget constrained positioning related state changes.
  262.      * <p>
  263.      * This method is invoked after bindUI is invoked for the Widget class
  264.      * using YUI's aop infrastructure.
  265.      * </p>
  266.      *
  267.      * @method _bindUIPosConstrained
  268.      * @protected
  269.      */
  270.     _bindUIPosConstrained : function() {
  271.         this.after(CONSTRAIN_CHANGE, this._afterConstrainChange);
  272.         this._enableConstraints(this.get(CONSTRAIN));
  273.     },

  275.     /**
  276.      * After change listener for the "constrain" attribute, responsible
  277.      * for updating the UI, in response to attribute changes.
  278.      *
  279.      * @method _afterConstrainChange
  280.      * @protected
  281.      * @param {EventFacade} e The event facade
  282.      */
  283.     _afterConstrainChange : function(e) {
  284.         this._enableConstraints(e.newVal);
  285.     },

  287.     /**
  288.      * Updates the UI if enabling constraints, and sets up the xyChange event listeners
  289.      * to constrain whenever the widget is moved. Disabling constraints removes the listeners.
  290.      * 
  291.      * @method enable or disable constraints listeners
  292.      * @private
  293.      * @param {boolean} enable Enable or disable constraints 
  294.      */
  295.     _enableConstraints : function(enable) {
  296.         if (enable) {
  297.             this.constrain();
  298.             this._cxyHandle = this._cxyHandle || this.on(CONSTRAIN_XYCHANGE, this._constrainOnXYChange);
  299.         } else if (this._cxyHandle) {
  300.             this._cxyHandle.detach();
  301.             this._cxyHandle = null;    
  302.         }
  303.     },

  305.     /**
  306.      * The on change listener for the "xy" attribute. Modifies the event facade's
  307.      * newVal property with the constrained XY value.
  308.      *
  309.      * @method _constrainOnXYChange
  310.      * @protected
  311.      * @param {EventFacade} e The event facade for the attribute change
  312.      */
  313.     _constrainOnXYChange : function(e) {
  314.         if (!e.constrained) {
  315.             e.newVal = this.getConstrainedXY(e.newVal);
  316.         }
  317.     },

  319.     /**
  320.      * Utility method to normalize region retrieval from a node instance, 
  321.      * or the viewport, if no node is provided. 
  322.      * 
  323.      * @method _getRegion
  324.      * @private
  325.      * @param {Node} node Optional.
  326.      */
  327.     _getRegion : function(node) {
  328.         var region;
  329.         if (!node) {
  330.             region = this._posNode.get(VIEWPORT_REGION);
  331.         } else {
  332.             node = Node.one(node);
  333.             if (node) {
  334.                 region = node.get(REGION);
  335.             }
  336.         }
  337.         return region;
  338.     }
  339. };

  341. Y.WidgetPositionConstrain = PositionConstrain;

  343.