Class YAHOO.ext.Element

Object
   |
   +--YAHOO.ext.Element

Direct Known Subclasses:

YAHOO.ext.Actor, YAHOO.ext.Animator

class YAHOO.ext.Element

Wraps around a DOM element and provides convenient access to Yahoo UI library functionality.

Usage:

 var el = YAHOO.ext.Element.get('myElementId');
 // or the shorter
 var el = getEl('myElementId');
 

- YAHOO.util.Dom
- YAHOO.util.Event
- YAHOO.util.CustomEvent
- YAHOO.util.Anim (optional) to support animation
- YAHOO.util.Motion (optional) to support animation
- YAHOO.util.Easing (optional) to support animation

Field Detail

autoBoxAdjust

Object autoBoxAdjust

Whether to automatically adjust width and height settings for box-model issues

defaultUnit

String defaultUnit

The default unit to append to CSS values where a unit isn't provided (Defaults to px).

id

String id

The DOM element ID

onMoved

CustomEvent onMoved

Fires when element moves. Uses fireDirect with signature: (oElement, newX, newY)

onResized

CustomEvent onResized

Fires when element is resized. Uses fireDirect with signature: (oElement, newWidth, newHeight)

onVisibilityChanged

CustomEvent onVisibilityChanged

Fires when visibility changes. Uses fireDirect with signature: (oElement, boolean isVisible)

DISPLAY

<static> Number DISPLAY

Visibility mode constant - Use display to hide element

VISIBILITY

<static> Number VISIBILITY

Visibility mode constant - Use visibility to hide element

YAHOO.ext.Element

YAHOO.ext.Element(<String> elementId, <Boolean> forceNew)

Parameters:
elementId -
forceNew - (optional) By default the constructor checks to see if there is already an instance of this element in the cache and if there is it returns the same instance. This will skip that check (useful for extending this class).

Requires:
- YAHOO.util.Dom
- YAHOO.util.Event
- YAHOO.util.CustomEvent
- YAHOO.util.Anim (optional) to support animation
- YAHOO.util.Motion (optional) to support animation
- YAHOO.util.Easing (optional) to support animation

addClass

void addClass(<String> className)

Add a CSS class to the element.

Parameters:
className - The CSS class to add

addHandler

void addHandler(<String> eventName, <Boolean> stopPropagation, <Function> handler, <Object> scope, <boolean> override)

Appends an event handler to this element and automatically prevents the default action, and if set stops propagation (bubbling) as well

Parameters:
eventName - The type of event to listen for
stopPropagation - Whether to also stopPropagation (bubbling)
handler - The method the event invokes
scope - (optional) An arbitrary object that will be passed as a parameter to the handler
override - (optional) If true, the obj passed in becomes the execution scope of the listener

addListener

void addListener(<String> eventName, <Function> handler, <Object> scope, <boolean> override)

Appends an event handler to this element

Parameters:
eventName - The type of event to listen for
handler - The method the event invokes
scope - (optional) An arbitrary object that will be passed as a parameter to the handler
override - (optional) If true, the obj passed in becomes the execution scope of the listener

addManagedListener

Object addManagedListener(<String> eventName, <Function> fn, <Object> scope, <boolean> override)

Append a managed listener - See YAHOO.ext.EventObject for more details.

Parameters:
eventName - The type of event to listen for
fn - The method the event invokes
scope - (optional) An arbitrary object that will be passed as a parameter to the handler
override - (optional) If true, the obj passed in becomes the execution scope of the listener

alignTo

void alignTo(<String/HTMLElement/YAHOO.ext.Element> element, <String> position, <Array> offsets, <Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Align this element with another element.

Parameters:
element - The element to align to.
position - The position to align to. Possible values are 'tl' - top left, 'tr' - top right, 'bl' - bottom left, and 'br' - bottom right.
offsets - (optional) Offset the positioning by [x, y]
animate - (optional) Animate the movement (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use.

animate

void animate(<Object> args, <Float> duration, <Function> onComplete, <Function> easing, <Function> animType)

Perform Yahoo UI animation on this element.

Parameters:
args - The YUI animation control args
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)
animType - (optional) YAHOO.util.Anim subclass to use. For YAHOO.ext.Element.prototype.example = YAHOO;.util.Motion

beginMeasure

void beginMeasure()

clearOpacity

void clearOpacity()

Clears any opacity settings from this element. Required in some cases for IE.

clearPositioning

void clearPositioning()

Clear positioning back to the default when the document was loaded

clip

void clip()

Clip overflow on the element - use unclip() to remove

enableDisplayMode

void enableDisplayMode()

Convenience method for setVisibilityMode(Element.DISPLAY)

endMeasure

void endMeasure()

focus

void focus()

Tries to focus the element. Any exceptions are caught.

getBorderWidth

Number getBorderWidth(<String> side)

Gets the width of the border(s) for the specified side(s)

Parameters:
side - Can be t, l, r, b or any combination of those to add multiple values. For example, passing lr would get the border (l)eft width + the border (r)ight width.

Returns:
The width of the sides passed added together

getBottom

String getBottom()

Gets the bottom Y coordinate of the element (element Y position + element height)

Returns:
The bottom position of the element

getBox

void getBox(contentBox)

Return a box {x, y, width, height} that can be used to set another elements size to match this element. If contentBox is true, a box for the content of the element is returned.

getCenterXY

Array getCenterXY(offsetScroll)

Calculates the x, y to center this element on the screen

Returns:
The x, y values [x, y]

getChildrenByClassName

Array getChildrenByClassName(<String> className, <String> tagName)

Gets an array of child YAHOO.ext.Element objects by class name and optional tagName

Parameters:
className -
tagName - (optional)

Returns:
The children

getChildrenByTagName

Array getChildrenByTagName(<String> tagName)

Gets an array of child YAHOO.ext.Element objects by tag name

Parameters:
tagName -

Returns:
The children

getHeight

Number getHeight()

Returns the offset height of the element

Returns:
The element's height

getLeft

Object getLeft()

Same as getX()

getPadding

Number getPadding(<String> side)

Gets the width of the padding(s) for the specified side(s)

Parameters:
side - Can be t, l, r, b or any combination of those to add multiple values. For example, passing lr would get the padding (l)eft + the padding (r)ight.

Returns:
The padding of the sides passed added together

getPositioning

void getPositioning()

Gets an object with all CSS positioning properties. Useful along with setPositioning() to get snapshot before performing an update and then restoring the element.

getRegion

Region getRegion()

Returns the region position of the given element. The element must be part of the DOM tree to have a region (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Returns:
A YAHOO.util.Region containing "top, left, bottom, right" member data.

getRight

String getRight()

Gets the right X coordinate of the element (element X position + element width)

Returns:
The left position of the element

getSize

Object} getSize()

Returns the size of the element

getStyle

String getStyle(name)

Normalizes currentStyle and ComputedStyle.

Parameters:
property - The style property whose value is returned.

Returns:
The current value of the style property for this element.

getTop

Object getTop()

Same as getY()

getUpdateManager

YAHOO.ext.UpdateManager getUpdateManager()

Gets this elements UpdateManager

Returns:
The UpdateManager

getWidth

Number getWidth()

Returns the offset width of the element

Returns:
The element's width

getX

Object getX()

Gets the current X position of the element based on page coordinates. Element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

getXY

Object getXY()

Gets the current position of the element based on page coordinates. Element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

getY

Object getY()

Gets the current Y position of the element based on page coordinates. Element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

hasClass

Boolean hasClass(<String> className)

Checks if a CSS class is in use by the element.

Parameters:
className - The CSS class to check

Returns:
true or false

hide

void hide(<Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Hide this element - Uses display mode to determine whether to use "display" or "visibility". See setVisible().

Parameters:
animate - (optional) Animate (fade) the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

isBorderBox

void isBorderBox()

Tests various css rules/browsers to determine if this element uses a border box

isVisible

Boolean isVisible(<Boolean> deep)

Checks whether the element is currently visible using both visibility and display properties.

Parameters:
deep - True to walk the dom and see if parent elements are hidden

Returns:
Whether the element is currently visible

mon

Object mon(<String> eventName, <Function> fn, <Object> scope, <boolean> override)

Append a managed listener (shorthanded for addManagedListener())

Parameters:
eventName - The type of event to listen for
fn - The method the event invokes
scope - (optional) An arbitrary object that will be passed as a parameter to the handler
override - (optional) If true, the obj passed in becomes the execution scope of the listener

move

void move(<String> direction, <Number> distance, <Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Move this element relative to it's current position.

Parameters:
direction - Possible values YAHOO.ext.Element.prototype.are = 'left'; 'right', 'up', 'down'.
distance - How far to move the element in pixels
animate - (optional) Animate the movement (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use.

moveTo

void moveTo(<Number> x, <Number> y, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the position of the element in page coordinates, regardless of how the element is positioned. The element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Parameters:
x - X value for new position (coordinates are page-based)
y - Y value for new position (coordinates are page-based)
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

on

void on(<String> eventName, <Function> handler, <Object> scope, <boolean> override)

Appends an event handler to this element (Same as addListener)

Parameters:
eventName - The type of event to listen for
handler - The method the event invokes
scope - (optional) An arbitrary object that will be passed as a parameter to the handler
override - (optional) If true, the obj passed in becomes the execution scope of the listener

radioClass

void radioClass(className)

Adds the passed className to this element and removes the class from all siblings

removeAllListeners

void removeAllListeners()

Removes all previous added listeners from this element

removeClass

void removeClass(<String> className)

Removes a CSS class from the element.

Parameters:
className - The CSS class to remove

removeListener

void removeListener(eventName, handler)

Removes an event handler from this element

Parameters:
sType - the type of event to remove
fn - the method the event invokes

replaceClass

void replaceClass(<String> oldClassName, <String> newClassName)

Replaces a CSS class on the element with another.

Parameters:
oldClassName - The CSS class to replace
newClassName - The replacement CSS class

setAbsolutePositioned

void setAbsolutePositioned(<Number> zIndex)

Set the element as absolute positioned with the specified z-index

Parameters:
zIndex - (optional)

setBottom

void setBottom(bottom)

Set the element's css bottom style

Parameters:
top - The bottom CSS property value

setBounds

void setBounds(<Number> x, <Number> y, <Number> width, <Number> height, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Sets the element's position and size in one shot. If animation is true then width, height, x and y will be animated concurrently.

Parameters:
x - X value for new position (coordinates are page-based)
y - Y value for new position (coordinates are page-based)
width - The new width
height - The new height
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setBox

void setBox(<Object> box, <Boolean> adjust, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Sets the element's box. Use getBox() on another element to get a box obj. If animate is true then width, height, x and y will be animated concurrently.

Parameters:
box - The box to fill {x, y, width, height}
adjust - (optional) Whether to adjust for box-model issues automatically
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setHeight

void setHeight(<Number> height, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the height of the element

Parameters:
height - The new height
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeOut if height is larger or YAHOO.util.Easing.easeIn if it is smaller)

setLeft

void setLeft(<String> left)

Set the element's X position directly using CSS style (instead of setX())

Parameters:
left - The left CSS property value

setLocation

void setLocation(<Number> x, <Number> y, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the position of the element in page coordinates, regardless of how the element is positioned. The element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Parameters:
x - X value for new position (coordinates are page-based)
y - Y value for new position (coordinates are page-based)
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setOpacity

void setOpacity(<Float> opacity, <Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Set the opacity of the element

Parameters:
opacity - The new opacity. 0 = transparent, .5 = 50% visibile, 1 = fully visible, etc
animate - (optional) Animate (fade) the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeOut if height is larger or YAHOO.util.Easing.easeIn if it is smaller)

setPositioning

void setPositioning(positionCfg)

Set positioning with an object returned by getPositioning().

setRegion

void setRegion(<YAHOO.util.Region> region, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Sets the element's position and size the the specified region. If animation is true then width, height, x and y will be animated concurrently.

Parameters:
region - The region to fill
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setRelativePositioned

void setRelativePositioned(<Number> zIndex)

Set the element as relative positioned with the specified z-index

Parameters:
zIndex - (optional)

setRight

void setRight(right)

Set the element's css right style

Parameters:
left - The right CSS property value

setSize

void setSize(<Number> width, <Number> height, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the size of the element. If animation is true, both width an height will be animated concurrently.

Parameters:
width - The new width
height - The new height
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setStyle

void setStyle(name, value)

Wrapper for setting style properties

Parameters:
property - The style property to be set.
val - The value to apply to the given property.

setTop

void setTop(<String> top)

Set the element's Y position directly using CSS style (instead of setY())

Parameters:
top - The top CSS property value

setVisibilityMode

void setVisibilityMode(visMode)

Sets the elements visibility mode. When setVisible() is called it will use this to determine whether to set the visibility or the display property.

Parameters:
visMode - Element.VISIBILITY or Element.DISPLAY

setVisible

void setVisible(<Boolean> visible, <Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Sets the visibility of the element (see details). If the visibilityMode is set to Element.DISPLAY, it will use the display property to hide the element, otherwise it uses visibility. The default is to hide and show using the visibility property.

Parameters:
visible - Whether the element is visible
animate - (optional) Fade the element in or out (Default is false)
duration - (optional) How long the fade effect lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeOut for hiding or YAHOO.util.Easing.easeIn for showing)

setWidth

void setWidth(<Number> width, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the width of the element

Parameters:
width - The new width
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeOut if width is larger or YAHOO.util.Easing.easeIn if it is smaller)

setX

void setX(x)

Sets the X position of the element based on page coordinates. Element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Parameters:
The - X position of the element

setXY

void setXY(<Array> pos, <Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Set the position of the element in page coordinates, regardless of how the element is positioned. The element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Parameters:
pos - Contains X & Y [x, y] values for new position (coordinates are page-based)
animate - (optional) Animate the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

setY

void setY(y)

Sets the Y position of the element based on page coordinates. Element must be part of the DOM tree to have page coordinates (YAHOO.ext.Element.prototype.display = none;or elements not appended return false).

Parameters:
The - Y position of the element

show

void show(<Boolean> animate, <Float> duration, <Function> onComplete, <Function> easing)

Show this element - Uses display mode to determine whether to use "display" or "visibility". See setVisible().

Parameters:
animate - (optional) Animate (fade in) the transition (Default is false)
duration - (optional) How long the animation lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeBoth)

toggle

void toggle(<Boolean> animate, <float> duration, <Function> onComplete, <Function> easing)

Toggles the elements visibility or display, depending on visibility mode.

Parameters:
animate - (optional) Fade the element in or out (Default is false)
duration - (optional) How long the fade effect lasts. (Defaults to .35 seconds)
onComplete - (optional) Function to call when animation completes.
easing - (optional) YAHOO.util.Easing method to use. (Defaults to YAHOO.util.Easing.easeOut for hiding or YAHOO.util.Easing.easeIn for showing)

toggleClass

void toggleClass(className)

unclip

void unclip()

Return clipping (overflow) to original clipping when the document loaded

update

void update(<String> html, <Boolean> loadScripts)

Update the innerHTML of this element, optionally searching for and processing scripts

Parameters:
html - The new HTML
loadScripts - (optional) true to look for and process scripts

get

<static> Element get(<String/HTMLElement/Element> el, <Boolean> autoGenerateId)

Static method to retreive Element objects. Uses simple caching to consistently return the same object. Automatically fixes if an object was recreated with the same id via AJAX or DOM.

Parameters:
el - The id of the element or the element to wrap (must have an id). If you pass in an element, it is returned
autoGenerateId - (optional) Set this flag to true if you are passing an element without an id (like document.body). It will auto generate an id if one isn't present.

Returns:
The element object