4 The following functions are treated as Window methods.
6 Function: document.id {#Window:document-id}
7 -------------------------------------------
9 The document.id function has a dual purpose: Getting the element by its id, and making an element in Internet Explorer "grab" all the [Element][] methods.
13 var myElement = document.id(el);
17 1. el - The Element to be extended. Can be one of the following types:
18 * (*element*) The element will be extended if it is not already.
19 * (*string*) A string containing the id of the DOM element desired.
20 * (*object*) If the object has a toElement method, toElement will be called to get the Element.
24 * (*element*) A DOM element.
25 * (*null*) Null if no matching id was found or if toElement did not return an element.
29 #### Get a DOM Element by ID:
31 var myElement = document.id('myElement');
33 #### Get a DOM Element by reference:
35 var div = document.getElementById('myElement');
36 div = document.id(div); // the element with all the Element methods applied.
40 - This method is useful when it's unclear if working with an actual element or an id. It also serves as a shorthand for document.getElementById().
41 - In Internet Explorer, the [Element][] is extended the first time document.id is called on it, and all the [Element][] Methods become available.
42 - Browsers with native HTMLElement support, such as Safari, Firefox, and Opera, apply all the [Element][] Methods to every DOM element automatically.
43 - Because MooTools detects if an element needs to be extended or not, this function may be called on the same Element many times with no ill effects.
46 Function: $ {#Window:dollar}
47 ----------------------------
49 The dollar function is an alias for [document:id][] if the $ variable is not set already.
50 However it is not recommended to use more frameworks, the $ variable can be set by another framework or script. MooTools will detect this and determine if it will set the $ function so it will not be overwritten.
54 var myElement = $('myElement');
55 var myElement2 = document.id('myElement');
57 myElement == myElement2; // returns true
62 // Now you can use $ safely in this closure
68 - MooTools Blogpost: [The Dollar Safe Mode][]
71 Function: $$ {#Window:dollars}
72 ------------------------------
74 Selects and extends DOM elements. Return an Elements instance.
75 The Element instance returned is an array-like object, supporting every [Array][] method and every [Element][] method.
79 var myElements = $$(argument);
83 * selector - (*string*) A CSS selector
84 * elements - (*elements*), (*collection*) or (*array*) An enumerable list of elements
85 * element, element - (*element*) any number of elements as arguments
89 * (*elements*) - An array-like Elements collection of all the DOM elements matched, extended with [document:id][].
93 #### Get Elements by Their Tag Names:
95 $$('a'); // returns all anchor elements in the page.
97 #### Get an Elements instance by passing multiple elements:
99 $$(element1, element2, element3); // returns an Elements instance containing these 3 elements.
101 #### Convert any array or collection of elements to an Elements instance:
103 $$([element1, element2, element3]); // returns an Elements instance containing these 3 elements.
104 $$(document.getElementsByTagName('a')); // returns an Elements instance containing the result of the getElementsByTagName call.
106 #### Using CSS Selectors:
108 $$('#myElement'); // returns an Elements instance containing only the element with the id 'myElement'.
109 $$('#myElement a.myClass'); // returns an Elements instance of all anchor tags with the class 'myClass' within the DOM element with id 'myElement'.
110 $$('a, b'); // returns an array of all anchor and bold elements in the page.
114 - Since MooTools 1.3 this function does not accept multiple collections or multiple strings as arguments.
115 - If an expression doesn't find any elements, an empty Elements instance will be returned.
116 - The return type of element methods run through [$$][] is always an Elements instance, regardless of the amount of results.
117 - Default Selectors supported are the same as you can find on [W3C CSS3 selectors](http://www.w3.org/TR/css3-selectors/#selectors).
120 Type: Element {#Element}
121 ========================
123 Custom Type to allow all of its methods to be used with any extended DOM Element.
127 Element Method: constructor {#Element:constructor}
128 --------------------------------------------------
130 Creates a new Element of the type passed in.
134 var myEl = new Element(element[, properties]);
138 1. element - (*mixed*) The tag name for the Element to be created or an actual DOM element or a CSS selector.
139 2. properties - (*object*, optional) Calls the Single Argument version of [Element:set][] with the properties object passed in.
143 * (*element*) A new MooTools extended HTML Element.
147 // Creating an new anchor with an Object
148 var myAnchor = new Element('a', {
149 href: 'http://mootools.net',
154 border: '1px solid black'
160 mouseover: function(){
161 alert('mouseovered');
167 var myNewElement = new Element('a.myClass');
171 Because the element name is parsed as a CSS selector, colons in namespaced tags have to be escaped. So `new Element('fb\:name')` becomes `<fb:name>`.
175 - [$][], [Element:set][]
179 Element Method: getElement {#Element:getElement}
180 ------------------------------------------------
182 Gets the first descendant element whose tag name matches the tag provided. CSS selectors may also be passed.
186 var myElement = myElement.getElement(tag);
190 1. tag - (*string*) Tag name of the element to find or a CSS Selector.
194 * (*mixed*) If a match is found, the Element will be returned. Otherwise, returns null.
198 var firstDiv = $(document.body).getElement('div');
202 - This method is also available for Document instances.
203 - Default Selectors supported are the same as you can find on [W3C CSS3 selectors](http://www.w3.org/TR/css3-selectors/#selectors).
207 Element Method: getElements {#Element:getElements}
208 --------------------------------------------------
210 Collects all descendant elements whose tag name matches the tag provided. CSS selectors may also be passed.
214 var myElements = myElement.getElements(tag);
218 1. tag - (*string*) String of the tag to match or a CSS Selector.
222 * (*array*) An [Elements][] array of all matched Elements.
226 var allAnchors = $(document.body).getElements('a');
230 - This method is also available for Document instances.
231 - Default Selectors supported are the same as you can find on [W3C CSS3 selectors](http://www.w3.org/TR/css3-selectors/#selectors).
235 Element Method: getElementById {#Element:getElementById}
236 --------------------------------------------------------
238 Gets the element with the specified id found inside the current Element.
242 var myElement = anElement.getElementById(id);
246 1. id - (*string*) The ID of the Element to find.
250 * (*mixed*) If a match is found, returns that Element. Otherwise, returns null.
254 var myChild = $('myParent').getElementById('myChild');
258 - This method is not provided for Document instances as document.getElementById is provided natively.
262 Element Method: set {#Element:set}
263 ----------------------------
265 This is a "dynamic arguments" method. Properties passed in can be any of the 'set' properties in the [Element.Properties][] Object.
269 myElement.set(arguments);
273 - Two Arguments (property, value)
274 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to set.
275 2. value - (*mixed*) The value to set for the specified property.
276 - One Argument (properties)
277 1. properties - (*object*) Object with its keys/value pairs representing the properties and values to set for the Element (as described below).
281 * (*element*) This Element.
285 #### With Property and Value:
287 $('myElement').set('text', 'text goes here');
288 $('myElement').set('class', 'active');
289 // the 'styles' property passes the object to Element:setStyles.
290 var body = $(document.body).set('styles', {
297 var myElement = $('myElement').set({
298 // the 'styles' property passes the object to Element:setStyles.
302 border: '1px solid #f00'
304 // the 'events' property passes the object to Element:addEvents.
306 click: function(){ alert('click'); },
307 mouseover: function(){ this.addClass('over'); }
309 //Any other property uses Element:setProperty.
315 - All the property arguments are passed to the corresponding method of the [Element.Properties][] Object.
316 - If no matching property is found in [Element.Properties][], it falls back to [Element:setProperty][].
317 - Whenever using [Element:setProperty][] to set an attribute, pass in the lowercase, simplified form of the property. For example:
318 - use 'for', not 'htmlFor',
319 - use 'class', not 'className'
320 - use 'frameborder', not 'frameBorder'
322 - In IE8 or lower, it is not possible to set `type` multiple times. It will throw an error.
327 - [Element][], [Element.Properties][], [Element:setProperty][], [Element:addEvents][], [Element:setStyles][]
331 Element Method: get {#Element:get}
332 ----------------------------------
334 This is a "dynamic arguments" method. Properties passed in can be any of the 'get' properties in the [Element.Properties][] Object.
338 myElement.get(property);
342 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to get.
346 * (*mixed*) The result of calling the corresponding 'get' function in the [Element.Properties][] Object.
350 #### Using Custom Getters:
352 var tag = $('myDiv').get('tag'); // returns "div".
354 #### Fallback to Element Attributes:
356 var id = $('myDiv').get('id'); // returns "myDiv".
357 var value = $('myInput').get('value'); // returns the myInput element's value.
361 - If the corresponding accessor doesn't exist in the [Element.Properties][] Object, the result of [Element:getProperty][] on the property passed in is returned.
365 - [Element][], [Element.Properties][], [Element:getProperty][]
369 Element Method: erase {#Element:erase}
370 --------------------------------------
372 This is a "dynamic arguments" method. Properties passed in can be any of the 'erase' properties in the [Element.Properties][] Object.
376 myElement.erase(property);
380 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to erase.
384 * (*mixed*) The result of calling the corresponding 'erase' function in the [Element.Properties][] Object.
388 $('myDiv').erase('id'); //Removes the id from myDiv.
389 $('myDiv').erase('class'); //myDiv element no longer has any class names set.
393 - If the corresponding eraser doesn't exist in the [Element.Properties][] Object, [Element:removeProperty][] is called with the property passed in.
397 - [Element][], [Element.Properties][], [Element:removeProperty][]
401 Element Method: match {#Element:match}
402 --------------------------------------
404 Tests this Element to see if it matches the argument passed in.
408 myElement.match(match);
412 1. match - can be a string or element
413 - (*string*) The tag name to test against this element. Any single CSS selectors may also be passed.
414 - (*element*) An element to match; returns true if this is the actual element passed in.
418 * (*boolean*) If the element matched, returns true. Otherwise, returns false.
422 #### Using a Tag Name:
424 // returns true if #myDiv is a div.
425 $('myDiv').match('div');
427 #### Using a CSS Selector:
429 // returns true if #myDiv has the class foo and is named "bar"
430 $('myDiv').match('.foo[name=bar]');
432 #### Using an Element:
435 $('myDiv').match(el); // returns true
436 $('otherElement').match(el); // returns false
440 Element Method: contains {#Element:contains}
441 --------------------------------------------
443 Checks all descendants of this Element for a match.
448 var result = myElement.contains(el);
452 1. el - (*element*) The element to search for.
456 * (*boolean*) Returns true if the element contains passed in Element is a child, otherwise false.
462 <div id="Darth_Vader">
463 <div id="Luke"></div>
468 if ($('Darth_Vader').contains($('Luke'))) alert('Luke, I am your father.'); //tan tan tannn...
472 Element Method: inject {#Element:inject}
473 ----------------------------------------
475 Injects, or inserts, the Element at a particular place relative to the Element's children (specified by the second the argument).
479 myElement.inject(el[, where]);
483 1. el - (*mixed*) el can be the id of an element or an element.
484 2. where - (*string*, optional: defaults to 'bottom') The place to inject this Element. Can be 'top', 'bottom', 'after', or 'before'.
488 * (*element*) This Element.
494 var myFirstElement = new Element('div', {id: 'myFirstElement'});
495 var mySecondElement = new Element('div', {id: 'mySecondElement'});
496 var myThirdElement = new Element('div', {id: 'myThirdElement'});
500 <div id="myFirstElement"></div>
501 <div id="mySecondElement"></div>
502 <div id="myThirdElement"></div>
504 #### Inject to the bottom:
508 myFirstElement.inject(mySecondElement);
512 <div id="mySecondElement">
513 <div id="myFirstElement"></div>
516 #### Inject to the top:
520 myThirdElement.inject(mySecondElement, 'top');
524 <div id="mySecondElement">
525 <div id="myThirdElement"></div>
526 <div id="myFirstElement"></div>
533 myFirstElement.inject(mySecondElement, 'before');
537 <div id="myFirstElement"></div>
538 <div id="mySecondElement"></div>
544 myFirstElement.inject(mySecondElement, 'after');
548 <div id="mySecondElement"></div>
549 <div id="myFirstElement"></div>
553 [Element:adopt](#Element:adopt), [Element:grab](#Element:grab), [Element:wraps](#Element:wraps)
557 Element Method: grab {#Element:grab}
558 ------------------------------------
560 Works as [Element:inject](#Element:inject), but in reverse.
562 Appends the Element at a particular place relative to the Element's children (specified by the where parameter).
566 myElement.grab(el[, where]);
570 1. el - (*mixed*) el can be the id of an element or an Element.
571 2. where - (*string*, optional: default 'bottom') The place to append this Element. Can be 'top', 'bottom', 'before' or 'after'.
575 * (*element*) This Element.
582 <div id="child"></div>
587 var mySecondElement = new Element('div#second');
588 $('first').grab(mySecondElement);
593 <div id="child"></div>
594 <div id="second"></div>
599 var mySecondElement = new Element('div#second');
600 myFirstElement.grab(mySecondElement, 'top');
605 <div id="second"></div>
606 <div id="child"></div>
611 [Element:adopt](#Element:adopt), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
615 Element Method: adopt {#Element:adopt}
616 --------------------------------------
618 Works like [Element:grab](#Element:grab), but allows multiple elements to be adopted and only appended at the bottom.
620 Inserts the passed element(s) inside the Element (which will then become the parent element).
624 myParent.adopt(el[, others]);
628 1. el - (*mixed*) The id of an element, an Element, or an array of elements.
629 2. others - (*mixed*, optional) One or more additional Elements separated by a comma or as an array.
633 * (*element*) This Element.
639 var myFirstElement = new Element('div#first');
640 var mySecondElement = new Element('p#second');
641 var myThirdElement = new Element('ul#third');
642 var myFourthElement = new Element('a#fourth');
644 var myParentElement = new Element('div#parent');
646 myFirstElement.adopt(mySecondElement);
647 mySecondElement.adopt(myThirdElement, myFourthElement);
648 myParentElement.adopt([myFirstElement, new Element('span#another')]);
659 <span id="another"></span>
664 [Element:grab](#Element:grab), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
668 Element Method: wraps {#Element:wraps}
669 --------------------------------------
671 Works like [Element:grab](#Element:grab), but replaces the element in its place, and then appends the replaced element in the location specified inside the this element.
675 myParent.wraps(el[, where]);
679 1. el - (*mixed*) The id of an element or an Element.
680 2. where - (*string*, optional: default 'bottom') The place to insert the passed in element. Can be 'top' or 'bottom'.
684 * (*element*) This Element.
690 <div id="first"></div>
694 var mySecondElement = new Element('div#second').wraps('first');
699 <div id="first"></div>
704 <div id="first"></div>
706 <div id="child"></div>
711 $('second').wraps('first');
716 <div id="child"></div>
717 <div id="first"></div>
722 $('second').wraps('first', 'top');
727 <div id="first"></div>
728 <div id="child"></div>
731 Element Method: appendHTML {#Element:appendHTML}
732 ------------------------------------------------
734 Works like [Element:grab](#Element:grab), but instead of accepting an id or an element, it only accepts an HTML string.
735 The HTML string will be parsed to create new DOM elements, and then injected relative to the element from where the method
740 myElement.appendHTML(html[, where]);
744 1. html - (*string*) The HTML string to append.
745 1. where - (*string*, optional: default 'bottom') The position to inject the text to. Values accepted are 'top', 'bottom', 'before' and 'after'.
749 * (*element*) The current Element instance.
755 <div id="myElement">Hey.</div>
759 $('myElement').appendHTML(' <strong>Howdy.</strong>');
763 <div id="myElement">Hey. <strong>Howdy.</strong></div>
767 - This method does *not* use the `innerHTML` property of an element but instead creates elements
768 directly before injecting them. Thus, it is safe to use in cases where you don't want to destroy
769 any descendant elements already present in the parent.
770 - This method uses `insertAdjacentHTML` when available.
774 - [MDN Element:insertAdjacentHTML][].
777 Element Method: appendText {#Element:appendText}
778 ------------------------------------------------
780 Works like [Element:grab](#Element:grab), but instead of accepting an id or an element, it only accepts text.
781 A text node will be created inside this Element, in either the top or bottom position.
785 myElement.appendText(text[, where]);
789 1. text - (*string*) The text to append.
790 1. where - (*string*, optional: default 'bottom') The position to inject the text to. Values accepted are 'top', 'bottom', 'before' and 'after'.
794 * (*element*) The current Element instance.
800 <div id="myElement">Hey.</div>
804 $('myElement').appendText(' Howdy.');
808 <div id="myElement">Hey. Howdy.</div>
812 Element Method: dispose {#Element:dispose}
813 ------------------------------------------
815 Removes the Element from the DOM.
820 var removedElement = myElement.dispose();
824 * (*element*) This Element. Useful to always grab the return from this function, as the element could be [injected](#Element:inject) back.
830 <div id="myElement"></div>
831 <div id="mySecondElement"></div>
835 $('myElement').dispose();
839 <div id="mySecondElement"></div>
843 - [MDN Element:removeChild][]
847 Element Method: clone {#Element:clone}
848 --------------------------------------
850 Clones the Element and returns the cloned one.
855 var copy = myElement.clone([contents, keepid]);
859 1. contents - (*boolean*, optional: defaults to true) When set to false the Element's contents are not cloned.
860 2. keepid - (*boolean*, optional: defaults to false) When true the cloned Element keeps the id attribute, if present. Same goes for any of the cloned childNodes.
865 * (*element*) The cloned Element.
871 <div id="myElement">ciao</div>
875 // clones the Element and appends the clone after the Element.
876 var clone = $('myElement').clone().inject('myElement','after');
880 <div id="myElement">ciao</div>
885 - The returned Element does not have attached events. To clone the events use [Element:cloneEvents](/core/Element/Element.Event#Element:cloneEvents).
886 - Values stored in Element.Storage are not cloned.
887 - The clone element and its children are stripped of ids, unless otherwise specified by the keepid parameter.
891 - [Element:cloneEvents](/core/Element/Element.Event#Element:cloneEvents).
895 Element Method: replaces {#Element:replaces}
896 --------------------------------------------------
898 Replaces the passed Element with Element.
902 var element = myElement.replaces(el);
906 1. el - (*mixed*) A string id representing the Element to be replaced, or an Element reference.
910 * (*element*) This Element.
914 $('myNewElement').replaces($('myOldElement'));
915 //$('myOldElement') is gone, and $('myNewElement') is in its place.
919 - [MDN Element:replaceChild][]
923 Element Method: hasClass {#Element:hasClass}
924 --------------------------------------------
926 Tests the Element to see if it has the passed in className.
930 var result = myElement.hasClass(className);
934 1. className - (*string*) The class name to test.
938 * (*boolean*) Returns true if the Element has the class, otherwise false.
944 <div id="myElement" class="testClass"></div>
948 $('myElement').hasClass('testClass'); // returns true
952 Element Method: addClass {#Element:addClass}
953 --------------------------------------------
955 Adds the passed in class to the Element, if the Element doesnt already have it.
959 myElement.addClass(className);
963 1. className - (*string*) The class name to add.
967 * (*element*) This Element.
973 <div id="myElement" class="testClass"></div>
977 $('myElement').addClass('newClass');
981 <div id="myElement" class="testClass newClass"></div>
985 Element Method: removeClass {#Element:removeClass}
986 ----------------------------
988 Works like [Element:addClass](#Element:addClass), but removes the class from the Element.
993 myElement.removeClass(className);
997 1. className - (*string*) The class name to remove.
1001 * (*element*) This Element.
1007 <div id="myElement" class="testClass newClass"></div>
1011 $('myElement').removeClass('newClass');
1013 ##### Resulting HTML
1015 <div id="myElement" class="testClass"></div>
1019 Element Method: toggleClass {#Element:toggleClass}
1020 --------------------------------------------------
1022 Adds or removes the passed in class name to the Element, depending on whether or not it's already present.
1026 myElement.toggleClass(className, force);
1030 1. className - (*string*) The class to add or remove.
1031 2. force - (*boolean*, optional) Force the class to be either added or removed
1035 * (*element*) This Element.
1041 <div id="myElement" class="myClass"></div>
1045 $('myElement').toggleClass('myClass');
1047 ##### Resulting HTML
1049 <div id="myElement" class=""></div>
1053 $('myElement').toggleClass('myClass');
1055 ##### Resulting HTML
1057 <div id="myElement" class="myClass"></div>
1061 Element Method: getPrevious {#Element:getPrevious}
1062 --------------------------------------------------
1064 Returns the previousSibling of the Element (excluding text nodes).
1068 var previousSibling = myElement.getPrevious([match]);
1072 1. match - (*string*, optional): A tag name to match the the found element(s) with. A full CSS selector can be passed.
1076 * (*mixed*) The previous sibling Element or null if none found.
1080 Element Method: getAllPrevious {#Element:getAllPrevious}
1081 --------------------------------------------------------
1083 Like [Element:getPrevious][], but returns a collection of all the matched previousSiblings.
1087 Element Method: getNext {#Element:getNext}
1088 ------------------------------------------
1090 As [Element:getPrevious][], but tries to find the nextSibling (excluding text nodes).
1095 var nextSibling = myElement.getNext([match]);
1099 1. match - (*string*, optional): A comma seperated list of tag names to match the found element(s) with. A full CSS selector can be passed.
1103 * (*mixed*) The next sibling Element or null if none found.
1106 Element Method: getAllNext {#Element:getAllNext}
1107 ------------------------------------------------
1109 Like Element.getNext, but returns a collection of all the matched nextSiblings.
1113 Element Method: getFirst {#Element:getFirst}
1114 --------------------------------------------
1116 Gets the first element that matches the passed in expression.
1121 var firstElement = myElement.getFirst([match]);
1125 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1129 * (*mixed*) The first found element or null if none found.
1133 Element Method: getLast {#Element:getLast}
1134 ------------------------------------------
1136 Gets the last element that matches the passed in expression.
1140 var lastElement = myElement.getLast([match]);
1144 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1148 * (*mixed*) The last found element, or returns null if none found.
1152 Element Method: getParent {#Element:getParent}
1153 ----------------------------------------------
1155 Works as [Element:getPrevious][], but tries to find the parentNode.
1160 var parent = myElement.getParent([match]);
1164 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1168 * (*mixed*) The target Element's parent or null if no matching parent is found.
1172 Element Method: getParents {#Element:getParents}
1173 ------------------------------------------------
1175 Like [Element:getParent](#Element:getParent), but returns a collection of all the matched parentNodes up the tree.
1179 * (*array*) If no matching parents are found, an empty array is returned.
1183 Element Method: getSiblings {#Element:getSiblings}
1184 --------------------------------------------------
1186 Like [Element:getAllPrevious][] but returns all Element's previous and next siblings (excluding text nodes). Returns as [Elements][].
1191 var siblings = myElement.getSiblings([match]);
1195 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1199 * (*array*) A [Elements](#Elements) array with all of the Element's siblings, except the text nodes.
1203 Element Method: getChildren {#Element:getChildren}
1204 --------------------------------------------------
1206 Returns all the Element's children (excluding text nodes). Returns as [Elements][].
1211 var children = myElement.getChildren([match]);
1215 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1219 * (*array*) A [Elements](#Elements) array with all of the Element's children, except the text nodes.
1223 The difference between the methods *getChildren* and *getElements* is that getChildren will only return its direct children while getElements searches for all the Elements in any depth.
1225 Element Method: empty {#Element:empty}
1226 --------------------------------------
1228 Empties an Element of all its children.
1237 * (*element*) This Element.
1243 <div id="myElement">
1250 $('myElement').empty();
1252 ##### Resulting HTML
1254 <div id="myElement"></div>
1258 This method does not garbage collect the children. Use [Element:destroy][] instead.
1262 Element Method: destroy {#Element:destroy}
1263 ------------------------------------------
1265 Removes the Element and its children from the DOM and prepares them for garbage collection.
1269 myElement.destroy();
1277 Element Method: toQueryString {#Element:toQueryString}
1278 ------------------------------------------------------
1280 Reads the child inputs of the Element and generates a query string based on their values.
1285 var query = myElement.toQueryString();
1289 * (*string*) A string representation of a all the input Elements' names and values.
1295 <form id="myForm" action="submit.php">
1296 <input name="email" value="bob@bob.com" />
1297 <input name="zipCode" value="90210" />
1302 $('myForm').toQueryString(); // returns "email=bob@bob.com&zipCode=90210".
1305 Element Method: getSelected {#Element:getSelected}
1306 --------------------------------------------------
1308 Returns the selected options of a select element.
1313 var selected = mySelect.getSelected();
1317 * (*array*) An array of the selected elements.
1323 <select id="country-select" name="country">
1324 <option value="US">United States</option
1325 <option value ="IT">Italy</option>
1330 $('country-select').getSelected(); // returns whatever the user selected.
1334 This method returns an array, regardless of the multiple attribute of the select element.
1335 If the select is single, it will return an array with only one item.
1339 Element Method: getProperty {#Element:getProperty}
1340 --------------------------------------------------
1342 Returns a single element attribute.
1346 var myProp = myElement.getProperty(property);
1350 * property - (*string*) The property to be retrieved.
1354 * (*string*) A string containing the Element's requested property.
1360 <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1364 var imgProps = $('myImage').getProperty('src'); // returns: 'mootools.png'.
1368 Element Method: getProperties {#Element:getProperties}
1369 ------------------------------------------------------
1371 Gets multiple element attributes.
1375 var myProps = myElement.getProperties(properties);
1379 * properties - (*strings*) Any number of properties to be retrieved.
1383 * (*object*) An object containing all of the Element's requested properties.
1389 <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1393 var imgProps = $('myImage').getProperties('id', 'src', 'title', 'alt');
1394 // returns: { id: 'myImage', src: 'mootools.png', title: 'MooTools, the compact JavaScript framework', alt: '' }
1398 Element Method: setProperty {#Element:setProperty}
1399 --------------------------------------------------
1401 Sets an attribute or special property for this Element.
1406 1. property - (*string*) The property to assign the value passed in.
1407 2. value - (*mixed*) The value to assign to the property passed in.
1411 * (*element*) - This Element.
1417 <img id="myImage" />
1421 $('myImage').setProperty('src', 'mootools.png');
1423 ##### Resulting HTML
1425 <img id="myImage" src="mootools.png" />
1429 - Whenever using [Element:setProperty][] to set an attribute, pass in the lowercase, simplified form of the property. For example:
1430 - use 'for', not 'htmlFor',
1431 - use 'class', not 'className'
1432 - use 'frameborder', not 'frameBorder'
1434 - When setting the `src` property for an image file, be sure to remove the `width` and `height` attribute (use `Element.removeAttribute`). IE7, and less, set and freeze the `width` and `height` of an image if previously specified.
1436 Element Method: setProperties {#Element:setProperties}
1437 ------------------------------------------------------
1439 Sets numerous attributes for the Element.
1444 1. properties - (*object*) An object with key/value pairs.
1448 * (*element*) This Element.
1454 <img id="myImage" />
1458 $('myImage').setProperties({
1459 src: 'whatever.gif',
1460 alt: 'whatever dude'
1463 ##### Resulting HTML
1465 <img id="myImage" src="whatever.gif" alt="whatever dude" />
1469 Element Method: removeProperty {#Element:removeProperty}
1470 --------------------------------------------------------
1472 Removes an attribute from the Element.
1477 myElement.removeProperty(property);
1481 1. property - (*string*) The attribute to remove.
1485 * (*element*) This Element.
1491 <a id="myAnchor" href="#" onmousedown="alert('click');"></a>
1495 //Eww... inline JavaScript is bad! Let's get rid of it.
1496 $('myAnchor').removeProperty('onmousedown');
1498 ##### Resulting HTML
1500 <a id="myAnchor" href="#"></a>
1504 Element Method: removeProperties {#Element:removeProperties}
1505 ------------------------------------------------------------
1507 Removes numerous attributes from the Element.
1512 myElement.removeProperties(properties);
1516 1. properties - (*strings*) The attributes to remove, separated by comma.
1520 * (*element*) This Element.
1526 <a id="myAnchor" href="#" title="hello world"></a>
1530 $('myAnchor').removeProperties('id', 'href', 'title');
1532 ##### Resulting HTML
1537 Element Method: store {#Element:store}
1538 --------------------------------------
1540 Stores an item in the Elements Storage, linked to this Element.
1545 myElement.store(key, value);
1549 1. key - (*string*) The key you want to assign to the stored value.
1550 2. value - (*mixed*) Any value you want to store.
1554 * (*element*) This Element.
1558 $('element').store('someProperty', someValue);
1561 Element Method: retrieve {#Element:retrieve}
1562 --------------------------------------------
1564 Retrieves a value from the Elements storage.
1569 myElement.retrieve(key[, default]);
1573 1. key - (*string*) The key you want to retrieve from the storage.
1574 2. default - (*mixed*, optional) Default value to store and return if no value is stored.
1578 * (*mixed*) The value linked to the key.
1582 $('element').retrieve('someProperty'); // returns someValue (see example above)
1585 Element Method: eliminate {#Element:eliminate}
1586 --------------------------------------------
1588 Eliminates a key from the Elements storage.
1593 myElement.eliminate(key);
1597 1. key - (*string*) The key you want to eliminate from the storage.
1601 * (*mixed*) The element/window/document.
1605 $('element').eliminate('someProperty');
1611 Object: Element.Properties {#Element-Properties}
1612 ==============================================
1614 This Object contains the functions that respond to the first argument passed in [Element:get][], [Element:set][] and [Element:erase][].
1616 ### Adding a Custom Element Property
1618 Element.Properties.disabled = {
1621 return this.disabled;
1624 set: function(value){
1625 this.disabled = !!value;
1626 this.setAttribute('disabled', !!value);
1631 ### Using a Custom Element Property
1633 // gets the "disabled" property
1634 $(element).get('disabled');
1635 // sets the "disabled" property to true, along with the attribute
1636 $(element).set('disabled', true);
1639 ### Using an Object:
1641 Additionally, you can access these custom getters and setters using an object as the parameter for the [set](#Element:set) method.
1646 $(divElement).set({html: '<p>Hello <em>People</em>!</p>', style: 'background:red'});
1648 // for new Elements (works the same as set):
1649 new Element('input', {type: 'checkbox', checked: true, disabled: true});
1654 - Automatically returns the element for setters.
1655 - Since MooTools 1.3 this is a native JavaScript Object and not an instance of the deprecated Hash
1659 Element Property: html {#Element-Properties:html}
1660 -------------------------------------------------
1664 Sets the innerHTML of the Element.
1668 myElement.set('html', html);
1672 1. html - (*string*) The new content as HTML string.
1676 * (*element*) This Element.
1682 <div id="myElement"></div>
1686 $('myElement').set('html', '<div></div><p></p>');
1688 ##### Resulting HTML
1690 <div id="myElement">
1697 Returns the inner HTML of the Element.
1701 myElement.get('html');
1705 * (*text*) This Element's innerHTML.
1709 Element Property: text {#Element-Properties:text}
1710 -------------------------------------------------
1714 Sets the inner text of the Element.
1718 myElement.set('text', text);
1722 1. text - (*string*) The new text content for the Element.
1726 * (*element*) This Element.
1732 <div id="myElement"></div>
1736 $('myElement').set('text', 'some text');
1737 // the text of myElement is now 'some text'.
1739 ##### Resulting HTML
1741 <div id="myElement">some text</div>
1745 Gets the inner text of the Element.
1749 var myText = myElement.get('text');
1753 * (*string*) The text of the Element.
1759 <div id="myElement">my text</div>
1763 var myText = $('myElement').get('text'); // myText = 'my text'.
1767 Element Property: tag {#Element-Properties:tag}
1768 -----------------------------------------------
1772 Returns the tag name of the Element in lower case.
1776 var myTag = myElement.get('tag');
1780 * (*string*) The tag name in lower case.
1786 <img id="myImage" />
1790 var myTag = $('myImage').get('tag'); // myTag = 'img'
1794 Type: IFrame {#IFrame}
1795 ========================
1797 Custom Type to create and easily work with IFrames.
1801 IFrame Method: constructor {#IFrame:constructor}
1802 ------------------------------------------------
1804 Creates an IFrame HTML Element and extends its window and document with MooTools.
1809 var myIFrame = new IFrame([el][, props]);
1813 1. el - (*mixed*, optional) The id of the IFrame to be converted, or the actual IFrame element. If its not passed, a new IFrame will be created (default).
1814 2. props - (*object*, optional) The properties to be applied to the new IFrame. Same as [Element:constructor](#Element:constructor) props argument.
1818 * (*element*) A new IFrame HTML Element.
1822 var myIFrame = new IFrame({
1824 src: 'http://mootools.net/',
1829 border: '1px solid #ccc'
1834 mouseenter: function(){
1835 alert('Welcome aboard.');
1838 mouseleave: function(){
1843 alert('The iframe has finished loading.');
1853 - If the IFrame already exists and has a different name than id, the name will be made the same as the id.
1854 - An IFrame's window and document will not be extended with MooTools methods.
1858 Type: Elements {#Elements}
1859 ============================
1861 The Elements class allows [Element][] methods to work on an [Elements][] array, as well as [Array][] Methods.
1865 Elements Method: constructor {#Elements:constructor}
1866 ----------------------------------------------------
1871 var myElements = new Elements(elements[, options]);
1875 1. elements - (*mixed*) An array of elements or an HTMLCollection Object.
1879 * (*array*) An array-like Elements collection with the [Element][], [Elements][] and [Array][] methods.
1883 #### Set Every Paragraph's Color to Red:
1885 $$('p').each(function(el){
1886 el.setStyle('color', 'red');
1889 // Because $$('myselector') also accepts Element methods, the below
1890 // example has the same effect as the one above.
1891 $$('p').setStyle('color', 'red');
1894 #### Create Elements From an Array:
1896 var myElements = new Elements(['myElementID', $('myElement'), 'myElementID2', document.getElementById('myElementID3')]);
1901 - In MooTools, every DOM function which returns a collection of nodes (such as [$$][]) returns the nodes as instances of Elements.
1902 - Because Elements is an array-like-object, it accepts all the [Array][] methods, while giving precedence to [Element][] and [Elements][] methods.
1903 - Every node of the Elements instance has all the [Element][] methods.
1907 - [$$][], [$][], [Element][], [Elements][], [Array][]
1910 Elements Method: append {#Elements:append}
1911 ------------------------------------------
1913 Adds the items of the collection to this [Elements][] array, and return the this array.
1917 elements.append(collection);
1921 1. collection - (*array*) [Elements][] array or an array of HTML Elements.
1925 * (*array*) This [Elements][] array.
1929 - This method doesn't process ([document:id][] or filters) the items of the array.
1932 Elements Method: concat {#Elements:concat}
1933 ------------------------------------------
1935 Adds the element, or array of Elements, to this [Elements][] array, and returns a new [Elements][] array.
1939 var newElements = elements.concat(element[, list, id, ...]]);
1943 1. element - (*mixed*) An HTML Element, or a string id.
1944 2. list, id, ... - (*mixed*) Additional [Elements][], array of ids, or string ids.
1948 * (*array*) A new [Elements][] array.
1951 Elements Method: empty {#Elements:empty}
1952 ------------------------------------------
1954 Removes every item from the [Elements][] array, and the empty array.
1962 * (*array*) This empty [Elements][] array.
1966 `Elements.empty` does not destroy the elements inside. As best practice, always destroy your elements if they're no longer in use. For example:
1968 $$('div').destroy().empty();
1972 - [Element:destroy][]
1976 Elements Method: filter {#Elements:filter}
1977 ------------------------------------------
1979 Filters a collection of elements by a given css selector, or filtering function like [Array:filter][].
1984 var filteredElements = elements.filter(selector);
1988 1. selector - (*mixed*) A single CSS selector, or filtering function.
1992 * (*array*) A subset of this [Elements][] instance.
1995 Elements Method: push {#Elements:push}
1996 --------------------------------------
1998 Adds the element, or elements, to the end of this [Elements][] array and returns the length of the array.
2003 var length = elements.push(element[, id, ...]]);
2007 1. element - (*mixed*) An HTML Element, or a string id.
2008 2. id, ... - (*mixed*) Additional HTML Element, or string ids.
2012 * (*number*) The new length of the [Elements][] array.
2015 Elements Method: unshift {#Elements:unshift}
2016 --------------------------------------------
2018 Adds the element, or elements, to the front of this [Elements][] array and returns the length of the array.
2022 var length = elements.unshift(element[, id, ...]]);
2026 1. element - (*mixed*) An HTML Element, or a string id.
2027 2. id, ... - (*mixed*) Additional HTML Element, or string ids.
2031 * (*number*) The new length of the [Elements][] array.
2034 Deprecated Functions {#Deprecated-Functions}
2035 ============================================
2037 Element Method: hasChild {#Deprecated-Functions:hasChild}
2038 ---------------------------------------------------------
2040 This method has been deprecated. Use [Element:contains][] instead.
2044 var myElement = document.id('element1');
2045 var myElement2 = document.id('element2');
2046 myElement !== myElement2 && myElement.contains(element2);
2048 // could be implemented as:
2049 Element.implement('hasChild', function(element){
2050 return this !== element && this.contains(element);
2053 Element Method: injectBefore {#Deprecated-Functions:injectBefore}
2054 -----------------------------------------------------------------
2056 This method has been deprecated. Use [Element:inject][] instead.
2058 Element Method: injectAfter {#Deprecated-Functions:injectAfter}
2059 ---------------------------------------------------------------
2061 This method has been deprecated. Use [Element:inject][] instead.
2063 Element Method: injectBottom {#Deprecated-Functions:injectBottom}
2064 -----------------------------------------------------------------
2066 This method has been deprecated. Use [Element:inject][] instead.
2068 Element Method: injectTop {#Deprecated-Functions:injectTop}
2069 -----------------------------------------------------------
2071 This method has been deprecated. Use [Element:inject][] instead.
2073 Element Method: injectInside {#Deprecated-Functions:injectInside}
2074 -----------------------------------------------------------------
2076 This method has been deprecated. Use [Element:inject][] instead.
2078 Element Method: grabBefore {#Deprecated-Functions:grabBefore}
2079 -----------------------------------------------------------------
2081 This method has been deprecated. Use [Element:grab][] instead.
2083 Element Method: grabAfter {#Deprecated-Functions:grabAfter}
2084 ---------------------------------------------------------------
2086 This method has been deprecated. Use [Element:grab][] instead.
2088 Element Method: grabBottom {#Deprecated-Functions:grabBottom}
2089 -----------------------------------------------------------------
2091 This method has been deprecated. Use [Element:grab][] instead.
2093 Element Method: grabTop {#Deprecated-Functions:grabTop}
2094 -----------------------------------------------------------
2096 This method has been deprecated. Use [Element:grab][] instead.
2098 Element Method: grabInside {#Deprecated-Functions:grabInside}
2099 -----------------------------------------------------------------
2101 This method has been deprecated. Use [Element:grab][] instead.
2104 Elements Method: extend {#Deprecated-Functions:extend}
2105 ------------------------------------------------------
2107 This method has been deprecated. Use [Elements:append][] instead.
2110 [document:id]: #Window:document-id
2112 [$$]: #Window:dollars
2114 [Array]: /core/Types/Array
2115 [Array:filter]: /core/Types/Array#Array:filter
2118 [Elements]: #Elements
2119 [Elements:append]: #Elements:append
2120 [Element:inject]: #Element:inject
2121 [Element:set]: #Element:set
2122 [Element:get]: #Element:get
2123 [Element:destroy]: #Element:destroy
2124 [Element:grab]: #Element:grab
2125 [Element:erase]: #Element:erase
2126 [Element:setProperty]: #Element:setProperty
2127 [Element:getProperty]: #Element:getProperty
2128 [Element:removeProperty]: #Element:removeProperty
2129 [Element:getElement]: #Element:getElement
2130 [Element:getElements]: #Element:getElements
2131 [Element.Properties]: #Element-Properties
2132 [Element:getPrevious]: #Element:getPrevious
2133 [Element:getAllPrevious]: #Element:getAllPrevious
2134 [Element:contains]: #Element:contains
2136 [Element:addEvents]: /core/Element/Element.Event#Element:addEvents
2137 [Element:setStyles]: /core/Element/Element.Style#Element:setStyles
2139 [The Dollar Safe Mode]: http://mootools.net/blog/2009/06/22/the-dollar-safe-mode/
2141 [MDN Element:removeChild]: https://developer.mozilla.org/En/DOM/Node.removeChild
2142 [MDN Element:replaceChild]: https://developer.mozilla.org/En/DOM/Node.replaceChild
2143 [MDN Element:insertAdjacentHTML]: https://developer.mozilla.org/en/DOM/Element.insertAdjacentHTML