#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# WidgetPositionAlign Class

Defined in: `widget-position-align/js/Widget-PositionAlign.js:24`
Module: widget-position-align

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`

)

Defined in `widget-position-align/js/Widget-PositionAlign.js:24`

#### Parameters:

- `config` Object

  User configuration object.

- Index
- Methods
- Properties
- Attributes

## Item Index

### Methods

- _afterAlignChange
- _afterAlignOnChange
- _attachPosAlignUIHandles
- _bindUIPosAlign
- _detachPosAlignUIHandles
- _doAlign
- _getRegion
- _setAlignCenter
- _syncUIPosAlign
- _uiSetAlign
- _uiSetVisiblePosAlign
- align
- centered

### Properties

- _posAlignUIHandles
- BC static
- BL static
- BR static
- CC static
- LC static
- RC static
- TC static
- TL static
- TR static

### Attributes

- align
- alignOn
- centered

## Methods

### `_afterAlignChange`

(

- `e`

)
protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:616`

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

#### Parameters:

- `e` EventFacade

### `_afterAlignOnChange`

(

- `e`

)
protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:631`

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

#### Parameters:

- `e` EventFacade

### `_attachPosAlignUIHandles`

() protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:458`

Attaches the alignment-syncing event handlers.

### `_bindUIPosAlign`

() protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:238`

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

Defined in `widget-position-align/js/Widget-PositionAlign.js:486`

Detaches the alignment-syncing event handlers.

### `_doAlign`

(

- `widgetPoint`
- `x`
- `y`

)
private

Defined in `widget-position-align/js/Widget-PositionAlign.js:502`

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

#### Parameters:

- `widgetPoint` String

  Supported point constant (e.g. WidgetPositionAlign.TL)

- `x` Number

  X page coordinate to align to.

- `y` Number

  Y page coordinate to align to.

### `_getRegion`

(

- `[node]`

)
Object private

Defined in `widget-position-align/js/Widget-PositionAlign.js:590`

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

#### Parameters:

- `[node]` Node optional

  The node to get the region of.

#### Returns:

Object: The node's region.

### `_setAlignCenter`

(

- `val`

)
Boolean | Node protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:327`

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

#### Parameters:

- `val` Boolean | Node

  The Attribute value being set.

#### Returns:

Boolean | Node: the value passed in.

### `_syncUIPosAlign`

() protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:254`

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

Defined in `widget-position-align/js/Widget-PositionAlign.js:347`

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

  The node to align to, or null to indicate the viewport.

- `points` Array

  The alignment points.

### `_uiSetVisiblePosAlign`

(

- `visible`

)
protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:441`

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

#### Parameters:

- `visible` Boolean

  The current value of the widget's `visible` Attribute.

### `align`

(

- `[node]`
- `[points]`

)
chainable

Defined in `widget-position-align/js/Widget-PositionAlign.js:275`

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

  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.

- `[points]` Array2 optional

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

#### Example:

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

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

### `centered`

(

- `[node]`

)
chainable

Defined in `widget-position-align/js/Widget-PositionAlign.js:311`

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

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

## Properties

### `_posAlignUIHandles`

Array protected

Defined in `widget-position-align/js/Widget-PositionAlign.js:222`

Holds the alignment-syncing event handles.

Default: null

### `BC`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:189`

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

### `BL`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:149`

Constant used to specify the bottom-left corner for alignment

### `BR`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:159`

Constant used to specify the bottom-right corner for alignment

### `CC`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:209`

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

### `LC`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:199`

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

### `RC`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:179`

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

### `TC`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:169`

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

### `TL`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:129`

Constant used to specify the top-left corner for alignment

### `TR`

String static

Defined in `widget-position-align/js/Widget-PositionAlign.js:139`

Constant used to specify the top-right corner for alignment

## Attributes

### `align`

Object

Defined in `widget-position-align/js/Widget-PositionAlign.js:48`

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

#### Fires event `alignChange`

Fires when the value for the configuration attribute `align` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

#### 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

Defined in `widget-position-align/js/Widget-PositionAlign.js:97`

An Array of Objects corresponding to the `Node`s 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: []

#### Fires event `alignOnChange`

Fires when the value for the configuration attribute `alignOn` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.

#### Example:

Sync this widget's alignment on window resize:

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

### `centered`

Boolean | Node

Defined in `widget-position-align/js/Widget-PositionAlign.js:79`

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

#### Fires event `centeredChange`

Fires when the value for the configuration attribute `centered` is changed. You can listen for the event using the `on` method if you wish to be notified before the attribute's value has changed, or using the `after` method if you wish to be notified after the attribute's value has changed.

#### Parameters:

- `e` EventFacade
  An Event Facade object with the following attribute-specific properties added:
  - `prevVal` Any
    The value of the attribute, prior to it being set.
  - `newVal` Any
    The value the attribute is to be set to.
  - `attrName` String
    The name of the attribute being set.
  - `subAttrName` String
    If setting a property within the attribute's value, the name of the sub-attribute property being set.