Element

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.

 

On this page

 

·Examples
·Moduleindex

 

 

 

Examples

 

 

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

 

 

 

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

  // -> div#message

 

 

 

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

  // -> 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});

 

 

Isn’t that just beautiful?!

 

 


Moduleindex

 

addClassName

 

addClassName(element, className) -> HTMLElement 

 

Adds a CSS class to element.

 

addMethods

 

addMethods([methods])

 

Takes a hash of methods and makes them available as methods of extended elements and of the Element object.

 

ancestors

 

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

 

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

 

classNames

 

classNames(element) -> [className...]

 

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

 

cleanWhitespace

 

cleanWhitespace(element) -> HTMLElement

 

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

 

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.

 

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

 

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

 

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

 

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

 

getHeight

 

getHeight(element) -> Number

 

Finds and returns the computed height of element.

 

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.

 

immediateDescendants

 

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

 

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

 

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 an 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

 

observe(element, eventName, handler[, useCapture = false]) -> HTMLElement

 

Registers an event handler on element and returns element.

 

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.

 

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.

 

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 makeClipping() was applied. Returns element.

 

undoPositioned

 

undoPositioned(element) -> HTMLElement

 

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

 

up

 

up([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.

 

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;").

 


Prototype API 1.5.0 - prototypejs.org