Show:

Widget extension, which can be used to add extended XY positioning support to the base Widget class, through the Base.create method.

Note: This extension requires that the WidgetPosition extension be added to the Widget (before WidgetPositionAlign, if part of the same extension list passed to Base.build).

Constructor

WidgetPositionAlign

(
  • config
)

Parameters:

  • config Object

    User configuration object.

Methods

_afterAlignChange

(
  • e
)
protected

Handles alignChange events by updating the UI in response to align Attribute changes.

Parameters:

_afterAlignOnChange

(
  • e
)
protected

Handles alignOnChange events by updating the alignment-syncing event handlers.

Parameters:

_attachPosAlignUIHandles

() protected

Attaches the alignment-syncing event handlers.

_bindUIPosAlign

() protected

Bind event listeners responsible for updating the UI state in response to the widget's position-align related state changes.

This method is invoked after bindUI has been invoked for the Widget class using the AOP infrastructure.

_detachPosAlignUIHandles

() protected

Detaches the alignment-syncing event handlers.

_doAlign

(
  • xy
)
private

Helper method, used to align the given point on the widget, with the XY page coordinates provided.

Parameters:

  • xy Array

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>XY page coordinates to align to.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_getAlignedXY

(
  • [node]
  • points
)
Array protected

Returns Widget alignment coordinates realative to the given Node.

Parameters:

  • [node] Node | String | Null optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node to align to, or null to indicate the viewport.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • points Array

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The alignment points.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Returns:

Array:

<p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>the coordinates.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_getAlignToXY

(
  • 'Node'
  • [point]
  • 'Node'
  • 'Node'
)
Array private

Returns coordinates realative to the passed Node alignment.

Parameters:

  • 'Node' Node

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node to align to.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • [point] Array optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node alignment points.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • 'Node' Number

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>x coordinate.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • 'Node' Number

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>y coordinate.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Returns:

Array:

<p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>the coordinates.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_getRegion

(
  • [node]
)
Object private

Returns the region of the passed-in Node, or the viewport region if calling with passing in a Node.

Parameters:

  • [node] Node optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node to get the region of.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Returns:

Object:

<p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node's region.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_setAlignCenter

(
  • val
)
Boolean | Node protected

Default setter for center Attribute changes. Sets up the appropriate value, and passes it through the to the align attribute.

Parameters:

  • val Boolean | Node

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The Attribute value being set.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Returns:

Boolean | Node:

<p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>the value passed in.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_syncUIPosAlign

() protected

Synchronizes the current align Attribute value to the DOM.

This method is invoked after syncUI has been invoked for the Widget class using the AOP infrastructure.

_uiSetAlign

(
  • [node]
  • points
)
protected

Updates the UI to reflect the align value passed in.

Note: See the align Attribute documentation, for the Object structure expected.

Parameters:

  • [node] Node | String | Null optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The node to align to, or null to indicate the viewport.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • points Array

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The alignment points.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

_uiSetVisiblePosAlign

(
  • visible
)
protected

Attaches or detaches alignment-syncing event handlers based on the widget's visible Attribute state.

Parameters:

  • visible Boolean

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>The current value of the widget's <code>visible</code> Attribute.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

align

(
  • [node]
  • [points]
)
chainable

Aligns this widget to the provided Node (or viewport) using the provided points. This method can be invoked with no arguments which will cause the widget's current align Attribute value to be synced to the DOM.

Parameters:

  • [node] Node | String | Null optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>A reference (or selector String) for the <code>Node</code> which with the widget is to be aligned. If null is passed in, the widget will be aligned with the viewport.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

  • [points] Array2 optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>A two item array specifying the points on the widget and <code>Node</code>/viewport which will to be aligned. The first entry is the point on the widget, and the second entry is the point on the <code>Node</code>/viewport. Valid point references are defined as static constants on the <code>WidgetPositionAlign</code> extension.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Example:

Aligning to the top-left corner of the <body>:

myWidget.align('body',
                                                    [Y.WidgetPositionAlign.TL, Y.WidgetPositionAlign.TR]);

centered

(
  • [node]
)
chainable

Centers the widget in the viewport, or if a Node is passed in, it will be centered to that Node.

Parameters:

  • [node] Node | String optional

    <p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p><p>A <code>Node</code> reference or selector String defining the <code>Node</code> which the widget should be centered. If a <code>Node</code> is not passed in, then the widget will be centered to the viewport.</p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p></p>

Properties

_posAlignUIHandles

Array protected

Holds the alignment-syncing event handles.

Default: null

BC

String static

Constant used to specify the bottom edge, center point for alignment

BL

String static

Constant used to specify the bottom-left corner for alignment

BR

String static

Constant used to specify the bottom-right corner for alignment

CC

String static

Constant used to specify the center of widget/node/viewport for alignment

LC

String static

Constant used to specify the left edge, center point for alignment

RC

String static

Constant used to specify the right edge, center point for alignment

TC

String static

Constant used to specify the top edge-center point for alignment

TL

String static

Constant used to specify the top-left corner for alignment

TR

String static

Constant used to specify the top-right corner for alignment

Attributes

align

Object

The alignment configuration for this widget.

The align attribute is used to align a reference point on the widget, with the reference point on another Node, or the viewport. The object which align expects has the following properties:

  • __node__: The Node to which the widget is to be aligned. If set to null, or not provided, the widget is aligned to the viewport.

  • __points__: 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. Supported alignment points are defined as static properties on WidgetPositionAlign.

Default: null

Example:

Aligns the top-right corner of the widget with the top-left corner of the viewport:

myWidget.set('align', {
                                                    points: [Y.WidgetPositionAlign.TR, Y.WidgetPositionAlign.TL]
                                                });

alignOn

Array

An Array of Objects corresponding to the Nodes and events that will cause the alignment of this widget to be synced to the DOM.

The alignOn Attribute is expected to be an Array of Objects with the following properties:

  • __eventName__: The String event name to listen for.

  • __node__: The optional Node that will fire the event, it can be a Node reference or a selector String. This will default to the widget's boundingBox.

Default: []

Example:

Sync this widget's alignment on window resize:

myWidget.set('alignOn', [
                                                    {
                                                        node     : Y.one('win'),
                                                        eventName: 'resize'
                                                    }
                                                ]);

centered

Boolean | Node

A convenience Attribute, which can be used as a shortcut for the align Attribute.

If set to true, the widget is centered in the viewport. If set to a Node reference or valid selector String, the widget will be centered within the Node. If set to false, no center positioning is applied.

Default: false