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

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

addClassName addClassName(element, className) -> HTMLElement Adds a CSS class to element. Example: <div id="mutsu" class="apple fruit"></div> $( 'mutsu' ).addClassName( 'food' ) $( 'mutsu' ).className // -> 'apple fruit food' $( 'mutsu' ).classNames() // -> ['apple', 'fruit', 'food']

addMethods addMethods([methods]) Takes a hash of methods and makes them available as methods of extended elements and of the Element object. Element.addMethods makes it possible to mix in your own methods to the Element object, which you can later use as methods of extended elements - those returned by the $() utility, for example - or as methods of Element. $(element).myOwnMethod([args...]); Note that this will also works: Element.myOwnMethod(element|id[, args...]); To add new methods, simply feed Element.addMethods with a hash of methods. Note that each method's first argument has to be element. Inside each method, remember to pass element to $() and to return it to allow for method chaining if appropriate.

addMethods (con’t) Eg: Hash var myVeryOwnElementMethods = { myFirstMethod: function ( element [, args...]){ element = $( element ); // do something return element ; }, mySecondMethod: function ( element [, args...]){ element = $( element ); // do something else return element ; } };

Want clean, semantic markup, but need that extra <div> around your element, why not create a wrap('tagName') Element method which encloses element in the provided tagName and returns the wrapper? Element.addMethods({ wrap: function ( element , tagName) { element = $( element ); var wrapper = document.createElement( 'tagName' ); element.parentNode.replaceChild(wrapper, element ); wrapper.appendChild( element ); return Element.extend(wrapper); } });

which you'll be able to use like this: // Before: <p id="first">Some content...</p> $( element ).wrap( 'div' ); // -> HTMLElement (div) // After: <div><p id="first">Some content...</p></div>

As you have thoughtfully decided that your wrap() method would return the newly created <div>, ready for prime time thanks to Element.extend, you can immediately chain a new method to it: $(element).wrap('div').setStyle({backgroundImage: 'url(images/rounded-corner-top-left.png) top left'}); Are you using Ajax.Updater quite a bit around your web application to update DOM elements? Would you want a quick and nifty solution to cut down on the amount of code you are writing ? Try this: Element.addMethods({ ajaxUpdate: function ( element , url, options){ element = $( element ); element.update( '<img src="/images/spinner.gif" alt="loading..." />' ); new Ajax.Updater( element , url, options); return element ; } });

Now, whenever you wish to update the content of an element just do: $( element ).ajaxUpdate( '/new/content' ); // -> HTMLElement This method will first replace the content of element with one of those nifty Ajax activity indicator. It will then create a new Ajax.Updater, which in turn will update the content of element with its request result, removing the spinner as it does.

Using Element.addMethods with no argument There's a last dirty little secret to Element.addMethods. You can can call it without passing it an argument. What happens then? Well, it simply iterates over all of Element.Methods, Element.Methods.Simulated, Form.Methods and Form.Element.Methods and adds them to the relevant DOM elements (Form.Methods only gets added to, well the form element while input, select and textarea elements get extended with Form.Element.Methods).

When could that be useful? Imagine that you wish to add a method that deactivates a submit button and replaces its text with something like "Please wait...". You wouldn't want such a method to be applied to any element, would you? So here is how you would go about doing that: Form.Element.Methods.processing = function ( element , text) { element = $( element ); if (element.tagName.toLowerCase() == 'input' && [ 'button' , 'submit' ].include(element.type)) element.value = typeof text == 'undefined' ? 'Please wait...' : text; return element.disable(); }; Element.addMethods();

ancestors :: Element The returned array’s first element is element’s direct ancestor (its parentNode), the second one is its grandparent and so on until the html element is reached. html will always be the last member of the array… unless you are looking for its ancestors obviously. But you wouldn’t do that, would you ? Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <html> […] <body> <div id="father"> <div id="kid"> </div> </div> </body> </html> $( 'kid' ).ancestors(); // -> [div#father, body, html] // Keep in mind that // the `body` and `html` elements will also be included! document.getElementsByTagName( 'html' )[ 0 ].ancestors(); // -> []

classNames :: Element classNames(element) -> [className...] Returns a new instance of ClassNames, an Enumerable object used to read and write class names of the element. Practically, this means that you have access to your element's CSS classNames as an Enumerable rather than as the string that the native className property gives you (notice the singular form). On top of that, this array is extended with a series of methods specifically targeted at dealing with CSS classNames: set(className), add(className) and remove(className). These are used internally by Element.addClassName, Element.toggleClassName and Element.removeClassName, but—unless you want to do some pretty wacky stuff—you usually won't need them.

Examples <div id="mutsu" class="apple fruit food"></div> $('mutsu').classNames()// -> ['apple', 'fruit', 'food'] // change its class names:$('mutsu').className = 'fruit round' $('mutsu').classNames()// -> ['fruit', 'round']

cleanWhitespace :: Element cleanWhitespace(element) -> HTMLElement Removes all of element's text nodes which contain only whitespace. Returns element. cleanWhitespace() removes whitespace-only text nodes. This can be very useful when using standard methods like nextSibling, previousSibling, firstChild or lastChild to walk the DOM. If you only need to access element nodes (and not text nodes), try using Element's new up() , down() , next() and previous() methods instead. You won't regret it!

Example Consider the following HTML snippet: <ul id="apples"> <li>Mutsu</li> <li>McIntosh</li> <li>Ida Red</li> </ul> Let's grab what we think is the first list item: var element = $( 'apples' ); element.firstChild.innerHTML; // -> undefined That doesn't seem to work to well. Why is that ? ul#apples's first child is actually a text node containing only whitespace that sits between <ul id="apples"> and <li>Mutsu</li>.

Let's remove all this useless whitespace: element.cleanWhitespace(); That's what our DOM looks like now: <UL id="apples"><LI>Mutsu</LI><LI>McIntosh</LI><LI>Ida Red</LI></UL> And guess what, firstChild now works as expected! element.firstChild.innerHTML; // -> 'Mutsu'

descendantOf :: Element descendantOf(element, ancestor) -> Boolean Checks if element is a descendant of ancestor. As descendantOf() internally applies $() to ancestor, it accepts indifferently an element or an element’s id as its second argument.

Examples <div id="australopithecus"> <div id="homo-herectus"> <div id="homo-sapiens"></div> </div> </div> $( 'homo-sapiens' ).descendantOf( 'australopithecus' ); // -> true $( 'homo-herectus' ).descendantOf( 'homo-sapiens' ); // -> false

descendants :: Element descendants(element) -> [HTMLElement...] Collects all of element’s descendants and returns them as an array of extended elements. Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <div id="australopithecus"> <div id="homo-herectus"> <div id="homo-neanderthalensis"></div> <div id="homo-sapiens"></div> </div> </div> $('australopithecus').descendants(); // -> [div#homo-herectus, div#homo-neanderthalensis, div#homo-sapiens] $('homo-sapiens').descendants(); // -> []

down :: Element 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. The down() method is part of Prototype’s ultimate DOM traversal toolkit (check out up(), next() and previous() for some more Prototypish niceness). It allows precise index-based and/or CSS rule-based selection of any of the element’s descendants. As it totally ignores text nodes (it only returns elements), you don’t have to worry about whitespace nodes. And as an added bonus, all elements returned are already extended allowing chaining: $(element).down(1).next('li', 2).hide(); Walking the DOM has never been that easy!

Arguments If no argument is passed, element’s first descendant is returned (this is similar as calling firstChild except down() returns an already extended element). If an index is passed, element’s corresponding descendant is returned. (This is equivalent to selecting an element from the array of elements returned by the method descendants().) Note that the first element has an index of 0. If cssRule is defined, down() will return the first descendant that matches it. This is a great way to grab the first item in a list for example (just pass in ‘li’ as the method’s first argument). If both cssRule and index are defined, down() will collect all the descendants matching the given CSS rule and will return the one specified by the index. In all of the above cases, if no descendant is found, undefined will be returned.

Examples <ul id="fruits"> <li id="apples"> <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu" class="yummy">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> </li> </ul>

$( 'fruits' ).down(); // equivalent: $( 'fruits' ).down( 0 ); // -> li#apple $( 'fruits' ).down( 3 ); // -> li#golden-delicious $( 'apples' ).down( 'li' ); // -> li#golden-delicious $( 'apples' ).down( 'li.yummy' ); // -> li#mutsu $( 'fruits' ).down( '.yummy' , 1 ); // -> li#mcintosh $( 'fruits' ).down( 99 ); // -> undefined

empty :: Element empty(element) -> Boolean Tests whether element is empty (i.e. contains only whitespace).

Examples <div id="wallet"> </div> <div id="cart">full!</div> $('wallet').empty(); // -> true $('cart').empty(); // -> false

extend :: Element 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.

This is where the magic happens! By extending an element with Prototype’s custom methods, we can achieve that syntactic sugar and ease of use we all crave for. For example, you can do the following with an extended element: element.update('hello world'); And since most methods of Element return the element they are applied to, you can chain methods like so: element.update('hello world').addClassName('greeting'); Note that all of the elements returned by Element methods are extended (yes even for methods like Element.siblings which return arrays of elements) and Prototype’s flagship utility methods $() and $$() obviously also return extended elements. If you want to know more about how Prototype extends the DOM, jump to this article.

getDimensions :: Element getDimensions(element) -> {height: Number, width: Number} Finds the computed width and height of element and returns them as key/value pairs of an object. This method returns correct values on elements whose display is set to none either in an inline style rule or in an CSS stylesheet. In order to avoid calling the method twice, you should consider caching the values returned in a variable as shown below. If you only need element’s width or height, consider using getWidth() or getHeight() instead. Note that all values are returned as numbers only although they are expressed in pixels

Examples <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div> var dimensions = $( 'rectangle' ).getDimensions(); // -> {width: 200, height: 100} dimensions.width; // -> 200 dimensions.height; // -> 100

getElementsByClassName :: Element 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. The returned array reflects the document order (e.g. an index of 0 refers to the topmost descendant of element with class className).

Examples <ul id="fruits"> <li id="apples">apples <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu" class="yummy">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> </li> <li id="exotic" class="yummy">exotic fruits <ul> <li id="kiwi">kiwi</li> <li id="granadilla">granadilla</li> </ul> </li> </ul>

$( 'fruits' ).getElementsByClassName( 'yummy' ); // -> [li#mutsu, li#mcintosh, li#exotic] $( 'exotic' ).getElementsByClassName( 'yummy' ); // -> []

getElementsBySelector :: Element 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. This method is very similar to $$() and therefore suffers from the same caveats. However, since it operates in a more restricted scope (element’s children) it is faster and therefore a much better alternative. The supported CSS syntax is identical, so please refer to the $$() docs for details.

Examples <ul id="fruits"> <li id="apples"> <h3 title="yummy!">Apples</h3> <ul id="list-of-apples"> <li id="golden-delicious" title="yummy!" >Golden Delicious</li> <li id="mutsu" title="yummy!">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> <p id="saying">An apple a day keeps the doctor away.</p> </li> </ul>

$( 'apples' ).getElementsBySelector( '[title="yummy!"]' ); // -> [h3, li#golden-delicious, li#mutsu] $( 'apples' ).getElementsBySelector( 'p#saying' , 'li[title="yummy!"]' ); // -> [h3, li#golden-delicious, li#mutsu, p#saying] $( 'apples' ).getElementsBySelector( '[title="disgusting!"]' ); // -> []

getHeight :: Element getHeight(element) -> Number Finds and returns the computed height of element. This method returns correct values on elements whose display is set to none either in an inline style rule or in an CSS stylesheet. For performance reasons, if you need to query both width and height of element, you should consider using getDimensions () instead.

Examples <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div> $('rectangle').getHeight(); // -> 100

getStyle :: Element 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. This method looks up the CSS property of an element whether it was applied inline or in a stylesheet. It works around browser inconsistencies regarding float, opacity, which returns a value between 0 (fully transparent) and 1 (fully opaque), position properties (left, top, right and bottom) and when getting the dimensions (width or height) of hidden elements.

Examples $( element ).getStyle( 'font-size' ); // equivalent: $( element ).getStyle( 'fontSize' ); // -> '12px'

Notes Internet Explorer returns literal values while other browsers return computed values. Consider the following HTML snippet: <style> #test { font-size: 12px; margin-left: 1em; } </style> <div id="test"></div> $('test').getStyle('margin-left'); // -> '1em' in Internet Explorer, // -> '12px' elsewhere. Safari returns null for any non-inline property if the element is hidden (has display set to 'none'). Not all CSS shorthand properties are supported . You may only use the CSS properties described in the Document Object Model (DOM) Level 2 Style Specification

getWidth :: Element getWidth(element) -> Number Finds and returns the computed width of element. This method returns correct values on elements whose display is set to none either in an inline style rule or in an CSS stylesheet. For performance reasons, if you need to query both width and height of element, you should consider using getDimensions () instead.

Examples <div id="rectangle" style="font-size: 10px; width: 20em; height: 10em"></div> $( 'rectangle' ).getWidth(); // -> 200

hasClassName :: Element hasClassName(element, className) -> Boolean Checks whether element has the given CSS className.

Examples <div id="mutsu" class="apple fruit food"></div> $( 'mutsu' ).hasClassName( 'fruit' ); // -> true $( 'mutsu' ).hasClassName( 'vegetable' ); // -> false

hide :: Element hide(element) -> HTMLElement Hides and returns element

Examples <div id="error-message"></div> $( 'error-message' ).hide(); // -> HTMLElement (and hides div#error-message)

Backwards compatibility change In previous versions of Prototype, you could pass an arbitrary number of elements to Element.toggle, Element.show, and Element.hide, for consistency, this is no longer possible in version 1.5 ! You can however achieve a similar result by using Enumerables: [ 'content' , 'navigation' , 'footer' ]. each (Element.hide); // -> ['content', 'navigation', 'footer'] // and displays #content, #navigation and #footer. or even better: $( 'content' , 'navigation' , 'footer' ). invoke ('hide'); // -> [HTMLElement, HTMLElement, HTMLElement] (#content, #navigation and #footer) // and displays #content, #navigation and #footer.

immediateDescendants :: Element immediateDescendants(element) -> [HTMLElement...] Collects all of the element’s immediate descendants (i.e. children) and returns them as an array of extended elements. The returned array reflects the children order in the document (e.g., an index of 0 refers to the topmost child of element). Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <div id="australopithecus"> <div id="homo-herectus"> <div id="homo-neanderthalensis"></div> <div id="homo-sapiens"></div> </div> </div> $( 'australopithecus' ).immediateDescendants(); // -> [div#homo-herectus] $( 'homo-herectus' ).immediateDescendants(); // -> [div#homo-neanderthalensis, div#homo-sapiens] $( 'homo-sapiens' ).immediateDescendants(); // -> []

inspect :: Element inspect(element) -> String Returns the debug-oriented string representation of element. For more information on inspect methods, see Object.inspect.

Example <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu" class="yummy apple">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li</li> </ul> $( 'golden-delicious' ).inspect(); // -> '<li id="golden-delicious">' $( 'mutsu' ).inspect(); // -> '<li id="mutsu" class="yummy apple">' $( 'mutsu' ).next().inspect(); // -> '<li>'

makeClipping :: Element makeClipping(element) -> HTMLElement Simulates the poorly supported CSS clip property by setting element's overflow value to 'hidden'. Returns element. To undo clipping, use undoClipping () . The visible area is determined by element's width and height.

Example <div id="framer"> <img src="/assets/2007/1/14/chairs.jpg" alt="example" /> </div> $( 'framer' ).makeClipping().setStyle({width: '100px' , height: '100px' }); // -> HTMLElement

makePositioned :: Element 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. To revert back to element's original CSS position, use undoPositioned () .

Example Consider the following case: <p>lorem […]</p> <div id="container"> <div id="element" style="position: absolute; top: 20px; left: 20px;"></div> </div>

match :: Element match(element, selector) -> Boolean Checks if element matches the given CSS selector.

Examples <ul id="fruits"> <li id="apples"> <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu" class="yummy">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> </li> </ul> $( 'fruits' ).match( 'ul' ); // -> true $( 'mcintosh' ).match( 'li#mcintosh.yummy' ); // -> true $( 'fruits' ).match( 'p' ); // -> false

next :: Element 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.

The next() method is part of Prototype’s ultimate DOM traversal toolkit (check out up(), down() and previous() for some more Prototypish niceness). It allows precise index-based and/or CSS rule-based selection of any of element’s following siblings . (Note that two elements are considered siblings if they have the same parent, so for example, the head and body elements are siblings—their parent is the html element.) As it totally ignores text nodes (it only returns elements), you don’t have to worry about whitespace-only nodes. And as an added bonus, all elements returned are already extended allowing chaining: $(element).down(1).next('li', 2).hide(); Walking the DOM has never been that easy!

Arguments If no argument is passed, element’s following sibling is returned (this is similar as calling nextSibling except next() returns an already extended element). If an index is passed, element’s corresponding following sibling is returned. (This is equivalent to selecting an element from the array of elements returned by the method nextSiblings()). Note that the sibling right below element has an index of 0. If cssRule is defined, next() will return the element first following sibling that matches it. If both cssRule and index are defined, previous() will collect all of element’s following siblings matching the given CSS rule and will return the one specified by the index. In all of the above cases, if no following sibling is found, undefined will be returned

Examples <ul id="fruits"> <li id="apples"> <h3 id="title">Apples</h3> <ul id="list-of-apples"> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li id="ida-red" class="yummy">Ida Red</li> </ul> <p id="saying">An apple a day keeps the doctor away.</p> </li> </ul>

$( 'list-of-apples' ).next(); // equivalent: $( 'list-of-apples' ).next( 0 ); // -> p#sayings $( 'title' ).next( 1 ); // -> ul#list-of-apples $( 'title' ).next( 'p' ); // -> p#sayings $( 'golden-delicious' ).next( '.yummy' ); // -> li#mcintosh $( 'golden-delicious' ).next( '.yummy' , 1 ); // -> li#ida-red $( 'ida-red' ).next(); // -> undefined

nextSiblings :: Element nextSiblings(element) -> [HTMLElement...] Collects all of element’s next siblings and returns them as an array of extended elements. Two elements are siblings if they have the same parent. So for example, the head and body elements are siblings (their parent is the html element). Next siblings are simply the ones which follow element in the document. The returned array reflects the siblings order in the document (e.g. an index of 0 refers to the sibling right below element). Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> $( 'mutsu' ).nextSiblings(); // -> [li#mcintosh, li#ida-red] $( 'ida-red' ).nextSiblings(); // -> []

observe :: Element observe(element, eventName, handler[, useCapture = false]) -> HTMLElement Registers an event handler on element and returns element. This is a simple proxy for Event.observe. Please refer to it for further information.

Example $( element ).observe( 'click' , function (event){ alert(Event.element(event).innerHTML); }); // -> HTMLElement (and will display an alert dialog containing // element's innerHTML when element is clicked).

previous :: Element 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. The previous() method is part of Prototype's ultimate DOM traversal toolkit (check out up(), down() and next() for some more Prototypish niceness). It allows precise index-based and/or CSS rule-based selection of any of element's previous siblings . (Note that two elements are considered siblings if they have the same parent, so for example, the head and body elements are siblings—their parent is the html element.)

As it totally ignores text nodes (it only returns elements), you don’t have to worry about whitespace-only nodes. And as an added bonus, all elements returned are already extended allowing chaining: $(element).down(1).next('li', 2).hide(); Walking the DOM has never been that easy!

Arguments If no argument is passed, element's previous sibling is returned (this is similar as calling previousSibling except previous() returns an already extended element). If an index is passed, element's corresponding previous sibling is returned. (This is equivalent to selecting an element from the array of elements returned by the method previousSiblings()). Note that the sibling right above element has an index of 0. If cssRule is defined, previous() will return the element first previous sibling that matches it. If both cssRule and index are defined, previous() will collect all of element's previous siblings matching the given CSS rule and will return the one specified by the index. In all of the above cases, if no previous sibling is found, undefined will be returned.

Examples <ul id="fruits"> <li id="apples"> <h3>Apples</h3> <ul id="list-of-apples"> <li id="golden-delicious" class="yummy">Golden Delicious</li> <li id="mutsu" class="yummy">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> <p id="saying">An apple a day keeps the doctor away.</p> </li> </ul>

$('saying').previous(); // equivalent: $('saying').previous(0); // -> ul#list-of-apples $('saying').previous(1); // -> h3 $('saying').previous('h3'); // -> h3 $('ida-red').previous('.yummy'); // -> li#mutsu $('ida-red').previous('.yummy', 1); // -> li#golden-delicious $('ida-red').previous(5); // -> undefined

previousSiblings :: Element previousSiblings(element) -> [HTMLElement...] Collects all of element’s previous siblings and returns them as an array of extended elements. Two elements are siblings if they have the same parent. So for example, the head and body elements are siblings (their parent is the html element). Previous siblings are simply the ones which precede element in the document. The returned array reflects the siblings inversed order in the document (e.g. an index of 0 refers to the lowest sibling i.e., the one closest to element). Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> $( 'mcintosh' ).previousSiblings(); // -> [li#mutsu, li#golden-delicious] $( 'golden-delicious' ).previousSiblings(); // -> []

readAttribute :: Element readAttribute(element, attribute) -> String | null Returns the value of element's attribute or null if attribute has not been specified. This method serves two purposes. First it acts as a simple wrapper around getAttribute which isn't a "real" function in Safari and Internet Explorer (it doesn't have .apply or .call for instance). Secondly, it cleans up the horrible mess Internet Explorer makes when handling attributes.

Examples <a id="tag" href="/tags/prototype" rel="tag" title="view related bookmarks." my_widget="some info.">Prototype</a> $( 'tag' ).readAttribute( 'href' ); // -> '/tags/prototype' $( 'tag' ).readAttribute( 'title' ); // -> 'view related bookmarks.' $( 'tag' ).readAttribute( 'my_widget' ); // -> 'some info.

recursivelyCollect :: Element 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. This method is used internally by ancestors(), descendants(), nextSiblings(), previousSiblings() and siblings() which offer really convenient way to grab elements, so directly accessing recursivelyCollect() should seldom be needed. However, if you are after something out of the ordinary, it is the way to go. Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <ul id="fruits"> <li id="apples"> <ul id="list-of-apples"> <li id="golden-delicious"><p>Golden Delicious</p></li> <li id="mutsu">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> </li> </ul> $( 'fruits' ).recursivelyCollect( 'firstChild' ); // -> [li#apples, ul#list-of-apples, li#golden-delicious, p]

remove :: Element remove(element) -> HTMLElement Completely removes element from the document and returns it. If you would rather just hide the element and keep it around for further use, try hide() instead.

Examples // Before: <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> $( 'mutsu' ).remove(); // -> HTMLElement (and removes li#mutsu) // After: <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul>

removeClassName :: Element removeClassName(element, className) -> HTMLElement Removes element’s CSS className and returns element.

Examples <div id="mutsu" class="apple fruit food"></div> $('mutsu').removeClassName('food'); // -> HTMLElement $('mutsu').classNames(); // -> ['apple', 'fruit']

replace :: Element replace(element[, html]) -> HTMLElement Replaces element by the content of the html argument and returns the removed element. html can be either plain text, an HTML snippet or any JavaScript object which has a toString() method. If it contains any <script> tags, these will be evaluated after element has been replaced (replace() internally calls String.evalScripts). Note that if no argument is provided, replace() will simply clear element of its content. However, using remove() to do so is both faster and more standard compliant.

Examples <div id="food"> <div id="fruits"> <p id="first">Kiwi, banana <em>and</em> apple.</p> </div> </div> Passing an HTML snippet: $('first').replace('<ul id="favorite"><li>kiwi</li><li>banana</li><li>apple</li></ul>'); // -> HTMLElement (p#first) $('fruits').innerHTML; // -> '<ul id="favorite"><li>kiwi</li><li>banana</li><li>apple</li></ul>'

Again, with a <script> tag thrown in: $('favorite').replace('<p id="still-first">Melon, oranges <em>and</em> grapes.</p><script>alert("removed!")</script>'); // -> HTMLElement (ul#favorite) and prints "removed!" in an alert dialog. $('fruits').innerHTML // -> '<p id="still-first">Melon, oranges <em>and</em> grapes.</p>' With plain text: $('still-first').replace('Melon, oranges and grapes.'); // -> HTMLElement (p#still-first) $('fruits').innerHTML // -> 'Melon, oranges and grapes.' Finally, relying on the toString() method: $('fruits').update(123); // -> HTMLElement $('food').innerHTML; // -> '123'

scrollTo :: Element scrollTo(element) -> HTMLElement Scrolls the window so that element appears at the top of the viewport. Returns element. This has a similar effect than what would be achieved using HTML anchors (except the browser’s history is not modified).

Examples $(element).scrollTo();

setStyle :: Element 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.

Examples $( element ).setStyle({ backgroundColor: ' #900' , fontSize: '12px' }); // -> HTMLElement

Notes The method transparently deals with browser inconsistencies for float—however, as float is a reserved keyword, you must either escape it or use cssFloat instead—and opacity—which accepts values between 0 (fully transparent) and 1 (fully opaque). You can safely use either of the following across all browsers: $( element ).setStyle({ cssFloat: 'left' , opacity: 0.5 }); // -> HTMLElement $( element ).setStyle({ 'float' : 'left' , // notice how float is surrounded by single quotes opacity: 0.5 }); // -> HTMLElement Not all CSS shorthand properties are supported. You may only use the CSS properties described in the Document Object Model (DOM) Level 2 Style Specification.

show :: Element show(element) -> HTMLElement Displays and returns element.

Examples <div id="error-message" style="display:none;"></div> $( 'error-message' ).show(); // -> HTMLElement (and displays div#error-message)

Notes show() cannot display elements hidden via CSS stylesheets. Note that this is not a Prototype limitation but a consequence of how the CSS display property works. <style> #hidden-by-css { display: none; } </style> […] <div id="hidden-by-css"></div> $( 'hidden-by-css' ).show(); // DOES NOT WORK! // -> HTMLElement (div#error-message is still hidden!)

Backwards compatibility change In previous versions of Prototype, you could pass an arbitrary number of elements to Element.toggle, Element.show, and Element.hide, for consistency, this is no longer possible in version 1.5 ! You can however achieve a similar result by using Enumerables: ['content', 'navigation', 'footer']. each (Element.show); // -> ['content', 'navigation', 'footer'] // and displays #content, #navigation and #footer. or even better: $('content', 'navigation', 'footer'). invoke ('show'); // -> [HTMLElement, HTMLElement, HTMLElement] (#content, #navigation and #footer) // and displays #content, #navigation and #footer.

siblings :: Element siblings(element) -> [HTMLElement...] Collects all of element’s siblings and returns them as an array of extended elements. Two elements are siblings if they have the same parent. So for example, the head and body elements are siblings (their parent is the html element). The returned array reflects the siblings order in the document (e.g. an index of 0 refers to element’s topmost sibling). Note that all of Prototype’s DOM traversal methods ignore text nodes and return element nodes only.

Examples <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu">Mutsu</li> <li id="mcintosh">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> $( 'mutsu' ).siblings(); // -> [li#golden-delicious, li#mcintosh, li#ida-red]

stopObserving :: Element stopObserving(element, eventName, handler) -> HTMLElement Unregisters handler and returns element. This is a simple proxy for Event.stopObserving . Please refer to it for further information.

Example $( element ).stopObserving( 'click' , coolAction); // -> HTMLElement (and unregisters the 'coolAction' event handler).

toggle :: Element toggle(element) -> HTMLElement Toggles the visibility of element.

Examples <div id="welcome-message"></div> <div id="error-message" style="display:none;"></div> $( 'welcome-message' ).toggle(); // -> HTMLElement (and hides div#welcome-message) $( 'error-message' ).toggle(); // -> HTMLElement (and displays div#error-message)

Notes toggle() cannot display elements hidden via CSS stylesheets. Note that this is not a Prototype limitation but a consequence of how the CSS display property works. <style> #hidden-by-css { display: none; } </style> […] <div id="hidden-by-css"></div> $( 'hidden-by-css' ).toggle(); // WONT' WORK! // -> HTMLElement (div#hidden-by-css is still hidden!)

Backwards compatibility change In previous versions of Prototype, you could pass an arbitrary number of elements to Element.toggle, Element.show, and Element.hide, for consistency, this is no longer possible in version 1.5! You can however achieve a similar result by using Enumerables: ['error-message', 'welcome-message'].each(Element.toggle); // -> ['error-message', 'welcome-message'] // and toggles the visibility of div#error-message and div#confirmation-message. or even better: $('error-message', 'welcome-message').invoke('toggle'); // -> [HTMLElement, HTMLElement] (div#error-message and div#welcome-message) // and toggles

toggleClassName :: Element toggleClassName(element, className) -> HTMLElement Toggles element’s CSS className and returns element.

Examples <div id="mutsu" class="apple"></div> $( 'mutsu' ).hasClassName( 'fruit' ); // -> false $( 'mutsu' ).toggleClassName( 'fruit' ); // -> element $( 'mutsu' ).hasClassName( 'fruit' ); // -> true

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

Example <div id="framer"> <img src="/assets/2007/1/14/chairs.jpg" alt="example" /> </div> $( 'framer' ).undoClipping(); // -> HTMLElement (and sets the CSS overflow property to its original value).

undoPositioned :: Element undoPositioned(element) -> HTMLElement Sets element back to the state it was before makePositioned() was applied to it. Returns element. element's absolutely positioned children will now have their positions set relatively to element's nearest ancestor with a CSS position of 'absolute', 'relative' or 'fixed'.

Example <p>lorem […]</p> <div id="container"> <div id="element" style="position: absolute; top: 20px; left: 20px;"></div> </div> $( 'container' ).makePositioned(); // -> HTMLElement

up :: Element 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. The up() method is part of Prototype’s ultimate DOM traversal toolkit (check out down(), next() and previous() for some more Prototypish niceness). It allows precise index-based and/or CSS rule-based selection of any of element’s ancestors. As it totally ignores text nodes (it only returns elements), you don’t have to worry about whitespace-only nodes. And as an added bonus, all elements returned are already extended allowing chaining: $(element).down(1).next('li', 2).hide(); Walking the DOM has never been that easy!

Arguments If no argument is passed, element’s first ancestor is returned (this is similar as calling parentNode except up() returns an already extended element. If an index is passed, element’s corresponding ancestor is is returned. (This is equivalent to selecting an element from the array of elements returned by the method ancestors()). Note that the first element has an index of 0. If cssRule is defined, up() will return the first ancestor that matches it. If both cssRule and index are defined, up() will collect all the ancestors matching the given CSS rule and will return the one specified by the index. In all of the above cases, if no descendant is found, undefined will be returned.

Examples <html> […] <body> <ul id="fruits"> <li id="apples" class="keeps-the-doctor-away"> <ul> <li id="golden-delicious">Golden Delicious</li> <li id="mutsu" class="yummy">Mutsu</li> <li id="mcintosh" class="yummy">McIntosh</li> <li id="ida-red">Ida Red</li> </ul> </li> </ul> </body> </html>

$( 'fruits' ).up(); // equivalent: $( 'fruits' ).up( 0 ); // -> body $( 'mutsu' ).up( 2 ); // -> ul#fruits $( 'mutsu' ).up( 'li' ); // -> li#apples $( 'mutsu' ).up( '.keeps-the-doctor-away' ); // -> li#apples $( 'mutsu' ).up( 'ul' , 1 ); // -> li#fruits $( 'mutsu' ).up( 'div' ); // -> undefined

update :: Element update(element[, newContent]) -> HTMLElement Replaces the content of element with the provided newContent argument and returns element. newContent can be plain text, an HTML snippet, or any JavaScript object which has a toString() method. If it contains any <script> tags, these will be evaluated after element has been updated (update() internally calls String.evalScripts()). If no argument is provided, update() will simply clear element of its content. Note that this method allows seamless content update of table related elements in Internet Explorer 6 and beyond

Examples <div id="fruits">carrot, eggplant and cucumber</div> Passing a regular string: $( 'fruits' ).update( 'kiwi, banana and apple' ); // -> HTMLElement $( 'fruits' ).innerHTML // -> 'kiwi, banana and apple' Clearing the element’s content: $( 'fruits' ).update(); // -> HTMLElement $( 'fruits' ).innerHTML; // -> '' (an empty string)

And now inserting an HTML snippet: $('fruits').update('<p>Kiwi, banana <em>and</em> apple.</p>'); // -> HTMLElement $('fruits').innerHTML; // -> '<p>Kiwi, banana <em>and</em> apple.</p>' … with a <script> tag thrown in: $('fruits').update('<p>Kiwi, banana <em>and</em> apple.</p><script>alert("updated!")</script>'); // -> HTMLElement (and prints "updated!" in an alert dialog). $('fruits').innerHTML; // -> '<p>Kiwi, banana <em>and</em> apple.</p>' Relying on the toString() method: $('fruits').update(123); // -> HTMLElement $('fruits').innerHTML; // -> '123'

Finally, you can do some pretty funky stuff by defining your own toString() method on your custom objects: var Fruit = Class.create(); Fruit.prototype = { initialize: function(fruit){ this.fruit = fruit; }, toString: function(){ return 'I am a fruit and my name is "' + this.fruit + '".'; } } var apple = new Fruit('apple'); $('fruits').update(apple); $('fruits').innerHTML; // -> 'I am a fruit and my name is "apple".'

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

Examples <div id="visible"></div> <div id="hidden" style="display: none;"></div> $( 'visible' ).visible(); // -> true $( 'hidden' ).visible(); // -> false

Notes Styles applied via a CSS stylesheet are not taken into consideration. Note that this is not a Prototype limitation, it is a CSS limitation. <style> #hidden-by-css { display: none; } </style> […] <div id="hidden-by-css"></div> $('hidden-by-css').visible(); // -> true

Element.Methods.Simulated Element.Methods.Simulated allows simulating missing HTMLElement methods in non standard compliant browsers which you can then call on extended elements just as if the browser vendor had suddenly decided to implement them. hasAttribute hasAttribute(element, attribute) -> Boolean Simulates the standard compliant DOM method hasAttribute for browsers missing it (Internet Explorer 6 and 7).

hasAttribute :: Element hasAttribute(element, attribute) -> Boolean Simulates the standard compliant DOM method hasAttribute for browsers missing it (Internet Explorer 6 and 7). Example <a id="link" href="http://prototypejs.org">Prototype</a> $('link').hasAttribute('href'); // -> true

info :: Element.Methods Element.Methods is a mixin for DOM elements. The methods of this object are accessed through the $() utility or through the Element object and shouldn’t be accessed directly.

Element

More Related Content

What's hot (20)

Similar to Element (20)

More from mussawir20 (20)

Recently uploaded (20)

Element