Yahoo! UI Library

widget  3.1.0

Yahoo! UI Library > widget > Widget
Search:
 
Filters

Class Widget - extends Base

Known Subclasses:
Console TabView Tab SliderBase Overlay
A base class for widgets, providing:
  • The render lifecycle method, in addition to the init and destroy lifecycle methods provide by Base
  • Abstract methods to support consistent MVC structure across widgets: renderer, renderUI, bindUI, syncUI
  • Support for common widget attributes, such as boundingBox, contentBox, visible, disabled, focused, strings

Constructor

Widget ( config )
Parameters:
config <Object> Object literal specifying widget configuration properties.

Properties

_BIND_UI_ATTRS - private Array

The list of UI attributes to bind for Widget's _bindUI implementation

_buildCfg - private static final Object

The build configuration for the Widget class.

Defines the static fields which need to be aggregated, when this class is used as the main class passed to the Base.build method.

_SYNC_UI_ATTRS - private Array

The list of UI attributes to sync for Widget's _syncUI implementation

BOUNDING_TEMPLATE - String

Property defining the markup template for bounding box.

CONTENT_TEMPLATE - String

Property defining the markup template for content box. If your Widget doesn't need the dual boundingBox/contentBox structure, set CONTENT_TEMPLATE to null, and contentBox and boundingBox will both point to the same Node.

DEF_PARENT_NODE - String | Node

Default node to render the bounding box to. If not set, will default to the current document body.

DEF_UNIT - String

Default unit to use for dimension values

UI_EVENTS - Object

Map of DOM events that should be fired as Custom Events by the Widget instance.

Widget.ATTRS - static Object

Static property used to define the default attribute configuration for the Widget.

Widget.CSS_PREFIX - private static String

The css prefix which the static Widget.getClassName method should use when constructing class names
Default Value: Widget.NAME.toLowerCase()

Widget.HTML_PARSER - static Object

Object hash, defining how attribute values are to be parsed from markup contained in the widget's content box. e.g.: 
{
// Set single Node references using selector syntax 
// (selector is run through node.one)
titleNode: "span.yui-title",
// Set NodeList references using selector syntax 
// (array indicates selector is to be run through node.all)
listNodes: ["li.yui-item"],
// Set other attribute types, using a parse function. 
// Context is set to the widget instance.
label: function(contentBox) {
return contentBox.one("span.title").get("innerHTML");
}
}

Widget.NAME - static String

Static property provides a string to identify the class.

Currently used to apply class identifiers to the bounding box and to classify events fired by the widget.

Widget.UI_SRC - static final String

Constant used to identify state changes originating from the DOM (as opposed to the JavaScript model).

Properties inherited from Attribute:

Properties inherited from Base:

name

Methods

_applyParsedConfig

protected Object _applyParsedConfig ( )
Returns: Object
The merged configuration literal

_applyParser

protected void _applyParser ( config )
Utilitity method used to apply the HTML_PARSER configuration for the instance, to retrieve config data values.
Parameters:
config <Object> User configuration object (will be populated with values from Node)

_bindAttrUI

private void _bindAttrUI ( attrs )
Binds after listeners for the list of attributes provided
Parameters:
attrs <Array>

_bindDOM

protected void _bindDOM ( )
Sets up DOM listeners, on elements rendered by the widget.

_bindUI

protected void _bindUI ( )
Sets up DOM and CustomEvent listeners for the widget.

_createUIEvent

private void _createUIEvent ( type )
Binds a delegated DOM event listener of the specified type to the Widget's outtermost DOM element to facilitate the firing of a Custom Event of the same type for the Widget instance.
Parameters:
type <String> String representing the name of the event

_defaultCB

protected void _defaultCB ( )
Returns the default value for the contentBox attribute. For the Widget class, this will be the srcNode if provided, otherwise null (resulting in a new contentBox node instance being created)

_defRenderFn

protected void _defRenderFn ( e , parentNode )
Default render handler
Parameters:
e <EventFacade> The Event object
parentNode <Node> The parent node to render to, if passed in to the render method

_getHtmlParser

private Object _getHtmlParser ( )
Gets the HTML_PARSER definition for this instance, by merging HTML_PARSER definitions across the class hierarchy.
Returns: Object
HTML_PARSER definition for this instance

_getSrcNode

protected Node _getSrcNode ( )
Returns: Node
The Node to apply HTML_PARSER to

_getStrings

protected void _getStrings ( locale )
Returns the strings key/value hash for a paricular locale, without locale lookup applied.
Parameters:
locale <Object>

_getUIEventNode

protected void _getUIEventNode ( )
Returns the node on which to bind delegate listeners.

_guid

protected void _guid ( )

_initUIEvent

private String _initUIEvent ( type )
Sets up infastructure required to fire a UI event.
Parameters:
type <String> String representing the name of the event

_isUIEvent

private String _isUIEvent ( type )
Determines if the specified event is a UI event.
Parameters:
type <String> String representing the name of the event
Returns: String
Event Returns the name of the UI Event, otherwise undefined.

_onDocFocus

protected void _onDocFocus ( evt )
DOM focus event handler, used to sync the state of the Widget with the DOM
Parameters:
evt <EventFacade> The event facade for the DOM focus event

_onDocMouseDown

protected void _onDocMouseDown ( evt )
"mousedown" event handler for the owner document of the widget's bounding box.
Parameters:
evt <EventFacade> The event facade for the DOM focus event

_removeLoadingClassNames

protected void _removeLoadingClassNames ( )
Removes class names representative of the widget's loading state from the boundingBox.

_renderBox

private void _renderBox ( parentNode )
Helper method to collect the boundingBox and contentBox, set styles and append to the provided parentNode, if not already a child. The owner document of the boundingBox, or the owner document of the contentBox will be used as the document into which the Widget is rendered if a parentNode is node is not provided. If both the boundingBox and the contentBox are not currently in the document, and no parentNode is provided, the widget will be rendered to the current document's body.
Parameters:
parentNode <Node> The parentNode to render the widget to. If not provided, and both the boundingBox and the contentBox are not currently in the document, the widget will be rendered to the current document's body.

_renderBoxClassNames

protected void _renderBoxClassNames ( )
Applies standard class names to the boundingBox and contentBox

_renderUI

protected void _renderUI ( )
Initializes the UI state for the Widget's bounding/content boxes.

_setAttrUI

private void _setAttrUI ( e )
Parameters:
e <EventFacade>

_setBB

private _setBB ( Node/String )
Setter for the boundingBox attribute
Parameters:
Node/String <object>
Returns:
Node

_setBox

private Node _setBox ( id , node , template )
Helper method to set the bounding/content box, or create it from the provided template if not found.
Parameters:
id <String> The node's id attribute
node <Node|String> The node reference
template <String> HTML string template for the node
Returns: Node
The node

_setCB

private _setCB ( node )
Setter for the contentBox attribute
Parameters:
node <Node|String>
Returns:
Node

_setStrings

protected void _setStrings ( strings , locale )
Sets strings for a particular locale, merging with any existing strings which may already be defined for the locale.
Parameters:
strings <Object> The hash of string key/values to set
locale <Object> The locale for the string values being set

_strSetter

protected String _strSetter ( strings )
The default setter for the strings attribute. Merges partial sets into the full string set, to allow users to partial sets of strings
Parameters:
strings <Object>
Returns: String
The full set of strings to set

_syncAttrUI

private void _syncAttrUI ( attrs )
Invokes the _uiSet=ATTR NAME> method for the list of attributes provided
Parameters:
attrs <Array>

_syncUI

protected void _syncUI ( )
Updates the widget UI to reflect the attribute state.

_uiSetDim

private void _uiSetDim ( dim , val )
Parameters:
dim <String> The dimension - "width" or "height"
val <Number | String> The value to set

_uiSetDisabled

protected void _uiSetDisabled ( val )
Sets the disabled state for the UI
Parameters:
val <boolean>

_uiSetFocused

protected void _uiSetFocused ( val , src )
Sets the focused state for the UI
Parameters:
val <boolean>
src <string> String representing the source that triggered an update to the UI.

_uiSetHeight

protected void _uiSetHeight ( val )
Sets the height on the widget's bounding box element
Parameters:
val <String | Number>

_uiSetTabIndex

protected void _uiSetTabIndex ( Number )
Set the tabIndex on the widget's rendered UI
Parameters:
Number <object>

_uiSetVisible

protected void _uiSetVisible ( val )
Sets the visible state for the UI
Parameters:
val <boolean>

_uiSetWidth

protected void _uiSetWidth ( val )
Sets the width on the widget's bounding box element
Parameters:
val <String | Number>

_uiSizeCB

protected void _uiSizeCB ( expand )
Parameters:
expand <boolean>

_unbindDOM

protected void _unbindDOM ( )

_unbindUI

protected void _unbindUI ( )

_validTabIndex

protected void _validTabIndex ( tabIndex )
Parameters:
tabIndex <Number>

bindUI

protected void bindUI ( )
Configures/Sets up listeners to bind Widget State to UI/DOM This method is not called by framework and is not chained automatically for the class hierarchy.

blur

void blur ( )
Causes the Widget to lose focus by setting the "focused" attribute to "false"
Chainable: This method is chainable.

destructor

protected void destructor ( )
Destructor lifecycle implementation for the Widget class. Purges events attached to the bounding box (and all child nodes) and removes the Widget from the list of registered widgets.

disable

void disable ( )
Set the Widget's "disabled" attribute to "true".
Chainable: This method is chainable.

enable

void enable ( )
Set the Widget's "disabled" attribute to "false".
Chainable: This method is chainable.

focus

void focus ( )
Causes the Widget to receive the focus by setting the "focused" attribute to "true".
Chainable: This method is chainable.

getClassName

void getClassName ( args* )
Generate a standard prefixed classname for the Widget, prefixed by the default prefix defined by the Y.config.classNamePrefix attribute used by ClassNameManager and Widget.NAME.toLowerCase() (e.g. "yui-widget-xxxxx-yyyyy", based on default values for the prefix and widget class name).

The instance based version of this method can be used to generate standard prefixed classnames, based on the instances NAME, as opposed to Widget.NAME. This method should be used when you need to use a constant class name across different types instances.

Parameters:
args* <String*> 0..n strings which should be concatenated, using the default separator defined by ClassNameManager, to create the class name

getDefaultLocale

String getDefaultLocale ( )
Returns the default locale for the widget (the locale value defined by the widget class, or provided by the user during construction).
Returns: String
The default locale for the widget

getSkinName

String getSkinName ( )
Returns the name of the skin that's currently applied to the widget. This is only really useful after the widget's DOM structure is in the document, either by render or by progressive enhancement. Searches up the Widget's ancestor axis for a class yui3-skin-(name), and returns the (name) portion. Otherwise, returns null.
Returns: String
the name of the skin, or null (yui3-skin-sam => sam)

getString

String getString ( key )
Helper method to get a specific string value
Parameters:
key <String>
Returns: String
The string
Deprecated Used by deprecated WidgetLocale implementations.

getStrings

void getStrings ( locale )
Gets the entire strings hash for a particular locale, performing locale lookup.

If no values of the key are defined for a particular locale the value for the default locale (in initial locale set for the class) is returned.

Parameters:
locale <String> (optional) The locale for which the string value is required. Defaults to the current locale, if not provided.

hide

void hide ( )
Hides the Widget by setting the "visible" attribute to "false".
Chainable: This method is chainable.

initializer

protected void initializer ( config )
Initializer lifecycle implementation for the Widget class. Registers the widget instance, and runs through the Widget's HTML_PARSER definition.
Parameters:
config <Object> Configuration object literal for the widget

render

final void render ( parentNode )
Establishes the initial DOM for the widget. Invoking this method will lead to the creating of all DOM elements for the widget (or the manipulation of existing DOM elements for the progressive enhancement use case).

This method should only be invoked once for an initialized widget.

It delegates to the widget specific renderer method to do the actual work.

Parameters:
parentNode <Object | String> Optional. The Node under which the Widget is to be rendered. This can be a Node instance or a CSS selector string.

If the selector string returns more than one Node, the first node will be used as the parentNode. NOTE: This argument is required if both the boundingBox and contentBox are not currently in the document. If it's not provided, the Widget will be rendered to the body of the current document in this case.

Chainable: This method is chainable.

renderer

protected void renderer ( )
Creates DOM (or manipulates DOM for progressive enhancement) This method is invoked by render() and is not chained automatically for the class hierarchy (unlike initializer, destructor) so it should be chained manually for subclasses if required.

renderUI

protected void renderUI ( )
Adds nodes to the DOM This method is not called by framework and is not chained automatically for the class hierarchy.

show

void show ( )
Shows the Widget by setting the "visible" attribute to "true".
Chainable: This method is chainable.

syncUI

protected void syncUI ( )
Refreshes the rendered UI, based on Widget State This method is not called by framework and is not chained automatically for the class hierarchy.

toString

String toString ( )
Generic toString implementation for all widgets.
Returns: String
The default string value for the widget [ displays the NAME of the instance, and the unique id ]

Widget.getByNode

static Widget Widget.getByNode ( node )
Returns the widget instance whose bounding box contains, or is, the given node.

In the case of nested widgets, the nearest bounding box ancestor is used to return the widget instance.

Parameters:
node <Node | String> The node for which to return a Widget instance. If a selector string is passed in, which selects more than one node, the first node found is used.
Returns: Widget
Widget instance, or null if not found.

Methods inherited from EventTarget:

_getType, _monitor, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, getTargets, on, once, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll

Methods inherited from Attribute:

_addAttrs, _addLazyAttr, _defAttrChangeFn, _fireAttrChange, _getAttr, _getAttrInitVal, _getAttrs, _getStateVal, _isLazyAttr, _normAttrVals, _protectAttrs, _set, _setAttr, _setAttrs, _setAttrVal, _setStateVal, addAttr, addAttrs, attrAdded, get, getAttrs, modifyAttr, removeAttr, reset, set, setAttrs

Methods inherited from Plugin.Host:

_destroyPlugins, _initPlugins, _plug, _unplug, hasPlugin, plug, unplug

Methods inherited from Base:

_aggregateAttrs, _defDestroyFn, _defInitFn, _destroyHierarchy, _filterAttrCfs, _getAttrCfgs, _getClasses, _initHierarchy, _initHierarchyData, _preInitEventCfg, destroy, init, toString

Events

boundingBoxChange

boundingBoxChange ( event )
Fires when the value for the configuration attribute 'boundingBox' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

contentBoxChange

contentBoxChange ( event )
Fires when the value for the configuration attribute 'contentBox' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

disabledChange

disabledChange ( event )
Fires when the value for the configuration attribute 'disabled' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

focusedChange

focusedChange ( event )
Fires when the value for the configuration attribute 'focused' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

heightChange

heightChange ( event )
Fires when the value for the configuration attribute 'height' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

idChange

idChange ( event )
Fires when the value for the configuration attribute 'id' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

localeChange

localeChange ( event )
Fires when the value for the configuration attribute 'locale' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

renderChange

renderChange ( event )
Fires when the value for the configuration attribute 'render' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

renderedChange

renderedChange ( event )
Fires when the value for the configuration attribute 'rendered' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

srcNodeChange

srcNodeChange ( event )
Fires when the value for the configuration attribute 'srcNode' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

stringsChange

stringsChange ( event )
Fires when the value for the configuration attribute 'strings' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

tabIndexChange

tabIndexChange ( event )
Fires when the value for the configuration attribute 'tabIndex' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

visibleChange

visibleChange ( event )
Fires when the value for the configuration attribute 'visible' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

widget:contentUpdate

widget:contentUpdate ( e )
Notification event, which widget implementations can fire, when they change the content of the widget. This event has no default behavior and cannot be prevented, so the "on" or "after" moments are effectively equivalent (with on listeners being invoked before after listeners).
Parameters:
e <EventFacade> The Event Facade
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is false.

widget:render

widget:render ( e )
Lifcyle event for the render phase, fired prior to rendering the UI for the widget (prior to invoking the widget's renderer method).

Subscribers to the "on" moment of this event, will be notified before the widget is rendered.

Subscribers to the "after" moment of this event, will be notified after rendering is complete.

Parameters:
e <EventFacade> The Event Facade
Preventable: This event is preventable by method e.preventDefault(). The default function executed by this event is _defRenderFn.

widthChange

widthChange ( event )
Fires when the value for the configuration attribute 'width' 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:
event <Event.Facade> An Event Facade object with the following attribute specific properties added:
prevVal
The value of the attribute, prior to it being set
newVal
The value the attribute is to be set to
attrName
The name of the attribute being set
subAttrName
If setting a property within the attribute's value, the name of the sub-attribute property being set

Events inherited from Base:

destroy, destroyedChange, init, initializedChange,

Configuration Attributes

boundingBox - writeonce String | Node

The outermost DOM node for the Widget, used for sizing and positioning of a Widget as well as a containing element for any decorator elements used for skinning.

contentBox - writeonce String | Node

A DOM node that is a direct descendent of a Widget's bounding box that houses its content.

disabled - boolean

Boolean indicating if the Widget should be disabled. The disabled implementation is left to the specific classes extending widget.
Default Value: false

focused - boolean

Boolean indicating if the Widget, or one of its descendants, has focus.
Default Value: false

height - {String | Number}

String with units, or number, representing the height of the Widget. If a number is provided, the default unit, defined by the Widgets DEF_UNIT, property is used.
Default Value: EMPTY_STR

id - writeonce String

Default Value: Generated using guid()

locale - String

The default locale for the widget. NOTE: Using get/set on the "strings" attribute will return/set strings for this locale.
Deprecated Use Y.config.lang and Y.Intl externalization support
Default Value: "en"

render - writeonce boolean | Node

Whether or not to render the widget automatically after init, and optionally, to which parent node.

rendered - boolean

Flag indicating whether or not this Widget has been through the render lifecycle phase.
Default Value: false

srcNode - writeonce String | Node

The DOM node to parse for configuration values, passed to the Widget's HTML_PARSER definition

strings - Object

Collection of strings used to label elements of the Widget's UI.
Default Value: null

tabIndex - Number

Number (between -32767 to 32767) indicating the widget's position in the default tab flow. The value is used to set the "tabIndex" attribute on the widget's bounding box. Negative values allow the widget to receive DOM focus programmatically (by calling the focus method), while being removed from the default tab flow. A value of null removes the "tabIndex" attribute from the widget's bounding box.
Default Value: 0

visible - boolean

Boolean indicating weather or not the Widget is visible.
Default Value: TRUE

width - {String | Number}

String with units, or number, representing the width of the Widget. If a number is provided, the default unit, defined by the Widgets DEF_UNIT, property is used.
Default Value: EMPTY_STR

Configuration attributes inherited from Base:

destroyed initialized

Classes

Copyright © 2010 Yahoo! Inc. All rights reserved.