Element Atom feed
- absolutize
- addClassName
- addMethods
- adjacent
- ancestors
- childElements
- classNames
- cleanWhitespace
- clonePosition
- cumulativeOffset
- cumulativeScrollOffset
- descendantOf
- descendants
- down
- empty
- extend
- fire
- firstDescendant
- getDimensions
- getElementsByClassName
- getElementsBySelector
- getHeight
- getOffsetParent
- getStyle
- getWidth
- hasClassName
- hide
- identify
- immediateDescendants
- insert
- inspect
- makeClipping
- makePositioned
- match
- next
- nextSiblings
- observe
- positionedOffset
- previous
- previousSiblings
- readAttribute
- recursivelyCollect
- relativize
- remove
- removeClassName
- replace
- scrollTo
- select
- setOpacity
- setStyle
- show
- siblings
- stopObserving
- toggle
- toggleClassName
- undoClipping
- undoPositioned
- up
- update
- viewportOffset
- visible
- wrap
- writeAttribute
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.