API: element YAHOO.util.Element (YUI Library)

# Yahoo! UI Library

### element 2.8.1

Yahoo! UI Library > element > YAHOO.util.Element
Search:
Filters Show Private Show Protected Show Deprecated

## Class YAHOO.util.Element - uses YAHOO.util.AttributeProvider

Known Subclasses:
  YAHOO.widget.Toolbar YAHOO.util.Resize YAHOO.widget.DataTable YAHOO.widget.Layout YAHOO.widget.ImageCropper YAHOO.widget.SimpleEditor YAHOO.widget.ProgressBar YAHOO.widget.SWF YAHOO.widget.Carousel YAHOO.widget.Tab YAHOO.widget.LayoutUnit YAHOO.widget.ColorPicker YAHOO.widget.ToolbarButton YAHOO.widget.ButtonGroup YAHOO.widget.ProfilerViewer YAHOO.widget.Button YAHOO.widget.TabView

Element provides an wrapper object to simplify adding event listeners, using dom methods, and managing attributes.

### Constructor

YAHOO.util.Element `( el , map )`

Parameters:
  `el <HTMLElement | String>` The html element that represents the Element.
  `map <Object>` A key-value map of initial config names and values

### Properties

#### DOM_EVENTS - `Object`

Dom events supported by the Element instance.

#### Properties inherited from YAHOO.util.AttributeProvider:

`_configs`

#### Properties inherited from YAHOO.util.EventProvider:

`__yui_events, __yui_subscribers`

### Methods

#### _setHTMLAttrConfig

`private void _setHTMLAttrConfig ( element , key , map )`
Sets the value of the property and fires beforeChange and change events.

Parameters:
  `element <YAHOO.util.Element>` The Element instance to register the config to.
  `key <String>` The name of the config to register
  `map <Object>` A key-value map of the config's params

#### addClass

`void addClass ( className )`
Wrapper for Dom method.

Parameters:
  `className <String>` The className to add

#### addListener

`void addListener ( type , fn , obj , scope )`
Adds a listener for the given event. These may be DOM or customEvent listeners. Any event that is fired via fireEvent can be listened for. All handlers receive an event object.

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The handler to call when the event fires
  `obj <Any>` A variable to pass to the handler
  `scope <Object>` The object to use for the scope of the handler

#### appendChild

`HTMLElement appendChild ( child )`
Wrapper for HTMLElement method.

Parameters:
  `child <YAHOO.util.Element || HTMLElement>` The element to append.

Returns: `HTMLElement`
  The appended DOM element.

#### appendTo

`HTMLElement appendTo ( parentNode , before )`
Appends the HTMLElement into either the supplied parentNode.

Parameters:
  `parentNode <HTMLElement | Element>` The node to append to
  `before <HTMLElement | Element>` An optional node to insert before

Returns: `HTMLElement`
  The appended DOM element.

#### delegate

`boolean delegate ( type , fn , filter , obj , scope )`
Appends a delegated event listener. Delegated event listeners receive two arguments by default: the DOM event and the element specified by the filtering function or CSS selector. (Note: Using the delegate method requires the element-delegate module. Using CSS selectors as the filtering criteria for delegated event listeners requires inclusion of the Selector Utility.)

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The handler to call when the event fires
  `filter <Function|string>` Function or CSS selector used to determine for what element(s) the event listener should be called. When a function is specified, the function should return an HTML element. Using a CSS Selector requires the inclusion of the CSS Selector Utility.
  `obj <Any>` A variable to pass to the handler
  `scope <Object>` The object to use for the scope of the handler

Returns: `boolean`
  Returns true if the delegated event listener was added successfully

#### fireQueue

`void fireQueue ( )`
Apply any queued set calls.

#### getElementsByClassName

`Array getElementsByClassName ( className , tag )`
Wrapper for Dom method.

Parameters:
  `className <String>` The className to collect
  `tag <String>` (optional) The tag to use in conjunction with class name

Returns: `Array`
  Array of HTMLElements

#### getElementsByTagName

`HTMLCollection getElementsByTagName ( tag )`
Wrapper for HTMLElement method.

Parameters:
  `tag <String>` The tagName to collect

Returns: `HTMLCollection`
  A collection of DOM elements.

#### getStyle

`String getStyle ( property )`
Wrapper for Dom method.

Parameters:
  `property <String>` The style property to retrieve

Returns: `String`
  The current value of the property

#### hasChildNodes

`Boolean hasChildNodes ( )`
Wrapper for HTMLElement method.

Returns: `Boolean`
  Whether or not the element has childNodes

#### hasClass

`Boolean hasClass ( className )`
Wrapper for Dom method.

Parameters:
  `className <String>` The className to add

Returns: `Boolean`
  Whether or not the element has the class name

#### initAttributes

`void initAttributes ( map )`
Registers Element specific attributes.

Parameters:
  `map <Object>` A key-value map of initial attribute configs

#### insertBefore

`HTMLElement insertBefore ( element , before )`
Wrapper for HTMLElement method.

Parameters:
  `element <HTMLElement>` The HTMLElement to insert
  `before <HTMLElement>` The HTMLElement to insert the element before.

Returns: `HTMLElement`
  The inserted DOM element.

#### on

`void on ( type , fn , obj , scope )`
Alias for addListener

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The function call when the event fires
  `obj <Any>` A variable to pass to the handler
  `scope <Object>` The object to use for the scope of the handler

#### removeChild

`HTMLElement removeChild ( child )`
Wrapper for HTMLElement method.

Parameters:
  `child <HTMLElement>` The HTMLElement to remove

Returns: `HTMLElement`
  The removed DOM element.

#### removeClass

`void removeClass ( className )`
Wrapper for Dom method.

Parameters:
  `className <String>` The className to remove

#### removeDelegate

`boolean removeDelegate ( type , fn )`
Remove a delegated event listener

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The function call when the event fires

Returns: `boolean`
  Returns true if the unbind was successful, false otherwise.

#### removeListener

`void removeListener ( type , fn )`
Remove an event listener

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The function call when the event fires

#### replaceChild

`HTMLElement replaceChild ( newNode , oldNode )`
Wrapper for HTMLElement method.

Parameters:
  `newNode <HTMLElement>` The HTMLElement to insert
  `oldNode <HTMLElement>` The HTMLElement to replace

Returns: `HTMLElement`
  The replaced DOM element.

#### replaceClass

`void replaceClass ( oldClassName , newClassName )`
Wrapper for Dom method.

Parameters:
  `oldClassName <String>` The className to replace
  `newClassName <String>` The className to add

#### setStyle

`void setStyle ( property , value )`
Wrapper for Dom method.

Parameters:
  `property <String>` The style property to set
  `value <String>` The value to apply to the style property

#### subscribe

`void subscribe ( type , fn , obj , scope )`
Alias for addListener

Parameters:
  `type <String>` The name of the event to listen for
  `fn <Function>` The function call when the event fires
  `obj <Any>` A variable to pass to the handler
  `scope <Object>` The object to use for the scope of the handler

#### Methods inherited from YAHOO.util.AttributeProvider:

`configureAttribute, fireBeforeChangeEvent, fireChangeEvent, get, getAttributeConfig, getAttributeKeys, refresh, register, resetAttributeConfig, resetValue, set, setAttributeConfig, setAttributes`

#### Methods inherited from YAHOO.util.EventProvider:

`createEvent, fireEvent, hasEvent, subscribe, unsubscribe, unsubscribeAll`

### Events

#### appendTo

`appendTo ( )`
Fires after the Element is appended to another Element.

See: Element.addListener

Event fields:
`<String> type` appendTo
`<HTMLElement/Element> target` the HTMLElement/Element being appended to

Usage:
`var handler = function(e) {var target = e.target};
myTabs.addListener('appendTo', handler);`

#### available

`available ( )`
Fires when the Element's HTMLElement can be retrieved by Id.

See: Element.addListener

Event fields:
`<String> type` available
`<HTMLElement> target` the HTMLElement bound to this Element instance

Usage:
`var handler = function(e) {var target = e.target};
myTabs.addListener('available', handler);`

#### beforeAppendTo

`beforeAppendTo ( )`
Fires before the Element is appended to another Element.

See: Element.addListener

Event fields:
`<String> type` beforeAppendTo
`<HTMLElement/Element> target` the HTMLElement/Element being appended to

Usage:
`var handler = function(e) {var target = e.target};
myTabs.addListener('beforeAppendTo', handler);`

#### beforeElementChange

`beforeElementChange ( event )`
Fires before the value for the configuration attribute 'element' changes. Return false to cancel the attribute change.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

#### contentReady

`contentReady ( )`
Fires when the Element's HTMLElement subtree is rendered.

See: Element.addListener

Event fields:
`<String> type` contentReady
`<HTMLElement> target` the HTMLElement bound to this Element instance

Usage:
`var handler = function(e) {var target = e.target};
myTabs.addListener('contentReady', handler);`

#### elementChange

`elementChange ( event )`
Fires when the value for the configuration attribute 'element' changes.

Parameters:
  `event <{oldValue: any, newValue: any}>` An object containing the previous attribute value and the new value.

### Configuration Attributes

#### element `- HTMLElement`

The HTMLElement the Element instance refers to.

Copyright © 2010 Yahoo! Inc. All rights reserved.