Prototype JavaScript framework

class Element

Related utilities

$

Methods

Constructor

new Element(tagName[, attributes])
  • tagName (String) – The name of the HTML element to create.
  • attributes (Object) – A list of attribute/value pairs to set on the element.

Creates an HTML element with tagName as the tag name.

Instance methods

  • absolutize

    Element#absolutize() -> Element
Element.absolutize(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • addClassName

    Element#addClassName(className) -> Element
Element.addClassName(element, className) -> Element

    Adds a CSS class to element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • ancestors

    Element#ancestors() -> [Element...]
Element.ancestors(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • childElements

    Element#childElements() -> [Element...]
Element.childElements(element) -> [Element...]

    Alias of:

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • childElements

    Element#childElements() -> [Element...]
Element.childElements(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • classNames

    Element#classNames() -> [String...]
Element.classNames(element) -> [String...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • cleanWhitespace

    Element#cleanWhitespace() -> Element
Element.cleanWhitespace(element) -> Element

    Removes whitespace-only text node children from element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • clonePosition

    Element#clonePosition(source[, options]) -> Element
Element.clonePosition(element, source[, options]) -> Element

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

    Valid keys for options are: setLeft, setTop, setWidth, and setHeight (all booleans which default to true); and offsetTop and offsetLeft (numbers which default to 0). Use these to control which aspects of source's layout are cloned and how much to offset the resulting position of element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • cumulativeOffset

    Element#cumulativeOffset() -> Array
Element.cumulativeOffset(element) -> Array

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

    Returns an array in the form of [leftValue, topValue]. Also accessible as properties: { left: leftValue, top: topValue }.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • descendantOf

    Element#descendantOf(ancestor) -> Boolean
Element.descendantOf(element, ancestor) -> Boolean

    Checks if element is a descendant of ancestor.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • descendants

    Element#descendants() -> [Element...]
Element.descendants(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • down

    Element#down([, expression[, index = 0]]) -> Element
Element.down(element[, expression[, index = 0]]) -> Element
    • expression (String) – A CSS selector.

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • empty

    Element#empty() -> Element
Element.empty(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • fire

    Element#fire(eventName[, memo[, bubble = true]]) -> Event
Element.fire(element, eventName[, memo[, bubble = true]]) -> Event

    See Event.fire.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • firstDescendant

    Element#firstDescendant() -> Element
Element.firstDescendant(element) -> Element

    Returns the first child that is an element.

    This is opposed to the firstChild DOM property, which will return any node, including text nodes.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getDimensions

    Element#getDimensions() -> Object
Element.getDimensions(element) -> Object

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getElementsBySelector

    Element#getElementsBySelector(selector) -> [Element...]
Element.getElementsBySelector(element, selector) -> [Element...]

    Alias of:

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getHeight

    Element#getHeight() -> Number
Element.getHeight(element) -> Number

    Returns the height of element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getOffsetParent

    Element#getOffsetParent() -> Element
Element.getOffsetParent(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getOpacity

    Element#getOpacity() -> String | null
Element.getOpacity(element) -> String | null

    Returns the opacity of the element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getStorage

    Element#getStorage() -> Hash
Element.getStorage(element) -> Hash

    Returns the Hash object that stores custom metadata for this element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getStyle

    Element#getStyle(style) -> String | null
Element.getStyle(element, style) -> String | null
    • style (String) – The property name to be retrieved.

    Returns the given CSS property value of element. The property can be specified in either its CSS form (font-size) or its camelized form (fontSize).

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • getWidth

    Element#getWidth() -> Number
Element.getWidth(element) -> Number

    Returns the width of element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • hasClassName

    Element#hasClassName(className) -> Boolean
Element.hasClassName(element, className) -> Boolean

    Checks whether element has the given CSS class name.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • hide

    Element#hide() -> Element
Element.hide(element) -> Element

    Sets display: none on element. Returns element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • identify

    Element#identify() -> String
Element.identify(element) -> String

    Returns element's ID. If element does not have an ID, one is generated, assigned to element, and returned.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • insert

    Element#insert(content) -> Element
Element.insert(element, content) -> Element

    Inserts content at a specific point relative to element.

    The content argument can be a string, in which case the implied insertion point is bottom. Or it can be an object that specifies one or more insertion points (e.g., { bottom: "foo", top: "bar" }).

    Accepted insertion points are before (as element's previous sibling); after (as element's next sibling); top (as element's first child); and bottom (as element's last child).

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • inspect

    Element#inspect() -> String
Element.inspect(element) -> String

    Returns the debug-oriented string representation of element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • makeClipping

    Element#makeClipping() -> Element
Element.makeClipping(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • makePositioned

    Element#makePositioned() -> Element
Element.makePositioned(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • match

    Element#match(selector) -> boolean
Element.match(element, selector) -> boolean
    • selector (String) – A CSS selector.

    Checks if element matches the given CSS selector.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • next

    Element#next([, expression[, index = 0]]) -> Element
Element.next(element[, expression[, index = 0]]) -> Element
    • expression (String) – A CSS selector.

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • nextSiblings

    Element#nextSiblings() -> [Element...]
Element.nextSiblings(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • observe

    Element#observe(eventName, handler) -> Element
Element.observe(element, eventName, handler) -> Element

    See Event.observe.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • positionedOffset

    Element#positionedOffset() -> Array
Element.positionedOffset(element) -> Array

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

    Returns an array in the form of [leftValue, topValue]. Also accessible as properties: { left: leftValue, top: topValue }.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • previous

    Element#previous([, expression[, index = 0]]) -> Element
Element.previous(element[, expression[, index = 0]]) -> Element
    • expression (String) – A CSS selector.

    Returns element’s first previous sibling (or the Nth, if index is specified) that matches expression. If no expression is provided, all previous siblings are considered. If none matches these criteria, undefined is returned.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • previousSiblings

    Element#previousSiblings() -> [Element...]
Element.previousSiblings(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • readAttribute

    Element#readAttribute(attributeName) -> String | null
Element.readAttribute(element, attributeName) -> String | null

    Returns the value of element's attribute with the given name.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • recursivelyCollect

    Element#recursivelyCollect(element, property) -> [Element...]

    Recursively collects elements whose relationship to element is specified by property. property has to be a property (a method won’t do!) of element that points to a single DOM node (e.g., nextSibling or parentNode).

  • relativize

    Element#relativize() -> Element
Element.relativize(element) -> Element

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

    Used to undo a call to Element.absolutize.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • remove

    Element#remove() -> Element
Element.remove(element) -> Element

    Completely removes element from the document and returns it.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • removeClassName

    Element#removeClassName(className) -> Element
Element.removeClassName(element, className) -> Element

    Removes a CSS class from element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • replace

    Element#replace([, newContent]) -> Element
Element.replace(element[, newContent]) -> Element

    Replaces element itself with newContent and returns element.

    Keep in mind that this method returns the element that has just been removed — not the element that took its place.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • retrieve

    Element#retrieve(key[, defaultValue]) -> ?
Element.retrieve(element, key[, defaultValue]) -> ?

    Retrieves custom metadata set on element with Element.store.

    If the value is undefined and defaultValue is given, it will be stored on the element as its new value for that key, then returned.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • scrollTo

    Element#scrollTo() -> Element
Element.scrollTo(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • select

    Element#select(selector...) -> [Element...]
Element.select(element, selector...) -> [Element...]
    • selector (String) – A CSS selector.

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • setOpacity

    Element#setOpacity(value) -> Element
Element.setOpacity(element, value) -> Element

    Sets the opacity of element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • setStyle

    Element#setStyle(styles) -> Element
Element.setStyle(element, styles) -> Element

    Modifies element’s CSS style properties.

    Styles are passed as an object of property-value pairs in which the properties are specified in their camelized form (e.g., fontSize).

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • show

    Element#show() -> Element
Element.show(element) -> Element

    Removes display: none on element. Returns element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • siblings

    Element#siblings() -> [Element...]
Element.siblings(element) -> [Element...]

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • stopObserving

    Element#stopObserving(element[, eventName[, handler]]) -> Element

    See Event.stopObserving.

  • store

    Element#store(key, value) -> Element
Element.store(element, key, value) -> Element

    Stores a key/value pair of custom metadata on the element.

    The metadata can later be retrieved with Element.retrieve.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • toggle

    Element#toggle() -> Element
Element.toggle(element) -> Element

    Toggles the visibility of element. Returns element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • toggleClassName

    Element#toggleClassName(className) -> Element
Element.toggleClassName(element, className) -> Element

    Toggles the presence of a CSS class on element.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • undoClipping

    Element#undoClipping() -> Element
Element.undoClipping(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • undoPositioned

    Element#undoPositioned() -> Element
Element.undoPositioned(element) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • up

    Element#up([, expression[, index = 0]]) -> Element
Element.up(element[, expression[, index = 0]]) -> Element
    • expression (String) – A CSS selector.

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • update

    Element#update([, newContent]) -> Element
Element.update(element[, newContent]) -> Element

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

    If newContent is omitted, the element's content is blanked out (i.e., replaced with an empty string).

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • viewportOffset

    Element#viewportOffset() -> Array
Element.viewportOffset(element) -> Array

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

    Returns an array in the form of [leftValue, topValue]. Also accessible as properties: { left: leftValue, top: topValue }.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • visible

    Element#visible() -> boolean
Element.visible(element) -> boolean

    Tells whether element is visible (i.e., whether its inline display CSS property is set to none.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • wrap

    Element#wrap(wrapper[, attributes]) -> Element
Element.wrap(element, wrapper[, attributes]) -> Element
    • wrapper (Element | String) – An element to wrap element inside, or else a string representing the tag name of an element to be created.
    • attributes (Object) – A set of attributes to apply to the wrapper element. Refer to the Element constructor for usage.

    Wraps an element inside another, then returns the wrapper.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • writeAttribute

    Element#writeAttribute(attribute[, value = true]) -> Element
Element.writeAttribute(element, attribute[, value = true]) -> Element

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

Class methods

  • addMethods

    Element.addMethods(methods) -> undefined

    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 adding methods only to specific tag names.

  • adjacent

    Element.adjacent(@element, selector...) -> [Element...]
    • selector (String) – A CSS selector.

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

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • cumulativeScrollOffset

    Element.cumulativeScrollOffset(@element) -> Array

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

    Returns an array in the form of [leftValue, topValue]. Also accessible as properties: { left: leftValue, top: topValue }.

    This method can be called either as an instance method or as a generic method. If calling as a generic, pass the instance in as the first argument.

  • extend

    Element.extend(element) -> 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 the methods from Form.Methods.