API Docs for: 3.8.0
Show:

WidgetParent Class

Uses
Defined in: widget-parent/js/Widget-Parent.js:11
Module: widget-parent

Widget extension providing functionality enabling a Widget to be a parent of another Widget.

In addition to the set of attributes supported by WidgetParent, the constructor configuration object can also contain a children which can be used to add child widgets to the parent during construction. The children property is an array of either child widget instances or child widget configuration objects, and is sugar for the add method. See the add for details on the structure of the child widget configuration object.

Constructor

WidgetParent

(
  • config
)

Defined in widget-parent/js/Widget-Parent.js:11

Parameters:

  • config Object

    User configuration object.

Methods

_add

(
  • child
  • child
  • index
)
Widget | Array protected

Defined in widget-parent/js/Widget-Parent.js:533

Adds a Widget as a child. If the specified Widget already has a parent it will be removed from its current parent before being added as a child.

Parameters:

  • child Widget | Object

    The Widget instance, or configuration object for the Widget to be added as a child.

  • child Array

    Array of Widget instances, or configuration objects for the Widgets to be added as a children.

  • index Number

    (Optional.) Number representing the position at which the child should be inserted.

Returns:

Widget | Array: Successfully added Widget or Array containing the successfully added Widget instance(s). If no children where added, will will return undefined.

_afterActiveDescendantChange

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:271

Attribute change listener for the activeDescendant attribute, responsible for setting the value of the parent's activeDescendant attribute.

Parameters:

  • event EventFacade

    The event facade for the attribute change.

_afterDestroyChild

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:217

Destroy event listener for each child Widget, responsible for removing the destroyed child Widget from the parent's internal array of children (_items property).

Parameters:

  • event EventFacade

    The event facade for the attribute change.

_afterParentSelectedChange

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:288

Attribute change listener for the selected attribute, responsible for syncing the selected state of all children to match that of their parent Widget.

Parameters:

  • event EventFacade

    The event facade for the attribute change.

_afterSelectionChange

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:234

Attribute change listener for the selection attribute, responsible for setting the value of the parent's selected attribute.

Parameters:

  • event EventFacade

    The event facade for the attribute change.

_bindUIParent

() protected

Defined in widget-parent/js/Widget-Parent.js:787

Sets up DOM and CustomEvent listeners for the parent widget.

This method in invoked after bindUI is invoked for the Widget class using YUI's aop infrastructure.

_createChild

(
  • config
)
protected

Defined in widget-parent/js/Widget-Parent.js:419

Creates an instance of a child Widget using the specified configuration. By default Widget instances will be created of the type specified by the defaultChildType attribute. Types can be explicitly defined via the childType property of the configuration object literal. The use of the type property has been deprecated, but will still be used as a fallback, if childType is not defined, for backwards compatibility.

Parameters:

  • config Object

    Object literal representing the configuration used to create an instance of a Widget.

_defAddChildFn

(
  • event
  • child
  • index
)
protected

Defined in widget-parent/js/Widget-Parent.js:462

Default addChild handler

Parameters:

  • event EventFacade

    The Event object

  • child Widget

    The Widget instance, or configuration object for the Widget to be added as a child.

  • index Number

    Number representing the position at which the child will be inserted.

_defRemoveChildFn

(
  • event
  • child
  • index
)
protected

Defined in widget-parent/js/Widget-Parent.js:502

Default removeChild handler

Parameters:

  • event EventFacade

    The Event object

  • child Widget

    The Widget instance to be removed.

  • index Number

    Number representing the index of the Widget to be removed.

_destroyChildren

() protected

Defined in widget-parent/js/Widget-Parent.js:835

Destroys all child Widgets for the parent.

This method is invoked before the destructor is invoked for the Widget class using YUI's aop infrastructure.

_item

(
  • i
)
Mixed protected

Inherited from ArrayList: collection/js/arraylist.js:138

Protected method for optimizations that may be appropriate for API mirroring. Similar in functionality to item, but is used by methods added with ArrayList.addMethod().

Parameters:

  • i Integer

    Index of item to fetch

Returns:

Mixed: The item appropriate for pass through API methods

_renderChildren

() protected

Defined in widget-parent/js/Widget-Parent.js:802

Renders all child Widgets for the parent.

This method in invoked after renderUI is invoked for the Widget class using YUI's aop infrastructure.

_setSelection

(
  • child
)
Widget | Array protected

Defined in widget-parent/js/Widget-Parent.js:320

Default setter for selection attribute changes.

Parameters:

  • child Widget | Array

    Widget or Array of Widget instances.

Returns:

Widget | Array: Widget or Array of Widget instances.

_uiAddChild

(
  • child
  • parentNode
)
protected

Defined in widget-parent/js/Widget-Parent.js:704

Updates the UI in response to a child being added.

Parameters:

  • child Widget

    The child Widget instance to render.

  • parentNode Object

    The Node under which the child Widget is to be rendered.

_uiRemoveChild

(
  • child
)
protected

Defined in widget-parent/js/Widget-Parent.js:760

Updates the UI in response to a child being removed.

Parameters:

  • child Widget

    The child Widget instance to render.

_updateActiveDescendant

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:405

Attribute change listener for the focused attribute of child Widgets, responsible for setting the value of the parent's activeDescendant attribute.

Parameters:

  • event EventFacade

    The event facade for the attribute change.

_updateSelection

(
  • event
)
protected

Defined in widget-parent/js/Widget-Parent.js:363

Attribute change listener for the selected attribute of child Widgets, responsible for setting the value of the parent's selection attribute.

Parameters:

  • event EventFacade

    The event facade for the attribute change.

add

(
  • child
  • child
  • index
)
ArrayList

Inherited from ArrayList but overwritten in widget-parent/js/Widget-Parent.js:596

Adds a Widget as a child. If the specified Widget already has a parent it will be removed from its current parent before being added as a child.

Parameters:

  • child Widget | Object

    The Widget instance, or configuration object for the Widget to be added as a child. The configuration object for the child can include a childType property, which is either a constructor function or a string which names a constructor function on the Y instance (e.g. "Tab" would refer to Y.Tab) (childType used to be named type, support for which has been deprecated, but is still maintained for backward compatibility. childType takes precedence over type if both are defined.

  • child Array

    Array of Widget instances, or configuration objects for the Widgets to be added as a children.

  • index Number

    (Optional.) Number representing the position at which the child should be inserted.

Returns:

ArrayList: Y.ArrayList containing the successfully added Widget instance(s). If no children where added, will return an empty Y.ArrayList instance.

deselectAll

()

Defined in widget-parent/js/Widget-Parent.js:695

Deselects all children.

destructor

()

Defined in widget-parent/js/Widget-Parent.js:209

The destructor implementation for Parent widgets. Destroys all children.

each

(
  • fn
  • context
)
ArrayList chainable

Inherited from ArrayList: collection/js/arraylist.js:51

Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.

The callback signature is callback( item, index ).

Parameters:

  • fn Function

    the function to execute

  • context Mixed

    optional override 'this' in the function

Returns:

ArrayList: this instance

filter

(
  • validator
)
ArrayList deprecated

Inherited from ArrayList: collection/js/arraylist-filter.js:13

Deprecated: Use ModelList or a custom subclass implementation

Create a new ArrayList (or augmenting class instance) from a subset of items as determined by the boolean function passed as the argument. The original ArrayList is unchanged.

The validator signature is validator( item ).

Parameters:

  • validator Function

    Boolean function to determine in or out.

Returns:

ArrayList: New instance based on who passed the validator.

indexOf

(
  • needle
)
Integer

Inherited from ArrayList: collection/js/arraylist.js:95

Finds the first index of the needle in the managed array of items.

Parameters:

  • needle Mixed

    The item to search for

Returns:

Integer: Array index if found. Otherwise -1

isEmpty

() Boolean

Inherited from ArrayList: collection/js/arraylist.js:116

Is this instance managing any items?

Returns:

Boolean: true if 1 or more items are being managed

item

(
  • i
)
Mixed

Inherited from ArrayList: collection/js/arraylist.js:37

Get an item by index from the list. Override this method if managing a list of objects that have a different public representation (e.g. Node instances vs DOM nodes). The iteration methods that accept a user function will use this method for access list items for operation.

Parameters:

  • i Integer

    index to fetch

Returns:

Mixed: the item at the requested index

itemsAreEqual

(
  • a
  • b
)
Boolean deprecated

Inherited from ArrayList: collection/js/arraylist-add.js:68

Deprecated: Use ModelList or a custom ArrayList subclass

Default comparator for items stored in this list. Used by remove().

Parameters:

  • a Mixed

    item to test equivalence with.

  • b Mixed

    other item to test equivalance.

Returns:

Boolean: true if items are deemed equivalent.

remove

(
  • index
)
Widget

Inherited from ArrayList but overwritten in widget-parent/js/Widget-Parent.js:627

Removes the Widget from its parent. Optionally, can remove a child by specifying its index.

Parameters:

  • index Number

    (Optional.) Number representing the index of the child to be removed.

Returns:

Widget: Widget instance that was successfully removed, otherwise undefined.

removeAll

() ArrayList

Defined in widget-parent/js/Widget-Parent.js:650

Removes all of the children from the Widget.

Returns:

ArrayList: Y.ArrayList instance containing Widgets that were successfully removed. If no children where removed, will return an empty Y.ArrayList instance.

selectAll

()

Defined in widget-parent/js/Widget-Parent.js:686

Selects all children.

selectChild

(
  • i
)

Defined in widget-parent/js/Widget-Parent.js:676

Selects the child at the given index (zero-based).

Parameters:

  • i Number

    the index of the child to be selected

size

() Integer

Inherited from ArrayList: collection/js/arraylist.js:106

How many items are in this list?

Returns:

Integer: Number of items in the list

some

(
  • fn
  • context
)
Boolean

Inherited from ArrayList: collection/js/arraylist.js:73

Execute a function on each item of the list, optionally providing a custom execution context. Default context is the item.

The callback signature is callback( item, index ).

Unlike each, if the callback returns true, the iteratation will stop.

Parameters:

  • fn Function

    the function to execute

  • context Mixed

    optional override 'this' in the function

Returns:

Boolean: True if the function returned true on an item

toJSON

() Array

Inherited from ArrayList: collection/js/arraylist.js:126

Provides an array-like representation for JSON.stringify.

Returns:

Array: an array representation of the ArrayList

Properties

_childrenContainer

Node protected

Defined in widget-parent/js/Widget-Parent.js:813

By default WidgetParent will render it's children to the parent's content box.

If the children need to be rendered somewhere else, the _childrenContainer property can be set to the Node which the children should be rendered to. This property should be set before the _renderChildren method is invoked, ideally in your renderUI method, as soon as you create the element to be rendered to.

Attributes

activeDescendant

Widget readonly

Defined in widget-parent/js/Widget-Parent.js:128

Returns the Widget's currently focused descendant Widget.

Fires event activeDescendantChange

Fires when the value for the configuration attribute activeDescendant 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.

defaultChildType

String | Object

Defined in widget-parent/js/Widget-Parent.js:106

String representing the default type of the children managed by this Widget. Can also supply default type as a constructor reference.

Fires event defaultChildTypeChange

Fires when the value for the configuration attribute defaultChildType 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.

multiple

Boolean

Defined in widget-parent/js/Widget-Parent.js:139

Boolean indicating if multiple children can be selected at once. Whether or not multiple selection is enabled is always delegated to the value of the multiple attribute of the root widget in the object hierarchy.

Default: false

Fires event multipleChange

Fires when the value for the configuration attribute multiple 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.

selection

ArrayList | Widget readonly

Defined in widget-parent/js/Widget-Parent.js:161

Returns the currently selected child Widget. If the mulitple attribte is set to true will return an Y.ArrayList instance containing the currently selected children. If no children are selected, will return null.

Fires event selectionChange

Fires when the value for the configuration attribute selection 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.

Events

addChild

Defined in widget-parent/js/Widget-Parent.js:29

Fires when a Widget is add as a child. The event object will have a 'child' property that returns a reference to the child Widget, as well as an 'index' property that returns a reference to the index specified when the add() method was called.

Subscribers to the "on" moment of this event, will be notified before a child is added.

Subscribers to the "after" moment of this event, will be notified after a child is added.

Event Payload:

removeChild

Defined in widget-parent/js/Widget-Parent.js:53

Fires when a child Widget is removed. The event object will have a 'child' property that returns a reference to the child Widget, as well as an 'index' property that returns a reference child's ordinal position.

Subscribers to the "on" moment of this event, will be notified before a child is removed.

Subscribers to the "after" moment of this event, will be notified after a child is removed.

Event Payload: