Docs/Element/Element.md

   1 Type: Window {#Window}
   2 ======================
   3
   4 The following functions are treated as Window methods.
   5
   6 Function: document.id {#Window:document-id}
   7 -------------------------------------------
   8
   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.
  10
  11 ### Syntax:
  12
  13         var myElement = document.id(el);
  14
  15 ### Arguments:
  16
  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.
  21
  22 ### Returns:
  23
  24 * (*element*) A DOM element.
  25 * (*null*) Null if no matching id was found or if toElement did not return an element.
  26
  27 ### Examples:
  28
  29 #### Get a DOM Element by ID:
  30
  31         var myElement = document.id('myElement');
  32
  33 #### Get a DOM Element by reference:
  34
  35         var div = document.getElementById('myElement');
  36         div = document.id(div); // the element with all the Element methods applied.
  37
  38 ### Notes:
  39
  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.
  44
  45
  46 Function: $ {#Window:dollar}
  47 ----------------------------
  48
  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.
  51
  52 ### Examples:
  53
  54         var myElement = $('myElement');
  55         var myElement2 = document.id('myElement');
  56
  57         myElement == myElement2; // returns true
  58
  59
  60         (function($){
  61
  62                 // Now you can use $ safely in this closure
  63
  64         })(document.id)
  65
  66
  67 ### See Also:
  68  - MooTools Blogpost: [The Dollar Safe Mode][]
  69
  70
  71 Function: $$ {#Window:dollars}
  72 ------------------------------
  73
  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.
  76
  77 ### Syntax:
  78
  79         var myElements = $$(argument);
  80
  81 ### Arguments:
  82
  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
  86
  87 ### Returns:
  88
  89 * (*elements*) - An array-like Elements collection of all the DOM elements matched, extended with [document:id][].
  90
  91 ### Examples:
  92
  93 #### Get Elements by Their Tag Names:
  94
  95         $$('a'); // returns all anchor elements in the page.
  96
  97 #### Get an Elements instance by passing multiple elements:
  98
  99         $$(element1, element2, element3); // returns an Elements instance containing these 3 elements.
 100
 101 #### Convert any array or collection of elements to an Elements instance:
 102
 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.
 105
 106 #### Using CSS Selectors:
 107
 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.
 111
 112 ### Notes:
 113
 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).
 118
 119
 120 Type: Element {#Element}
 121 ========================
 122
 123 Custom Type to allow all of its methods to be used with any extended DOM Element.
 124
 125
 126
 127 Element Method: constructor {#Element:constructor}
 128 --------------------------------------------------
 129
 130 Creates a new Element of the type passed in.
 131
 132 ### Syntax:
 133
 134         var myEl = new Element(element[, properties]);
 135
 136 ### Arguments:
 137
 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.
 140
 141 ### Returns:
 142
 143 * (*element*) A new MooTools extended HTML Element.
 144
 145 ### Examples:
 146
 147         // Creating an new anchor with an Object
 148         var myAnchor = new Element('a', {
 149                 href: 'http://mootools.net',
 150                 'class': 'myClass',
 151                 html: 'Click me!',
 152                 styles: {
 153                         display: 'block',
 154                         border: '1px solid black'
 155                 },
 156                 events: {
 157                         click: function(){
 158                                 alert('clicked');
 159                         },
 160                         mouseover: function(){
 161                                 alert('mouseovered');
 162                         }
 163                 }
 164         });
 165
 166         // Using Selectors
 167         var myNewElement = new Element('a.myClass');
 168
 169 ### Note:
 170
 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>`.
 172
 173 ### See Also:
 174
 175 - [$][], [Element:set][]
 176
 177
 178
 179 Element Method: getElement {#Element:getElement}
 180 ------------------------------------------------
 181
 182 Gets the first descendant element whose tag name matches the tag provided. CSS selectors may also be passed.
 183
 184 ### Syntax:
 185
 186         var myElement = myElement.getElement(tag);
 187
 188 ### Arguments:
 189
 190 1. tag - (*string*) Tag name of the element to find or a CSS Selector.
 191
 192 ### Returns:
 193
 194 * (*mixed*) If a match is found, the Element will be returned. Otherwise, returns null.
 195
 196 ### Examples:
 197
 198         var firstDiv = $(document.body).getElement('div');
 199
 200 ### Notes:
 201
 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).
 204
 205
 206
 207 Element Method: getElements {#Element:getElements}
 208 --------------------------------------------------
 209
 210 Collects all descendant elements whose tag name matches the tag provided. CSS selectors may also be passed.
 211
 212 ### Syntax:
 213
 214         var myElements = myElement.getElements(tag);
 215
 216 ### Arguments:
 217
 218 1. tag - (*string*) String of the tag to match  or a CSS Selector.
 219
 220 ### Returns:
 221
 222 * (*array*) An [Elements][] array of all matched Elements.
 223
 224 ### Examples:
 225
 226         var allAnchors = $(document.body).getElements('a');
 227
 228 ### Notes:
 229
 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).
 232
 233
 234
 235 Element Method: getElementById {#Element:getElementById}
 236 --------------------------------------------------------
 237
 238 Gets the element with the specified id found inside the current Element.
 239
 240 ### Syntax:
 241
 242         var myElement = anElement.getElementById(id);
 243
 244 ### Arguments:
 245
 246 1. id - (*string*) The ID of the Element to find.
 247
 248 ### Returns:
 249
 250 * (*mixed*) If a match is found, returns that Element. Otherwise, returns null.
 251
 252 ### Examples:
 253
 254         var myChild = $('myParent').getElementById('myChild');
 255
 256 ### Notes:
 257
 258 - This method is not provided for Document instances as document.getElementById is provided natively.
 259
 260
 261
 262 Element Method: set {#Element:set}
 263 ----------------------------
 264
 265 This is a "dynamic arguments" method. Properties passed in can be any of the 'set' properties in the [Element.Properties][] Object.
 266
 267 ### Syntax:
 268
 269         myElement.set(arguments);
 270
 271 ### Arguments:
 272
 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).
 278
 279 ### Returns:
 280
 281 * (*element*) This Element.
 282
 283 ### Examples:
 284
 285 #### With Property and Value:
 286
 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', {
 291                 font: '12px Arial',
 292                 color: 'blue'
 293         });
 294
 295 #### With an Object:
 296
 297         var myElement = $('myElement').set({
 298                 // the 'styles' property passes the object to Element:setStyles.
 299                 styles: {
 300                         font: '12px Arial',
 301                         color: 'blue',
 302                         border: '1px solid #f00'
 303                 },
 304                 // the 'events' property passes the object to Element:addEvents.
 305                 events: {
 306                         click: function(){ alert('click'); },
 307                         mouseover: function(){ this.addClass('over'); }
 308                 },
 309                 //Any other property uses Element:setProperty.
 310                 id: 'documentBody'
 311         });
 312
 313 ### Notes:
 314
 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'
 321         - etc.
 322 - In IE8 or lower, it is not possible to set `type` multiple times. It will throw an error.
 323
 324
 325 ### See Also:
 326
 327 - [Element][], [Element.Properties][], [Element:setProperty][], [Element:addEvents][], [Element:setStyles][]
 328
 329
 330
 331 Element Method: get {#Element:get}
 332 ----------------------------------
 333
 334 This is a "dynamic arguments" method. Properties passed in can be any of the 'get' properties in the [Element.Properties][] Object.
 335
 336 ### Syntax:
 337
 338         myElement.get(property);
 339
 340 ### Arguments:
 341
 342 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to get.
 343
 344 ### Returns:
 345
 346 * (*mixed*) The result of calling the corresponding 'get' function in the [Element.Properties][] Object.
 347
 348 ### Examples:
 349
 350 #### Using Custom Getters:
 351
 352         var tag = $('myDiv').get('tag'); // returns "div".
 353
 354 #### Fallback to Element Attributes:
 355
 356         var id = $('myDiv').get('id'); // returns "myDiv".
 357         var value = $('myInput').get('value'); // returns the myInput element's value.
 358
 359 ### Notes:
 360
 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.
 362
 363 ### See Also:
 364
 365 - [Element][], [Element.Properties][], [Element:getProperty][]
 366
 367
 368
 369 Element Method: erase {#Element:erase}
 370 --------------------------------------
 371
 372 This is a "dynamic arguments" method. Properties passed in can be any of the 'erase' properties in the [Element.Properties][] Object.
 373
 374 ### Syntax:
 375
 376         myElement.erase(property);
 377
 378 ### Arguments:
 379
 380 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to erase.
 381
 382 ### Returns:
 383
 384 * (*mixed*) The result of calling the corresponding 'erase' function in the [Element.Properties][] Object.
 385
 386 ### Examples:
 387
 388         $('myDiv').erase('id'); //Removes the id from myDiv.
 389         $('myDiv').erase('class'); //myDiv element no longer has any class names set.
 390
 391 ### Note:
 392
 393 -  If the corresponding eraser doesn't exist in the  [Element.Properties][] Object, [Element:removeProperty][] is called with the property passed in.
 394
 395 ### See Also:
 396
 397 - [Element][], [Element.Properties][], [Element:removeProperty][]
 398
 399
 400
 401 Element Method: match {#Element:match}
 402 --------------------------------------
 403
 404 Tests this Element to see if it matches the argument passed in.
 405
 406 ### Syntax:
 407
 408         myElement.match(match);
 409
 410 ### Arguments:
 411
 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.
 415
 416 ### Returns:
 417
 418 * (*boolean*) If the element matched, returns true. Otherwise, returns false.
 419
 420 ### Examples:
 421
 422 #### Using a Tag Name:
 423
 424         // returns true if #myDiv is a div.
 425         $('myDiv').match('div');
 426
 427 #### Using a CSS Selector:
 428
 429         // returns true if #myDiv has the class foo and is named "bar"
 430         $('myDiv').match('.foo[name=bar]');
 431
 432 #### Using an Element:
 433
 434         var el = $('myDiv');
 435         $('myDiv').match(el); // returns true
 436         $('otherElement').match(el); // returns false
 437
 438
 439
 440 Element Method: contains {#Element:contains}
 441 --------------------------------------------
 442
 443 Checks all descendants of this Element for a match.
 444
 445
 446 ### Syntax:
 447
 448         var result = myElement.contains(el);
 449
 450 ### Arguments:
 451
 452 1. el - (*element*) The element to search for.
 453
 454 ### Returns:
 455
 456 * (*boolean*) Returns true if the element contains passed in Element is a child, otherwise false.
 457
 458 ### Examples:
 459
 460 ##### HTML
 461
 462         <div id="Darth_Vader">
 463                 <div id="Luke"></div>
 464         </div>
 465
 466 ##### JavaScript
 467
 468         if ($('Darth_Vader').contains($('Luke'))) alert('Luke, I am your father.'); //tan tan tannn...
 469
 470
 471
 472 Element Method: inject {#Element:inject}
 473 ----------------------------------------
 474
 475 Injects, or inserts, the Element at a particular place relative to the Element's children (specified by the second the argument).
 476
 477 ### Syntax:
 478
 479         myElement.inject(el[, where]);
 480
 481 ### Arguments:
 482
 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'.
 485
 486 ### Returns:
 487
 488 * (*element*) This Element.
 489
 490 ### Examples:
 491
 492 ##### JavaScript
 493
 494         var myFirstElement  = new Element('div', {id: 'myFirstElement'});
 495         var mySecondElement = new Element('div', {id: 'mySecondElement'});
 496         var myThirdElement  = new Element('div', {id: 'myThirdElement'});
 497
 498 ##### Resulting HTML
 499
 500         <div id="myFirstElement"></div>
 501         <div id="mySecondElement"></div>
 502         <div id="myThirdElement"></div>
 503
 504 #### Inject to the bottom:
 505
 506 ##### JavaScript
 507
 508         myFirstElement.inject(mySecondElement);
 509
 510 ##### Resulting HTML
 511
 512         <div id="mySecondElement">
 513                 <div id="myFirstElement"></div>
 514         </div>
 515
 516 #### Inject to the top:
 517
 518 ##### JavaScript
 519
 520         myThirdElement.inject(mySecondElement, 'top');
 521
 522 ##### Resulting HTML
 523
 524         <div id="mySecondElement">
 525                 <div id="myThirdElement"></div>
 526                 <div id="myFirstElement"></div>
 527         </div>
 528
 529 #### Inject before:
 530
 531 ##### JavaScript
 532
 533         myFirstElement.inject(mySecondElement, 'before');
 534
 535 ##### Resulting HTML
 536
 537         <div id="myFirstElement"></div>
 538         <div id="mySecondElement"></div>
 539
 540 #### Inject After:
 541
 542 ##### JavaScript
 543
 544         myFirstElement.inject(mySecondElement, 'after');
 545
 546 ##### Resulting HTML
 547
 548         <div id="mySecondElement"></div>
 549         <div id="myFirstElement"></div>
 550
 551 ### See Also:
 552
 553 [Element:adopt](#Element:adopt), [Element:grab](#Element:grab), [Element:wraps](#Element:wraps)
 554
 555
 556
 557 Element Method: grab {#Element:grab}
 558 ------------------------------------
 559
 560 Works as [Element:inject](#Element:inject), but in reverse.
 561
 562 Appends the Element at a particular place relative to the Element's children (specified by the where parameter).
 563
 564 ### Syntax:
 565
 566         myElement.grab(el[, where]);
 567
 568 ### Arguments:
 569
 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'.
 572
 573 ### Returns:
 574
 575 * (*element*) This Element.
 576
 577 ### Examples:
 578
 579 ##### HTML
 580
 581         <div id="first">
 582                 <div id="child"></div>
 583         </div>
 584
 585 ##### JavaScript
 586
 587         var mySecondElement = new Element('div#second');
 588         $('first').grab(mySecondElement);
 589
 590 ##### Resulting HTML
 591
 592         <div id="first">
 593                 <div id="child"></div>
 594                 <div id="second"></div>
 595         </div>
 596
 597 ##### JavaScript
 598
 599         var mySecondElement = new Element('div#second');
 600         myFirstElement.grab(mySecondElement, 'top');
 601
 602 ##### Resulting HTML
 603
 604         <div id="first">
 605                 <div id="second"></div>
 606                 <div id="child"></div>
 607         </div>
 608
 609 ### See Also:
 610
 611 [Element:adopt](#Element:adopt), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
 612
 613
 614
 615 Element Method: adopt {#Element:adopt}
 616 --------------------------------------
 617
 618 Works like [Element:grab](#Element:grab), but allows multiple elements to be adopted and only appended at the bottom.
 619
 620 Inserts the passed element(s) inside the Element (which will then become the parent element).
 621
 622 ### Syntax:
 623
 624         myParent.adopt(el[, others]);
 625
 626 ### Arguments:
 627
 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.
 630
 631 ### Returns:
 632
 633 * (*element*) This Element.
 634
 635 ### Examples:
 636
 637 ##### JavaScript
 638
 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');
 643
 644         var myParentElement = new Element('div#parent');
 645
 646         myFirstElement.adopt(mySecondElement);
 647         mySecondElement.adopt(myThirdElement, myFourthElement);
 648         myParentElement.adopt([myFirstElement, new Element('span#another')]);
 649
 650 ##### Resulting HTML
 651
 652         <div id="parent">
 653                 <div id="first">
 654                         <p id="second">
 655                                 <ul id="third"></ul>
 656                                 <a id="fourth"></a>
 657                         </p>
 658                 </div>
 659                 <span id="another"></span>
 660         </div>
 661
 662 ### See Also:
 663
 664 [Element:grab](#Element:grab), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
 665
 666
 667
 668 Element Method: wraps {#Element:wraps}
 669 --------------------------------------
 670
 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.
 672
 673 ### Syntax:
 674
 675         myParent.wraps(el[, where]);
 676
 677 ### Arguments:
 678
 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'.
 681
 682 ### Returns:
 683
 684 * (*element*) This Element.
 685
 686 ### Examples:
 687
 688 ##### HTML
 689
 690         <div id="first"></div>
 691
 692 ##### JavaScript
 693
 694         var mySecondElement = new Element('div#second').wraps('first');
 695
 696 ##### Resulting HTML
 697
 698         <div id="second">
 699                 <div id="first"></div>
 700         </div>
 701
 702 ##### HTML
 703
 704         <div id="first"></div>
 705         <div id="second">
 706                 <div id="child"></div>
 707         </div>
 708
 709 ##### JavaScript
 710
 711         $('second').wraps('first');
 712
 713 ##### Resulting HTML
 714
 715         <div id="second">
 716                 <div id="child"></div>
 717                 <div id="first"></div>
 718         </div>
 719
 720 ##### JavaScript
 721
 722         $('second').wraps('first', 'top');
 723
 724 ##### Resulting HTML
 725
 726         <div id="second">
 727                 <div id="first"></div>
 728                 <div id="child"></div>
 729         </div>
 730
 731 Element Method: appendHTML {#Element:appendHTML}
 732 ------------------------------------------------
 733
 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
 736 was called.
 737
 738 ### Syntax:
 739
 740         myElement.appendHTML(html[, where]);
 741
 742 ### Arguments:
 743
 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'.
 746
 747 ### Returns:
 748
 749 * (*element*) The current Element instance.
 750
 751 ### Examples:
 752
 753 ##### HTML
 754
 755         <div id="myElement">Hey.</div>
 756
 757 ##### JavaScript
 758
 759         $('myElement').appendHTML(' <strong>Howdy.</strong>');
 760
 761 ##### Resulting HTML
 762
 763         <div id="myElement">Hey. <strong>Howdy.</strong></div>
 764
 765 ### Notes:
 766
 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.
 771
 772 ### See Also:
 773
 774 - [MDN Element:insertAdjacentHTML][].
 775
 776
 777 Element Method: appendText {#Element:appendText}
 778 ------------------------------------------------
 779
 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.
 782
 783 ### Syntax:
 784
 785         myElement.appendText(text[, where]);
 786
 787 ### Arguments:
 788
 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'.
 791
 792 ### Returns:
 793
 794 * (*element*) The current Element instance.
 795
 796 ### Examples:
 797
 798 ##### HTML
 799
 800         <div id="myElement">Hey.</div>
 801
 802 ##### JavaScript
 803
 804         $('myElement').appendText(' Howdy.');
 805
 806 ##### Resulting HTML
 807
 808         <div id="myElement">Hey. Howdy.</div>
 809
 810
 811
 812 Element Method: dispose {#Element:dispose}
 813 ------------------------------------------
 814
 815 Removes the Element from the DOM.
 816
 817
 818 ### Syntax:
 819
 820         var removedElement = myElement.dispose();
 821
 822 ### Returns:
 823
 824 * (*element*) This Element. Useful to always grab the return from this function, as the element could be [injected](#Element:inject) back.
 825
 826 ### Examples:
 827
 828 ##### HTML
 829
 830         <div id="myElement"></div>
 831         <div id="mySecondElement"></div>
 832
 833 ##### JavaScript
 834
 835         $('myElement').dispose();
 836
 837 ##### Resulting HTML
 838
 839         <div id="mySecondElement"></div>
 840
 841 ### See Also:
 842
 843 - [MDN Element:removeChild][]
 844
 845
 846
 847 Element Method: clone {#Element:clone}
 848 --------------------------------------
 849
 850 Clones the Element and returns the cloned one.
 851
 852
 853 ### Syntax:
 854
 855         var copy = myElement.clone([contents, keepid]);
 856
 857 ### Arguments:
 858
 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.
 861
 862
 863 ### Returns:
 864
 865 * (*element*) The cloned Element.
 866
 867 ### Examples:
 868
 869 ##### HTML
 870
 871         <div id="myElement">ciao</div>
 872
 873 ##### JavaScript
 874
 875         // clones the Element and appends the clone after the Element.
 876         var clone = $('myElement').clone().inject('myElement','after');
 877
 878 ##### Resulting HTML
 879
 880         <div id="myElement">ciao</div>
 881         <div>ciao</div>
 882
 883 ### Note:
 884
 885 - The returned Element does not have attached events. To clone the events use [Element:cloneEvents](/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.
 888
 889 ### See Also:
 890
 891 - [Element:cloneEvents](/Element/Element.Event#Element:cloneEvents).
 892
 893
 894
 895 Element Method: replaces {#Element:replaces}
 896 --------------------------------------------------
 897
 898 Replaces the passed Element with Element.
 899
 900 ### Syntax:
 901
 902         var element = myElement.replaces(el);
 903
 904 ### Arguments:
 905
 906 1. el - (*mixed*) A string id representing the Element to be replaced, or an Element reference.
 907
 908 ### Returns:
 909
 910 * (*element*) This Element.
 911
 912 ### Examples:
 913
 914         $('myNewElement').replaces($('myOldElement'));
 915         //$('myOldElement') is gone, and $('myNewElement') is in its place.
 916
 917 ### See Also:
 918
 919 - [MDN Element:replaceChild][]
 920
 921
 922
 923 Element Method: hasClass {#Element:hasClass}
 924 --------------------------------------------
 925
 926 Tests the Element to see if it has the passed in className.
 927
 928 ### Syntax:
 929
 930         var result = myElement.hasClass(className);
 931
 932 ### Arguments:
 933
 934 1. className - (*string*) The class name to test.
 935
 936 ### Returns:
 937
 938 * (*boolean*) Returns true if the Element has the class, otherwise false.
 939
 940 ### Examples:
 941
 942 ##### HTML
 943
 944         <div id="myElement" class="testClass"></div>
 945
 946 ##### JavaScript
 947
 948         $('myElement').hasClass('testClass'); // returns true
 949
 950
 951
 952 Element Method: addClass {#Element:addClass}
 953 --------------------------------------------
 954
 955 Adds the passed in class to the Element, if the Element doesnt already have it.
 956
 957 ### Syntax:
 958
 959         myElement.addClass(className);
 960
 961 ### Arguments:
 962
 963 1. className - (*string*) The class name to add.
 964
 965 ### Returns:
 966
 967 * (*element*) This Element.
 968
 969 ### Examples:
 970
 971 ##### HTML
 972
 973         <div id="myElement" class="testClass"></div>
 974
 975 ##### JavaScript
 976
 977         $('myElement').addClass('newClass');
 978
 979 ##### Resulting HTML
 980
 981         <div id="myElement" class="testClass newClass"></div>
 982
 983
 984
 985 Element Method: removeClass {#Element:removeClass}
 986 ----------------------------
 987
 988 Works like [Element:addClass](#Element:addClass), but removes the class from the Element.
 989
 990
 991 ### Syntax:
 992
 993         myElement.removeClass(className);
 994
 995 ### Arguments:
 996
 997 1. className - (*string*) The class name to remove.
 998
 999 ### Returns:
1000
1001 * (*element*) This Element.
1002
1003 ### Examples:
1004
1005 ##### HTML
1006
1007         <div id="myElement" class="testClass newClass"></div>
1008
1009 ##### JavaScript
1010
1011         $('myElement').removeClass('newClass');
1012
1013 ##### Resulting HTML
1014
1015         <div id="myElement" class="testClass"></div>
1016
1017
1018
1019 Element Method: toggleClass {#Element:toggleClass}
1020 --------------------------------------------------
1021
1022 Adds or removes the passed in class name to the Element, depending on whether or not it's already present.
1023
1024 ### Syntax:
1025
1026         myElement.toggleClass(className, force);
1027
1028 ### Arguments:
1029
1030 1. className - (*string*) The class to add or remove.
1031 2. force - (*boolean*, optional) Force the class to be either added or removed
1032
1033 ### Returns:
1034
1035 * (*element*) This Element.
1036
1037 ### Examples:
1038
1039 ##### HTML
1040
1041         <div id="myElement" class="myClass"></div>
1042
1043 ##### JavaScript
1044
1045         $('myElement').toggleClass('myClass');
1046
1047 ##### Resulting HTML
1048
1049         <div id="myElement" class=""></div>
1050
1051 ##### JavaScript
1052
1053         $('myElement').toggleClass('myClass');
1054
1055 ##### Resulting HTML
1056
1057         <div id="myElement" class="myClass"></div>
1058
1059
1060
1061 Element Method: getPrevious {#Element:getPrevious}
1062 --------------------------------------------------
1063
1064 Returns the previousSibling of the Element (excluding text nodes).
1065
1066 ### Syntax:
1067
1068         var previousSibling = myElement.getPrevious([match]);
1069
1070 ### Arguments:
1071
1072 1. match - (*string*, optional): A tag name to match the the found element(s) with. A full CSS selector can be passed.
1073
1074 ### Returns:
1075
1076 * (*mixed*) The previous sibling Element or null if none found.
1077
1078
1079
1080 Element Method: getAllPrevious {#Element:getAllPrevious}
1081 --------------------------------------------------------
1082
1083 Like [Element:getPrevious][], but returns a collection of all the matched previousSiblings.
1084
1085
1086
1087 Element Method: getNext {#Element:getNext}
1088 ------------------------------------------
1089
1090 As [Element:getPrevious][], but tries to find the nextSibling (excluding text nodes).
1091
1092
1093 ### Syntax:
1094
1095         var nextSibling = myElement.getNext([match]);
1096
1097 ### Arguments:
1098
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.
1100
1101 ### Returns:
1102
1103 * (*mixed*) The next sibling Element or null if none found.
1104
1105
1106 Element Method: getAllNext {#Element:getAllNext}
1107 ------------------------------------------------
1108
1109 Like Element.getNext, but returns a collection of all the matched nextSiblings.
1110
1111
1112
1113 Element Method: getFirst {#Element:getFirst}
1114 --------------------------------------------
1115
1116 Gets the first element that matches the passed in expression.
1117
1118
1119 ### Syntax:
1120
1121         var firstElement = myElement.getFirst([match]);
1122
1123 ### Arguments:
1124
1125 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1126
1127 ### Returns:
1128
1129 * (*mixed*) The first found element or null if none found.
1130
1131
1132
1133 Element Method: getLast {#Element:getLast}
1134 ------------------------------------------
1135
1136 Gets the last element that matches the passed in expression.
1137
1138 ### Syntax:
1139
1140         var lastElement = myElement.getLast([match]);
1141
1142 ### Arguments:
1143
1144 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1145
1146 ### Returns:
1147
1148 * (*mixed*) The last found element, or returns null if none found.
1149
1150
1151
1152 Element Method: getParent {#Element:getParent}
1153 ----------------------------------------------
1154
1155 Works as [Element:getPrevious][], but tries to find the parentNode.
1156
1157
1158 ### Syntax:
1159
1160         var parent = myElement.getParent([match]);
1161
1162 ### Arguments:
1163
1164 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1165
1166 ### Returns:
1167
1168 * (*mixed*) The target Element's parent or null if no matching parent is found.
1169
1170
1171
1172 Element Method: getParents {#Element:getParents}
1173 ------------------------------------------------
1174
1175 Like [Element:getParent](#Element:getParent), but returns a collection of all the matched parentNodes up the tree.
1176
1177 ### Returns:
1178
1179 * (*array*) If no matching parents are found, an empty array is returned.
1180
1181
1182
1183 Element Method: getSiblings {#Element:getSiblings}
1184 --------------------------------------------------
1185
1186 Like [Element:getAllPrevious][] but returns all Element's previous and next siblings (excluding text nodes). Returns as [Elements][].
1187
1188
1189 ### Syntax:
1190
1191         var siblings = myElement.getSiblings([match]);
1192
1193 ### Arguments:
1194
1195 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1196
1197 ### Returns:
1198
1199 * (*array*) A [Elements](#Elements) array with all of the Element's siblings, except the text nodes.
1200
1201
1202
1203 Element Method: getChildren {#Element:getChildren}
1204 --------------------------------------------------
1205
1206 Returns all the Element's children (excluding text nodes). Returns as [Elements][].
1207
1208
1209 ### Syntax:
1210
1211         var children = myElement.getChildren([match]);
1212
1213 ### Arguments:
1214
1215 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1216
1217 ### Returns:
1218
1219 * (*array*) A [Elements](#Elements) array with all of the Element's children, except the text nodes.
1220
1221 ### Note:
1222
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.
1224
1225 Element Method: empty {#Element:empty}
1226 --------------------------------------
1227
1228 Empties an Element of all its children.
1229
1230
1231 ### Syntax:
1232
1233         myElement.empty();
1234
1235 ### Returns:
1236
1237 * (*element*) This Element.
1238
1239 ### Examples:
1240
1241 ##### HTML
1242
1243         <div id="myElement">
1244                 <p></p>
1245                 <span></span>
1246         </div>
1247
1248 ##### JavaScript
1249
1250         $('myElement').empty();
1251
1252 ##### Resulting HTML
1253
1254         <div id="myElement"></div>
1255
1256 ### Note:
1257
1258 This method does not garbage college the children. Use [Element:destroy][] instead.
1259
1260
1261
1262 Element Method: destroy {#Element:destroy}
1263 ------------------------------------------
1264
1265 Removes the Element and its children from the DOM and prepares them for garbage collection.
1266
1267 ### Syntax:
1268
1269         myElement.destroy();
1270
1271 ### Returns:
1272
1273 * (*null*)
1274
1275
1276
1277 Element Method: toQueryString {#Element:toQueryString}
1278 ------------------------------------------------------
1279
1280 Reads the child inputs of the Element and generates a query string based on their values.
1281
1282
1283 ### Syntax:
1284
1285         var query = myElement.toQueryString();
1286
1287 ### Returns:
1288
1289 * (*string*) A string representation of a all the input Elements' names and values.
1290
1291 ### Examples:
1292
1293 ##### HTML
1294
1295         <form id="myForm" action="submit.php">
1296                 <input name="email" value="bob@bob.com" />
1297                 <input name="zipCode" value="90210" />
1298         </form>
1299
1300 ##### JavaScript
1301
1302         $('myForm').toQueryString(); // returns "email=bob@bob.com&zipCode=90210".
1303
1304
1305 Element Method: getSelected {#Element:getSelected}
1306 --------------------------------------------------
1307
1308 Returns the selected options of a select element.
1309
1310
1311 ### Syntax:
1312
1313         var selected = mySelect.getSelected();
1314
1315 ### Returns:
1316
1317 * (*array*) An array of the selected elements.
1318
1319 ### Examples:
1320
1321 ##### HTML
1322
1323         <select id="country-select" name="country">
1324                 <option value="US">United States</option
1325                 <option value ="IT">Italy</option>
1326         </select>
1327
1328 ##### JavaScript
1329
1330         $('country-select').getSelected(); // returns whatever the user selected.
1331
1332 ### Note:
1333
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.
1336
1337
1338
1339 Element Method: getProperty {#Element:getProperty}
1340 --------------------------------------------------
1341
1342 Returns a single element attribute.
1343
1344 ### Syntax:
1345
1346         var myProp = myElement.getProperty(property);
1347
1348 ### Arguments:
1349
1350 * property - (*string*) The property to be retrieved.
1351
1352 ### Returns:
1353
1354 * (*string*) A string containing the Element's requested property.
1355
1356 ### Examples:
1357
1358 ##### HTML
1359
1360         <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1361
1362 ##### JavaScript
1363
1364         var imgProps = $('myImage').getProperty('src'); // returns: 'mootools.png'.
1365
1366
1367
1368 Element Method: getProperties {#Element:getProperties}
1369 ------------------------------------------------------
1370
1371 Gets multiple element attributes.
1372
1373 ### Syntax:
1374
1375         var myProps = myElement.getProperties(properties);
1376
1377 ### Arguments:
1378
1379 * properties - (*strings*) Any number of properties to be retrieved.
1380
1381 ### Returns:
1382
1383 * (*object*) An object containing all of the Element's requested properties.
1384
1385 ### Examples:
1386
1387 ##### HTML
1388
1389         <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1390
1391 ##### JavaScript
1392
1393         var imgProps = $('myImage').getProperties('id', 'src', 'title', 'alt');
1394         // returns: { id: 'myImage', src: 'mootools.png', title: 'MooTools, the compact JavaScript framework', alt: '' }
1395
1396
1397
1398 Element Method: setProperty {#Element:setProperty}
1399 --------------------------------------------------
1400
1401 Sets an attribute or special property for this Element.
1402
1403
1404 ### Arguments:
1405
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.
1408
1409 ### Returns:
1410
1411 * (*element*) - This Element.
1412
1413 ### Examples:
1414
1415 ##### HTML
1416
1417         <img id="myImage" />
1418
1419 ##### JavaScript
1420
1421         $('myImage').setProperty('src', 'mootools.png');
1422
1423 ##### Resulting HTML
1424
1425         <img id="myImage" src="mootools.png" />
1426
1427 ### Note
1428
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'
1433         - etc.
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.
1435
1436 Element Method: setProperties {#Element:setProperties}
1437 ------------------------------------------------------
1438
1439 Sets numerous attributes for the Element.
1440
1441
1442 ### Arguments:
1443
1444 1. properties - (*object*) An object with key/value pairs.
1445
1446 ### Returns:
1447
1448 * (*element*) This Element.
1449
1450 ### Examples:
1451
1452 ##### HTML
1453
1454         <img id="myImage" />
1455
1456 ##### JavaScript
1457
1458         $('myImage').setProperties({
1459                 src: 'whatever.gif',
1460                 alt: 'whatever dude'
1461         });
1462
1463 ##### Resulting HTML
1464
1465         <img id="myImage" src="whatever.gif" alt="whatever dude" />
1466
1467
1468
1469 Element Method: removeProperty {#Element:removeProperty}
1470 --------------------------------------------------------
1471
1472 Removes an attribute from the Element.
1473
1474
1475 ### Syntax:
1476
1477         myElement.removeProperty(property);
1478
1479 ### Arguments:
1480
1481 1. property - (*string*) The attribute to remove.
1482
1483 ### Returns:
1484
1485 * (*element*) This Element.
1486
1487 ### Examples:
1488
1489 ##### HTML
1490
1491         <a id="myAnchor" href="#" onmousedown="alert('click');"></a>
1492
1493 ##### JavaScript
1494
1495         //Eww... inline JavaScript is bad! Let's get rid of it.
1496         $('myAnchor').removeProperty('onmousedown');
1497
1498 ##### Resulting HTML
1499
1500         <a id="myAnchor" href="#"></a>
1501
1502
1503
1504 Element Method: removeProperties {#Element:removeProperties}
1505 ------------------------------------------------------------
1506
1507 Removes numerous attributes from the Element.
1508
1509
1510 ### Syntax:
1511
1512         myElement.removeProperties(properties);
1513
1514 ### Arguments:
1515
1516 1. properties - (*strings*) The attributes to remove, separated by comma.
1517
1518 ### Returns:
1519
1520 * (*element*) This Element.
1521
1522 ### Examples:
1523
1524 ##### HTML
1525
1526         <a id="myAnchor" href="#" title="hello world"></a>
1527
1528 ##### JavaScript
1529
1530         $('myAnchor').removeProperties('id', 'href', 'title');
1531
1532 ##### Resulting HTML
1533
1534         <a></a>
1535
1536
1537 Element Method: store {#Element:store}
1538 --------------------------------------
1539
1540 Stores an item in the Elements Storage, linked to this Element.
1541
1542
1543 ### Syntax:
1544
1545         myElement.store(key, value);
1546
1547 ### Arguments:
1548
1549 1. key - (*string*) The key you want to assign to the stored value.
1550 2. value - (*mixed*) Any value you want to store.
1551
1552 ### Returns:
1553
1554 * (*element*) This Element.
1555
1556 ### Example:
1557
1558         $('element').store('someProperty', someValue);
1559
1560
1561 Element Method: retrieve {#Element:retrieve}
1562 --------------------------------------------
1563
1564 Retrieves a value from the Elements storage.
1565
1566
1567 ### Syntax:
1568
1569         myElement.retrieve(key[, default]);
1570
1571 ### Arguments:
1572
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.
1575
1576 ### Returns:
1577
1578 * (*mixed*) The value linked to the key.
1579
1580 ### Example:
1581
1582         $('element').retrieve('someProperty'); // returns someValue (see example above)
1583
1584
1585 Element Method: eliminate {#Element:eliminate}
1586 --------------------------------------------
1587
1588 Eliminates a key from the Elements storage.
1589
1590
1591 ### Syntax:
1592
1593         myElement.eliminate(key);
1594
1595 ### Arguments:
1596
1597 1. key - (*string*) The key you want to eliminate from the storage.
1598
1599 ### Returns:
1600
1601 * (*mixed*) The element/window/document.
1602
1603 ### Example:
1604
1605         $('element').eliminate('someProperty');
1606
1607
1608
1609
1610
1611 Object: Element.Properties {#Element-Properties}
1612 ==============================================
1613
1614 This Object contains the functions that respond to the first argument passed in [Element:get][], [Element:set][] and [Element:erase][].
1615
1616 ### Adding a Custom Element Property
1617
1618         Element.Properties.disabled = {
1619
1620                 get: function(){
1621                         return this.disabled;
1622                 },
1623
1624                 set: function(value){
1625                         this.disabled = !!value;
1626                         this.setAttribute('disabled', !!value);
1627                 }
1628
1629         };
1630
1631 ### Using a Custom Element Property
1632
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);
1637
1638
1639 ### Using an Object:
1640
1641 Additionally, you can access these custom getters and setters using an object as the parameter for the [set](#Element:set) method.
1642
1643 #### Example:
1644
1645         // using set:
1646         $(divElement).set({html: '<p>Hello <em>People</em>!</p>', style: 'background:red'});
1647
1648         // for new Elements (works the same as set):
1649         new Element('input', {type: 'checkbox', checked: true, disabled: true});
1650
1651
1652 ### Notes:
1653
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
1656
1657
1658
1659 Element Property: html {#Element-Properties:html}
1660 -------------------------------------------------
1661
1662 ### Setter:
1663
1664 Sets the innerHTML of the Element.
1665
1666 #### Syntax:
1667
1668         myElement.set('html', html);
1669
1670 #### Arguments:
1671
1672 1. html - (*string*) The new content as HTML string.
1673
1674 #### Returns:
1675
1676 * (*element*) This Element.
1677
1678 #### Examples:
1679
1680 ##### HTML
1681
1682         <div id="myElement"></div>
1683
1684 ##### JavaScript
1685
1686         $('myElement').set('html', '<div></div><p></p>');
1687
1688 ##### Resulting HTML
1689
1690         <div id="myElement">
1691                 <div></div>
1692                 <p></p>
1693         </div>
1694
1695 ### Getter:
1696
1697 Returns the inner HTML of the Element.
1698
1699 #### Syntax:
1700
1701         myElement.get('html');
1702
1703 #### Returns:
1704
1705 * (*text*) This Element's innerHTML.
1706
1707
1708
1709 Element Property: text {#Element-Properties:text}
1710 -------------------------------------------------
1711
1712 ### Setter:
1713
1714 Sets the inner text of the Element.
1715
1716 #### Syntax:
1717
1718         myElement.set('text', text);
1719
1720 #### Arguments:
1721
1722 1. text - (*string*) The new text content for the Element.
1723
1724 #### Returns:
1725
1726 * (*element*) This Element.
1727
1728 #### Examples:
1729
1730 ##### HTML
1731
1732         <div id="myElement"></div>
1733
1734 ##### JavaScript
1735
1736         $('myElement').set('text', 'some text');
1737         // the text of myElement is now 'some text'.
1738
1739 ##### Resulting HTML
1740
1741         <div id="myElement">some text</div>
1742
1743 ### Getter:
1744
1745 Gets the inner text of the Element.
1746
1747 #### Syntax:
1748
1749         var myText = myElement.get('text');
1750
1751 #### Returns:
1752
1753 * (*string*) The text of the Element.
1754
1755 #### Examples:
1756
1757 ##### HTML
1758
1759         <div id="myElement">my text</div>
1760
1761 ##### JavaScript
1762
1763         var myText = $('myElement').get('text'); // myText = 'my text'.
1764
1765
1766
1767 Element Property: tag {#Element-Properties:tag}
1768 -----------------------------------------------
1769
1770 ### Getter:
1771
1772 Returns the tag name of the Element in lower case.
1773
1774 #### Syntax:
1775
1776         var myTag = myElement.get('tag');
1777
1778 #### Returns:
1779
1780 * (*string*) The tag name in lower case.
1781
1782 #### Examples:
1783
1784 ##### HTML
1785
1786         <img id="myImage" />
1787
1788 ##### JavaScript
1789
1790         var myTag = $('myImage').get('tag'); // myTag = 'img'
1791
1792
1793
1794 Type: IFrame {#IFrame}
1795 ========================
1796
1797 Custom Type to create and easily work with IFrames.
1798
1799
1800
1801 IFrame Method: constructor {#IFrame:constructor}
1802 ------------------------------------------------
1803
1804 Creates an IFrame HTML Element and extends its window and document with MooTools.
1805
1806
1807 ### Syntax:
1808
1809         var myIFrame = new IFrame([el][, props]);
1810
1811 ### Arguments:
1812
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.
1815
1816 ### Returns:
1817
1818 * (*element*) A new IFrame HTML Element.
1819
1820 ### Examples:
1821
1822         var myIFrame = new IFrame({
1823
1824                 src: 'http://mootools.net/',
1825
1826                 styles: {
1827                         width: 800,
1828                         height: 600,
1829                         border: '1px solid #ccc'
1830                 },
1831
1832                 events: {
1833
1834                         mouseenter: function(){
1835                                 alert('Welcome aboard.');
1836                         },
1837
1838                         mouseleave: function(){
1839                                 alert('Goodbye!');
1840                         },
1841
1842                         load: function(){
1843                                 alert('The iframe has finished loading.');
1844                         }
1845
1846                 }
1847
1848         });
1849
1850
1851 ### Notes:
1852
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.
1855
1856
1857
1858 Type: Elements {#Elements}
1859 ============================
1860
1861 The Elements class allows [Element][] methods to work on an [Elements][] array, as well as [Array][] Methods.
1862
1863
1864
1865 Elements Method: constructor {#Elements:constructor}
1866 ----------------------------------------------------
1867
1868
1869 ### Syntax:
1870
1871         var myElements = new Elements(elements[, options]);
1872
1873 ### Arguments:
1874
1875 1. elements - (*mixed*) An array of elements or an HTMLCollection Object.
1876
1877 ### Returns:
1878
1879 * (*array*) An array-like Elements collection with the [Element][], [Elements][] and [Array][] methods.
1880
1881 ### Examples:
1882
1883 #### Set Every Paragraph's Color to Red:
1884
1885         $$('p').each(function(el){
1886                 el.setStyle('color', 'red');
1887         });
1888
1889         // Because $$('myselector') also accepts Element methods, the below
1890         // example has the same effect as the one above.
1891         $$('p').setStyle('color', 'red');
1892
1893
1894 #### Create Elements From an Array:
1895
1896         var myElements = new Elements(['myElementID', $('myElement'), 'myElementID2', document.getElementById('myElementID3')]);
1897
1898
1899 ### Notes:
1900
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.
1904
1905 ### See Also:
1906
1907 - [$$][], [$][], [Element][], [Elements][], [Array][]
1908
1909
1910 Elements Method: append {#Elements:append}
1911 ------------------------------------------
1912
1913 Adds the items of the collection to this [Elements][] array, and return the this array.
1914
1915 ### Syntax:
1916
1917         elements.append(collection);
1918
1919 ### Arguments:
1920
1921 1. collection - (*array*) [Elements][] array or an array of HTML Elements.
1922
1923 ### Returns:
1924
1925 * (*array*) This [Elements][] array.
1926
1927 ### Notes:
1928
1929 - This method doesn't process ([document:id][] or filters) the items of the array.
1930
1931
1932 Elements Method: concat {#Elements:concat}
1933 ------------------------------------------
1934
1935 Adds the element, or array of Elements, to this [Elements][] array, and returns a new [Elements][] array.
1936
1937 ### Syntax:
1938
1939         var newElements = elements.concat(element[, list, id, ...]]);
1940
1941 ### Arguments:
1942
1943 1. element - (*mixed*) An HTML Element, or a string id.
1944 2. list, id, ... - (*mixed*) Additional [Elements][], array of ids, or string ids.
1945
1946 ### Returns:
1947
1948 * (*array*) A new [Elements][] array.
1949
1950
1951 Elements Method: empty {#Elements:empty}
1952 ------------------------------------------
1953
1954 Removes every item from the [Elements][] array, and the empty array.
1955
1956 ### Syntax:
1957
1958         elements.empty();
1959
1960 ### Returns:
1961
1962 * (*array*) This empty [Elements][] array.
1963
1964 ### Note:
1965
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:
1967
1968     $$('div').destroy().empty();
1969
1970 ### See Also
1971
1972  - [Element:destroy][]
1973
1974
1975
1976 Elements Method: filter {#Elements:filter}
1977 ------------------------------------------
1978
1979 Filters a collection of elements by a given css selector, or filtering function like [Array:filter][].
1980
1981
1982 ### Syntax:
1983
1984         var filteredElements = elements.filter(selector);
1985
1986 ### Arguments:
1987
1988 1. selector - (*mixed*) A single CSS selector, or filtering function.
1989
1990 ### Returns:
1991
1992 * (*array*) A subset of this [Elements][] instance.
1993
1994
1995 Elements Method: push {#Elements:push}
1996 --------------------------------------
1997
1998 Adds the element, or elements, to the end of this [Elements][] array and returns the length of the array.
1999
2000
2001 ### Syntax:
2002
2003         var length = elements.push(element[, id, ...]]);
2004
2005 ### Arguments:
2006
2007 1. element - (*mixed*) An HTML Element, or a string id.
2008 2. id, ... - (*mixed*) Additional HTML Element, or string ids.
2009
2010 ### Returns:
2011
2012 * (*number*) The new length of the [Elements][] array.
2013
2014
2015 Elements Method: unshift {#Elements:unshift}
2016 --------------------------------------------
2017
2018 Adds the element, or elements, to the front of this [Elements][] array and returns the length of the array.
2019
2020 ### Syntax:
2021
2022         var length = elements.unshift(element[, id, ...]]);
2023
2024 ### Arguments:
2025
2026 1. element - (*mixed*) An HTML Element, or a string id.
2027 2. id, ... - (*mixed*) Additional HTML Element, or string ids.
2028
2029 ### Returns:
2030
2031 * (*number*) The new length of the [Elements][] array.
2032
2033
2034 Deprecated Functions {#Deprecated-Functions}
2035 ============================================
2036
2037 Element Method: hasChild {#Deprecated-Functions:hasChild}
2038 ---------------------------------------------------------
2039
2040 This method has been deprecated. Use [Element:contains][] instead.
2041
2042 ### Example:
2043
2044         var myElement = document.id('element1');
2045         var myElement2 = document.id('element2');
2046         myElement !== myElement2 && myElement.contains(element2);
2047
2048         // could be implemented as:
2049         Element.implement('hasChild', function(element){
2050                 return this !== element && this.contains(element);
2051         });
2052
2053 Element Method: injectBefore {#Deprecated-Functions:injectBefore}
2054 -----------------------------------------------------------------
2055
2056 This method has been deprecated. Use [Element:inject][] instead.
2057
2058 Element Method: injectAfter {#Deprecated-Functions:injectAfter}
2059 ---------------------------------------------------------------
2060
2061 This method has been deprecated. Use [Element:inject][] instead.
2062
2063 Element Method: injectBottom {#Deprecated-Functions:injectBottom}
2064 -----------------------------------------------------------------
2065
2066 This method has been deprecated. Use [Element:inject][] instead.
2067
2068 Element Method: injectTop {#Deprecated-Functions:injectTop}
2069 -----------------------------------------------------------
2070
2071 This method has been deprecated. Use [Element:inject][] instead.
2072
2073 Element Method: injectInside {#Deprecated-Functions:injectInside}
2074 -----------------------------------------------------------------
2075
2076 This method has been deprecated. Use [Element:inject][] instead.
2077
2078 Element Method: grabBefore {#Deprecated-Functions:grabBefore}
2079 -----------------------------------------------------------------
2080
2081 This method has been deprecated. Use [Element:grab][] instead.
2082
2083 Element Method: grabAfter {#Deprecated-Functions:grabAfter}
2084 ---------------------------------------------------------------
2085
2086 This method has been deprecated. Use [Element:grab][] instead.
2087
2088 Element Method: grabBottom {#Deprecated-Functions:grabBottom}
2089 -----------------------------------------------------------------
2090
2091 This method has been deprecated. Use [Element:grab][] instead.
2092
2093 Element Method: grabTop {#Deprecated-Functions:grabTop}
2094 -----------------------------------------------------------
2095
2096 This method has been deprecated. Use [Element:grab][] instead.
2097
2098 Element Method: grabInside {#Deprecated-Functions:grabInside}
2099 -----------------------------------------------------------------
2100
2101 This method has been deprecated. Use [Element:grab][] instead.
2102
2103
2104 Elements Method: extend {#Deprecated-Functions:extend}
2105 ------------------------------------------------------
2106
2107 This method has been deprecated. Use [Elements:append][] instead.
2108
2109
2110 [document:id]: #Window:document-id
2111 [$]: #Window:dollar
2112 [$$]: #Window:dollars
2113
2114 [Array]: /core/Types/Array
2115 [Array:filter]: /core/Types/Array#Array:filter
2116
2117 [Element]: #Element
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
2135
2136 [Element:addEvents]: /core/Element/Element.Event#Element:addEvents
2137 [Element:setStyles]: /core/Element/Element.Style#Element:setStyles
2138
2139 [The Dollar Safe Mode]: http://mootools.net/blog/2009/06/22/the-dollar-safe-mode/
2140
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