widget-position-ext.js revision 4d1598c3e0a0b50935d0b39e5d69b68f3fdc41f0
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke SmithYUI.add('widget-position-ext', function(Y) {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith/**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Provides extended/advanced XY positioning support for Widgets, through an extension.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * It builds on top of the widget-position module, to provide alignmentment and centering support.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Future releases aim to add constrained and fixed positioning support.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @module widget-position-ext
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith var L = Y.Lang,
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith ALIGN = "align",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith BINDUI = "bindUI",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith SYNCUI = "syncUI",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith OFFSET_WIDTH = "offsetWidth",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith OFFSET_HEIGHT = "offsetHeight",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith VIEWPORT_REGION = "viewportRegion",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith REGION = "region",
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith AlignChange = "alignChange";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Widget extension, which can be used to add extended XY positioning support to the base Widget class,
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * through the <a href="Base.html#method_build">Base.build</a> method.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @class WidgetPositionExt
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @param {Object} User configuration object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith function PositionExt(config) {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith Y.after(this._syncUIPosExtras, this, SYNCUI);
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith Y.after(this._bindUIPosExtras, this, BINDUI);
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith }
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Static property used to define the default attribute
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * configuration introduced by WidgetPositionExt.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.ATTRS
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type Object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.ATTRS = {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @attribute align
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type Object
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @default null
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @desciption The align attribute is used to align a reference point on the widget, with the refernce point on another node, or the viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * The object which align expects has the following properties:
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dl>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dt>node</dt>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dd>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * The node to which the Widget is to be aligned. If set to null, or not provided, the Widget is aligned to the viewport
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * </dd>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dt>points</dt>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <dd>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <p>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * A two element array, defining the two points on the Widget and node/viewport which are to be aligned. The first element is the point on the Widget, and the second element is the point on the node/viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Supported alignment points are defined as static properties on <code>WidgetPositionExt</code>.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * </p>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * <p>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * e.g. <code>[WidgetPositionExt.TR, WidgetPositionExt.TL]</code> aligns the Top-Right corner of the Widget with the
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Top-Left corner of the node/viewport, and <code>[WidgetPositionExt.CC, WidgetPositionExt.TC]</code> aligns the Center of the
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Widget with the Top-Center edge of the node/viewport.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * </p>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * </dd>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * </dl>
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith align: {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith value:null
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith },
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @attribute centered
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type {boolean | node}
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @default false
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith * @description A convenience attribute, which can be used as a shortcut for the align attribute.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * If set to true, the Widget is centered in the viewport. If set to a node reference or valid selector string,
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * the Widget will be centered within the node. If set the false, no center positioning is applied.
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith centered: {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith setter: function(val) {
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith return this._setAlignCenter(val);
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith },
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith value:false
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith }
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith };
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the top-left corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TL
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tl"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.TL = "tl";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the top-right corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TR
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tr"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.TR = "tr";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom-left corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BL
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "bl"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.BL = "bl";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom-right corner for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BR
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "br"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.BR = "br";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
2fe13ddab136a6eb6239d89e5e064e09d9e1bb92Luke Smith * Constant used to specify the top edge-center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.TC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "tc"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.TC = "tc";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the right edge, center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.RC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "rc"
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith */
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith PositionExt.RC = "rc";
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith /**
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * Constant used to specify the bottom edge, center point for alignment
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith *
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @property WidgetPositionExt.BC
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @type String
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @static
d08a2495e1fbc0cf1435767148ec01129af3bcd6Luke Smith * @value "bc"
*/
PositionExt.BC = "bc";
/**
* Constant used to specify the left edge, center point for alignment
*
* @property WidgetPositionExt.LC
* @type String
* @static
* @value "lc"
*/
PositionExt.LC = "lc";
/**
* Constant used to specify the center of widget/node/viewport for alignment
*
* @property WidgetPositionExt.CC
* @type String
* @static
* @value "cc"
*/
PositionExt.CC = "cc";
PositionExt.prototype = {
/**
* Synchronizes the UI to match the Widgets extended positioning state.
* This method in invoked after syncUI is invoked for the Widget class
* using YUI's aop infrastructure.
*
* @method _syncUIPosExtras
* @protected
*/
_syncUIPosExtras : function() {
var align = this.get(ALIGN);
if (align) {
this._uiSetAlign(align.node, align.points);
}
},
/**
* Binds event listeners responsible for updating the UI state in response to
* Widget extended positioning related state changes.
* <p>
* This method is invoked after bindUI is invoked for the Widget class
* using YUI's aop infrastructure.
* </p>
* @method _bindUIStack
* @protected
*/
_bindUIPosExtras : function() {
this.after(AlignChange, this._afterAlignChange);
},
/**
* Default setter for center attribute changes. Sets up the appropriate value, and passes
* it through the to the align attribute.
*
* @method _setAlignCenter
* @protected
* @param {boolean | node} The attribute value being set.
* @return {Number} The attribute value being set.
*/
_setAlignCenter : function(val) {
if (val) {
this.set(ALIGN, {
node: val === true ? null : val,
points: [PositionExt.CC, PositionExt.CC]
});
}
return val;
},
/**
* Default attribute change listener for the align attribute, responsible
* for updating the UI, in response to attribute changes.
*
* @method _afterAlignChange
* @protected
* @param {Event.Facade} e The event facade for the attribute change
*/
_afterAlignChange : function(e) {
if (e.newVal) {
this._uiSetAlign(e.newVal.node, e.newVal.points);
}
},
/**
* Updates the UI to reflect the align value passed in (see the align attribute documentation, for the object stucture expected)
* @method _uiSetAlign
* @protected
* @param {Node | null} The node to align to, or null to indicate the viewport
*/
_uiSetAlign: function (node, points) {
if (!L.isArray(points) || points.length != 2) {
Y.error("align: Invalid Points Arguments");
return;
}
var nodeRegion, widgetPoint, nodePoint, xy;
if (!node) {
nodeRegion = this._posNode.get(VIEWPORT_REGION);
} else {
node = Y.Node.get(node);
if (node) {
nodeRegion = node.get(REGION);
}
}
if (nodeRegion) {
// TODO: ViewportRegion doesn't have width/height - Workaround until normalized in Node/Dom
nodeRegion.width = nodeRegion.width || nodeRegion.right - nodeRegion.left;
nodeRegion.height = nodeRegion.height || nodeRegion.bottom - nodeRegion.top;
widgetPoint = points[0];
nodePoint = points[1];
// TODO: Optimize KWeight - Would lookup table help?
switch (nodePoint) {
case PositionExt.TL:
xy = [nodeRegion.left, nodeRegion.top];
break;
case PositionExt.TR:
xy = [nodeRegion.right, nodeRegion.top];
break;
case PositionExt.BL:
xy = [nodeRegion.left, nodeRegion.bottom];
break;
case PositionExt.BR:
xy = [nodeRegion.right, nodeRegion.bottom];
break;
case PositionExt.TC:
xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top];
break;
case PositionExt.BC:
xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.bottom];
break;
case PositionExt.LC:
xy = [nodeRegion.left, nodeRegion.top + Math.floor(nodeRegion.height/2)];
break;
case PositionExt.RC:
xy = [nodeRegion.right, nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint];
break;
case PositionExt.CC:
xy = [nodeRegion.left + Math.floor(nodeRegion.width/2), nodeRegion.top + Math.floor(nodeRegion.height/2), widgetPoint];
break;
default:
break;
}
if (xy) {
this._doAlign(widgetPoint, xy[0], xy[1]);
}
}
},
/**
* Helper method, used to align the given point on the widget, with the XY page co-ordinates provided.
*
* @method _doAlign
* @private
* @param {String} widgetPoint Supported point constant (e.g. WidgetPositionExt.TL)
* @param {Number} x X page co-ordinate to align to
* @param {Number} y Y page co-ordinate to align to
*/
_doAlign : function(widgetPoint, x, y) {
var widgetNode = this._posNode,
xy;
switch (widgetPoint) {
case PositionExt.TL:
xy = [x, y];
break;
case PositionExt.TR:
xy = [x - widgetNode.get(OFFSET_WIDTH), y];
break;
case PositionExt.BL:
xy = [x, y - widgetNode.get(OFFSET_HEIGHT)];
break;
case PositionExt.BR:
xy = [x - widgetNode.get(OFFSET_WIDTH), y - widgetNode.get(OFFSET_HEIGHT)];
break;
case PositionExt.TC:
xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y];
break;
case PositionExt.BC:
xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - widgetNode.get(OFFSET_HEIGHT)];
break;
case PositionExt.LC:
xy = [x, y - (widgetNode.get(OFFSET_HEIGHT)/2)];
break;
case PositionExt.RC:
xy = [(x - widgetNode.get(OFFSET_WIDTH)), y - (widgetNode.get(OFFSET_HEIGHT)/2)];
break;
case PositionExt.CC:
xy = [x - (widgetNode.get(OFFSET_WIDTH)/2), y - (widgetNode.get(OFFSET_HEIGHT)/2)];
break;
default:
break;
}
if (xy) {
this.move(xy);
}
},
/**
* Aligns the Widget to the provided node (or viewport) using the provided
* points. The method can be invoked directly, however it will result in
* the align attribute being out of sync with current position of the of Widget.
*
* @method align
* @param {Node | String | null} node A reference (or selector string) for the Node which with the Widget is to be aligned.
* If null is passed in, the Widget will be aligned with the viewport.
* @param {Array[2]} points A two element array, specifying the points on the Widget and node/viewport which need to be aligned.
* The first entry is the point on the Widget, and the second entry is the point on the node/viewport which need to align.
* Valid point references are defined as static constants on the WidgetPositionExt class.
*
* e.g. [WidgetPositionExt.TL, WidgetPositionExt.TR] will align the top-left corner of the Widget with the top-right corner of the node/viewport.
*/
align: function (node, points) {
this.set(ALIGN, {node: node, points:points});
},
/**
* Centers the container in the viewport, or if a node is passed in,
* the node.
*
* @method centered
* @param {Node | String} node Optional. A node reference or selector string defining the node
* inside which the Widget is to be centered. If not passed in, the Widget will be centered in the
* viewport.
*/
centered: function (node) {
this.align(node, [PositionExt.CC, PositionExt.CC]);
}
};
Y.WidgetPositionExt = PositionExt;
}, '@VERSION@' ,{requires:['widget', 'widget-position']});