Element Atom feed

The Element object sports a flurry of powerful DOM methods which you can access either as methods of Element (but that’s rather old-fashioned now) or directly as methods of an extended element (thanks to Element.extend for that added bit of syntactic sugar).

Before you pursue, you really should read “How Prototype extends the DOM” which will walk you through the arcane inner workings of Prototype’s magic DOM extension mechanism.

Examples


<div id="message" class=""></div>

// Toggle the CSS class name of div#message
$('message').addClassName('read');
// -> div#message

// You could also use a syntactic-sugar-free version:
Element.toggleClassName('message', 'read');
// -> div#message

Since most methods of Element return the element they are applied to, you can chain methods like so:


$('message').addClassName('read').update('I read this message!').setStyle({opacity: 0.5});

Element as a constructor
1.6

new Element(tagName[, attributes])

The Element object can be used to create new elements in a friendlier, more concise way than afforted by the built-in DOM methods. It returns an extended element, so you can chain a call to Element#update in order to set the element’s content.

A set of attribute/value pairs can be provided as an optional second argument; they’ll be set on the newly-created element using Element#writeAttribute.

The old way

var a = document.createElement('a');
a.setAttribute('class', 'foo');
a.setAttribute('href', '/foo.html');
a.appendChild(document.createTextNode("Next page"));

The new way

var a = new Element('a', { 'class': 'foo', href: '/foo.html' }).update("Next page");

Methods

absolutize
1.6

absolutize(element) -> HTMLElement

Turns element into an absolutely-positioned element without changing its position in the page layout.

addClassName

addClassName(element, className) -> HTMLElement 

Adds a CSS class to element.

addMethods

addMethods([methods])
addMethods(tagName, methods)

Takes a hash of methods and makes them available as methods of extended elements and of the Element object. The second usage form is for targeting a specific HTML element.

adjacent
1.6

Element.adjacent(element[, selectors...]) -> [HTMLElement...]
someElement.adjacent([selectors...]) -> [HTMLElement...]

Finds all siblings of the current element that match the given selector(s).

ancestors

ancestors(element) -> [HTMLElement...]

Collects all of element’s ancestors and returns them as an array of extended elements.

childElements
1.5.1

childElements(element) -> [HTMLElement...]

Collects all of the element's children and returns them as an array of extended elements.

classNames
deprecated

classNames(element) -> Enumerable

Returns a new instance of ClassNames, an Enumerable object used to read and write CSS class names of element.

cleanWhitespace

cleanWhitespace(element) -> HTMLElement

Removes all of element's text nodes which contain only whitespace. Returns element.

clonePosition
1.6

clonePosition(element, source[, options]) -> HTMLElement

Clones the position and/or dimensions of source onto element as defined by the optional argument options.

cumulativeOffset
1.6

cumulativeOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns the offsets of element from the top left corner of the document.

cumulativeScrollOffset
1.6

cumulativeScrollOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Calculates the cumulative scroll offset of an element in nested scrolling containers.

descendantOf

descendantOf(element, ancestor) -> Boolean 

Checks if element is a descendant of ancestor.

descendants

descendants(element) -> [HTMLElement...]

Collects all of element’s descendants and returns them as an array of extended elements.

down

down(element[, cssRule][, index = 0]) -> HTMLElement | undefined

Returns element’s first descendant (or the n-th descendant if index is specified) that matches cssRule. If no cssRule is provided, all descendants are considered. If no descendant matches these criteria, undefined is returned.

empty

empty(element) -> Boolean

Tests whether element is empty (i.e. contains only whitespace).

extend

extend(element)

Extends element with all of the methods contained in Element.Methods and Element.Methods.Simulated. If element is an input, textarea or select tag, it will also be extended with the methods from Form.Element.Methods. If it is a form tag, it will also be extended with Form.Methods.

fire
1.6.0

fire(eventName[, memo]) -> Event

Fires a custom event with the current element as its target.

firstDescendant
1.5.1

firstDescendant(element) -> HTMLElement

Returns the first child that is an element. This is opposed to firstChild DOM property which will return any node (whitespace in most usual cases).

getDimensions

getDimensions(element) -> {height: Number, width: Number}

Finds the computed width and height of element and returns them as key/value pairs of an object.

getElementsByClassName
deprecated

getElementsByClassName(element, className) -> [HTMLElement...]

Fetches all of element’s descendants which have a CSS class of className and returns them as an array of extended elements.

getElementsBySelector
deprecated

getElementsBySelector(element, selector...) -> [HTMLElement...]

Takes an arbitrary number of CSS selectors (strings) and returns an array of extended children of element that match any of them.

getHeight

getHeight(element) -> Number

Finds and returns the computed height of element.

getOffsetParent
1.6

getOffsetParent(element) -> HTMLElement

Returns element’s closest positioned ancestor. If none is found, the body element is returned.

getStyle

getStyle(element, property) -> String | null

Returns the given CSS property value of element. property can be specified in either of its CSS or camelized form.

getWidth

getWidth(element) -> Number

Finds and returns the computed width of element.

hasClassName

hasClassName(element, className) -> Boolean

Checks whether element has the given CSS className.

hide

hide(element) -> HTMLElement

Hides and returns element.

identify
1.6

identify(element) -> id

returns element’s id attribute if it exists, or sets and returns a unique, auto-generated id.

immediateDescendants
deprecated

immediateDescendants(element) -> [HTMLElement...]

Collects all of the element’s immediate descendants (i.e. children) and returns them as an array of extended elements.

insert
1.6

insert(element, { position: content }) -> HTMLElement
insert(element, content) -> HTMLElement

Inserts content before, after, at the top of, or at the bottom of element, as specified by the position property of the second argument. If the second argument is the content itself, insert will append it to element.

inspect

inspect(element) -> String

Returns the debug-oriented string representation of element.

makeClipping

makeClipping(element) -> HTMLElement

Simulates the poorly supported CSS clip property by setting element's overflow value to 'hidden'. Returns element.

makePositioned

makePositioned(element) -> HTMLElement

Allows for the easy creation of CSS containing block by setting element's CSS position to 'relative' if its initial position is either 'static' or undefined. Returns element.

match

match(element, selector) -> Boolean

Checks if element matches the given CSS selector.

next

next(element[, cssRule][, index = 0]) -> HTMLElement | undefined

Returns element’s following sibling (or the index’th one, if index is specified) that matches cssRule. If no cssRule is provided, all following siblings are considered. If no following sibling matches these criteria, undefined is returned.

nextSiblings

nextSiblings(element) -> [HTMLElement...]

Collects all of element’s next siblings and returns them as an array of extended elements.

observe

Element.observe(element, eventName, handler) -> HTMLElement
someElement.observe(eventName, handler) -> HTMLElement

Registers an event handler on element and returns element.

positionedOffset
1.6

positionedOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns element’s offset relative to its closest positioned ancestor (the element that would be returned by Element#getOffsetParent).

previous

previous(element[, cssRule][, index = 0]) -> HTMLElement | undefined

Returns element's previous sibling (or the index'th one, if index is specified) that matches cssRule. If no cssRule is provided, all previous siblings are considered. If no previous sibling matches these criteria, undefined is returned.

previousSiblings

previousSiblings(element) -> [HTMLElement...]

Collects all of element’s previous siblings and returns them as an array of extended elements.

readAttribute

readAttribute(element, attribute) -> String | null

Returns the value of element's attribute or null if attribute has not been specified.

recursivelyCollect

recursivelyCollect(element, property) -> [HTMLElement...]

Recursively collects elements whose relationship is specified by property. property has to be a property (a method won’t do!) of element that points to a single DOM node. Returns an array of extended elements.

relativize
1.6

relativize(element) -> HTMLElement

Turns element into an relatively-positioned element without changing its position in the page layout.

remove

remove(element) -> HTMLElement

Completely removes element from the document and returns it.

removeClassName

removeClassName(element, className) -> HTMLElement

Removes element’s CSS className and returns element.

replace

replace(element[, html]) -> HTMLElement

Replaces element by the content of the html argument and returns the removed element.

scrollTo

scrollTo(element) -> HTMLElement

Scrolls the window so that element appears at the top of the viewport. Returns element.

select
1.6

select(element, selector...) -> [HTMLElement...]

Takes an arbitrary number of CSS selectors (strings) and returns an array of extended descendants of element that match any of them.

setOpacity
1.5.1

Element.setOpacity(element, opacity) -> [HTMLElement...]
someElement.setOpacity(opacity) -> [HTMLElement...]

Sets the visual opacity of an element while working around inconsistencies in various browsers. The opacity argument should be a floating point number, where the value of 0 is fully transparent and 1 is fully opaque.

setStyle

setStyle(element, styles) -> HTMLElement

Modifies element’s CSS style properties. Styles are passed as a hash of property-value pairs in which the properties are specified in their camelized form.

show

show(element) -> HTMLElement

Displays and returns element.

siblings

siblings(element) -> [HTMLElement...]

Collects all of element’s siblings and returns them as an array of extended elements.

stopObserving

stopObserving(element, eventName, handler) -> HTMLElement

Unregisters handler and returns element.

toggle

toggle(element) -> HTMLElement

Toggles the visibility of element.

toggleClassName

toggleClassName(element, className) -> HTMLElement

Toggles element’s CSS className and returns element.

undoClipping

undoClipping(element) -> HTMLElement

Sets element’s CSS overflow property back to the value it had before Element.makeClipping() was applied. Returns element.

undoPositioned

undoPositioned(element) -> HTMLElement

Sets element back to the state it was before Element.makePositioned was applied to it. Returns element.

up

up(element, [cssRule][, index = 0]) -> HTMLElement | undefined

Returns element’s first ancestor (or the index’th ancestor, if index is specified) that matches cssRule. If no cssRule is provided, all ancestors are considered. If no ancestor matches these criteria, undefined is returned.

update

update(element[, newContent]) -> HTMLElement

Replaces the content of element with the provided newContent argument and returns element.

viewportOffset
1.6

viewportOffset(element) -> [Number, Number] also accessible as { left: Number, top: Number }

Returns the X/Y coordinates of element relative to the viewport.

visible

visible(element) -> Boolean

Returns a Boolean indicating whether or not element is visible (i.e. whether its inline style property is set to "display: none;").

wrap
1.6

Element.wrap(element, wrapper[, attributes]) -> HTMLElement
someElement.wrap(wrapper[, attributes]) -> HTMLElement

Wraps an element inside another, then returns the wrapper.

writeAttribute
1.6

writeAttribute(element, attribute[, value = true]) -> HTMLElement
writeAttribute(element, attributes) -> HTMLElement

Adds, specifies or removes attributes passed as either a hash or a name/value pair.