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.

Class methods

  • absolutize #

    Element.absolutize(element) ⇒ Element
    Element#absolutize() ⇒ 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(element, className) ⇒ Element
    Element#addClassName(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.

  • addMethods #

    Element.addMethods(methods) ⇒ undefined
    Element.addMethods(tagName, 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…]
    Element#adjacent(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.

  • ancestors #

    Element.ancestors(element) ⇒ [Element…]
    Element#ancestors() ⇒ [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…]
    Element#childElements() ⇒ [Element…]

    Alias of: Element.immediateDescendants

    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(element) ⇒ [String…]
    Element#classNames() ⇒ [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
    Element#cleanWhitespace() ⇒ 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.

  • clone #

    Element.clone(element, deep) ⇒ Element
    Element#clone(deep) ⇒ Element
    • deep (Boolean) – Whether to clone element's descendants as well.

    Returns a duplicate of element.

    A wrapper around DOM Level 2 Node#cloneNode, Element#clone cleans up any expando properties defined by Prototype.

    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(element, source[, options]) ⇒ Element
    Element#clonePosition(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(element) ⇒ Array
    Element#cumulativeOffset() ⇒ 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.

  • cumulativeScrollOffset #

    Element.cumulativeScrollOffset(element) ⇒ Array
    Element#cumulativeScrollOffset() ⇒ 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.

  • descendantOf #

    Element.descendantOf(element, ancestor) ⇒ Boolean
    Element#descendantOf(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…]
    Element#descendants() ⇒ [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(element[, expression[, index = 0]]) ⇒ Element
    Element#down([expression[, index = 0]]) ⇒ Element
    Element#down([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
    Element#empty() ⇒ 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.

  • 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.

  • fire #

    Element.fire(element, eventName[, memo[, bubble = true]]) ⇒ Event
    Element#fire(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
    Element#firstDescendant() ⇒ 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(element) ⇒ Object
    Element#getDimensions() ⇒ 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(element, selector) ⇒ [Element…]
    Element#getElementsBySelector(selector) ⇒ [Element…]

    Alias of: Element.select

    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(element) ⇒ Number
    Element#getHeight() ⇒ 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
    Element#getOffsetParent() ⇒ 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(element) ⇒ String | null
    Element#getOpacity() ⇒ 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(element) ⇒ Hash
    Element#getStorage() ⇒ 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(element, style) ⇒ String | null
    Element#getStyle(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(element) ⇒ Number
    Element#getWidth() ⇒ 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(element, className) ⇒ Boolean
    Element#hasClassName(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
    Element#hide() ⇒ 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(element) ⇒ String
    Element#identify() ⇒ 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.

  • immediateDescendants #

    Element.immediateDescendants(element) ⇒ [Element…]
    Element#immediateDescendants() ⇒ [Element…]

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

    Aliased as: Element.childElements

    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(element, content) ⇒ Element
    Element#insert(content) ⇒ Element

    Inserts content above, below, at the top, and/or at the bottom of the given element, depending on the option(s) given.

    insert accepts content in any of these forms:

    • String: A string of HTML to be parsed and rendered
    • Element: An Element instance to insert
    • ...any object with a toElement method: The method is called and the resulting element used
    • ...any object with a toHTML method: The method is called and the resulting HTML string is parsed and rendered

    The content argument can be the content to insert, in which case the implied insertion point is bottom, or 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)
    • bottom (as element's last child)
    Examples

    Insert the given HTML at the bottom of the element (using the default):

    $('myelement').insert("<p>HTML to append</p>");

$('myelement').insert({
  top: new Element('img', {src: 'logo.png'})
});

    Put hrs before and after the element:

    $('myelement').insert({
  before: "<hr>",
  after: "<hr>"
});

    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(element) ⇒ String
    Element#inspect() ⇒ 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
    Element#makeClipping() ⇒ 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
    Element#makePositioned() ⇒ 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(element, selector) ⇒ boolean
    Element#match(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(element[, expression[, index = 0]]) ⇒ Element
    Element#next([expression[, index = 0]]) ⇒ Element
    Element#next([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…]
    Element#nextSiblings() ⇒ [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(element, eventName, handler) ⇒ Element
    Element#observe(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(element) ⇒ Array
    Element#positionedOffset() ⇒ 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(element[, expression[, index = 0]]) ⇒ Element
    Element#previous([expression[, index = 0]]) ⇒ Element
    Element#previous([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…]
    Element#previousSiblings() ⇒ [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(element, attributeName) ⇒ String | null
    Element#readAttribute(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…]
    Element#recursivelyCollect(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).

    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.

  • relativize #

    Element.relativize(element) ⇒ Element
    Element#relativize() ⇒ 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
    Element#remove() ⇒ 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(element, className) ⇒ Element
    Element#removeClassName(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(element[, newContent]) ⇒ Element
    Element#replace([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(element, key[, defaultValue]) ⇒ ?
    Element#retrieve(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
    Element#scrollTo() ⇒ 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(element, selector...) ⇒ [Element…]
    Element#select(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.

    Aliased as: Element.getElementsBySelector

    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(element, value) ⇒ Element
    Element#setOpacity(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(element, styles) ⇒ Element
    Element#setStyle(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
    Element#show() ⇒ 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…]
    Element#siblings() ⇒ [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
    Element#stopObserving([eventName[, handler]]) ⇒ Element

    See Event.stopObserving.

    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.

  • store #

    Element.store(element, key, value) ⇒ Element
    Element#store(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
    Element#toggle() ⇒ 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(element, className) ⇒ Element
    Element#toggleClassName(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
    Element#undoClipping() ⇒ 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
    Element#undoPositioned() ⇒ 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(element[, expression[, index = 0]]) ⇒ Element
    Element#up([expression[, index = 0]]) ⇒ Element
    Element#up([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(element[, newContent]) ⇒ Element
    Element#update([newContent]) ⇒ Element

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

    newContent may be in any of these forms:

    • String: A string of HTML to be parsed and rendered
    • Element: An Element instance to insert
    • ...any object with a toElement method: The method is called and the resulting element used
    • ...any object with a toHTML method: The method is called and the resulting HTML string is parsed and rendered

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

    If newContent is a string and contains one or more inline <script> tags, the scripts are scheduled to be evaluated after a very brief pause (using Function#defer) to allow the browser to finish updating the DOM. Note that the scripts are evaluated in the scope of String#evalScripts, not in the global scope, which has important ramifications for your vars and functions. See String#evalScripts for details.

    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(element) ⇒ Array
    Element#viewportOffset() ⇒ 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(element) ⇒ boolean
    Element#visible() ⇒ 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(element, wrapper[, attributes]) ⇒ Element
    Element#wrap(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(element, attribute[, value = true]) ⇒ Element
    Element#writeAttribute(attribute[, value = true]) ⇒ Element
    Element#writeAttribute(attributes) ⇒ 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.