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 decedent 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
 323
 324 ### See Also:
 325
 326 - [Element][], [Element.Properties][], [Element:setProperty][], [Element:addEvents][], [Element:setStyles][]
 327
 328
 329
 330 Element Method: get {#Element:get}
 331 ----------------------------------
 332
 333 This is a "dynamic arguments" method. Properties passed in can be any of the 'get' properties in the [Element.Properties][] Object.
 334
 335 ### Syntax:
 336
 337         myElement.get(property);
 338
 339 ### Arguments:
 340
 341 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to get.
 342
 343 ### Returns:
 344
 345 * (*mixed*) The result of calling the corresponding 'get' function in the [Element.Properties][] Object.
 346
 347 ### Examples:
 348
 349 #### Using Custom Getters:
 350
 351         var tag = $('myDiv').get('tag'); // returns "div".
 352
 353 #### Fallback to Element Attributes:
 354
 355         var id = $('myDiv').get('id'); // returns "myDiv".
 356         var value = $('myInput').get('value'); // returns the myInput element's value.
 357
 358 ### Notes:
 359
 360 -  If the corresponding accessor doesn't exist in the [Element.Properties][] Object, the result of [Element:getProperty][] on the property passed in is returned.
 361
 362 ### See Also:
 363
 364 - [Element][], [Element.Properties][], [Element:getProperty][]
 365
 366
 367
 368 Element Method: erase {#Element:erase}
 369 --------------------------------------
 370
 371 This is a "dynamic arguments" method. Properties passed in can be any of the 'erase' properties in the [Element.Properties][] Object.
 372
 373 ### Syntax:
 374
 375         myElement.erase(property);
 376
 377 ### Arguments:
 378
 379 1. property - (*string*) The string key from the [Element.Properties][] Object representing the property to erase.
 380
 381 ### Returns:
 382
 383 * (*mixed*) The result of calling the corresponding 'erase' function in the [Element.Properties][] Object.
 384
 385 ### Examples:
 386
 387         $('myDiv').erase('id'); //Removes the id from myDiv.
 388         $('myDiv').erase('class'); //myDiv element no longer has any class names set.
 389
 390 ### Note:
 391
 392 -  If the corresponding eraser doesn't exist in the  [Element.Properties][] Object, [Element:removeProperty][] is called with the property passed in.
 393
 394 ### See Also:
 395
 396 - [Element][], [Element.Properties][], [Element:removeProperty][]
 397
 398
 399
 400 Element Method: match {#Element:match}
 401 --------------------------------------
 402
 403 Tests this Element to see if it matches the argument passed in.
 404
 405 ### Syntax:
 406
 407         myElement.match(match);
 408
 409 ### Arguments:
 410
 411 1. match - can be a string or element
 412         - (*string*) The tag name to test against this element. Any single CSS selectors may also be passed.
 413         - (*element*) An element to match; returns true if this is the actual element passed in.
 414
 415 ### Returns:
 416
 417 * (*boolean*) If the element matched, returns true. Otherwise, returns false.
 418
 419 ### Examples:
 420
 421 #### Using a Tag Name:
 422
 423         // returns true if #myDiv is a div.
 424         $('myDiv').match('div');
 425
 426 #### Using a CSS Selector:
 427
 428         // returns true if #myDiv has the class foo and is named "bar"
 429         $('myDiv').match('.foo[name=bar]');
 430
 431 #### Using an Element:
 432
 433         var el = $('myDiv');
 434         $('myDiv').match(el); // returns true
 435         $('otherElement').match(el); // returns false
 436
 437
 438
 439 Element Method: contains {#Element:contains}
 440 --------------------------------------------
 441
 442 Checks all descendants of this Element for a match.
 443
 444
 445 ### Syntax:
 446
 447         var result = myElement.contains(el);
 448
 449 ### Arguments:
 450
 451 1. el - (*mixed*) Can be an Element reference or string id.
 452
 453 ### Returns:
 454
 455 * (*boolean*) Returns true if the element contains passed in Element is a child, otherwise false.
 456
 457 ### Examples:
 458
 459 ##### HTML
 460
 461         <div id="Darth_Vader">
 462                 <div id="Luke"></div>
 463         </div>
 464
 465 ##### JavaScript
 466
 467         if ($('Darth_Vader').contains('Luke')) alert('Luke, I am your father.'); //tan tan tannn...
 468
 469
 470
 471 Element Method: inject {#Element:inject}
 472 ----------------------------------------
 473
 474 Injects, or inserts, the Element at a particular place relative to the Element's children (specified by the second the argument).
 475
 476 ### Syntax:
 477
 478         myElement.inject(el[, where]);
 479
 480 ### Arguments:
 481
 482 1. el   - (*mixed*) el can be the id of an element or an element.
 483 2. where - (*string*, optional: defaults to 'bottom') The place to inject this Element.  Can be 'top', 'bottom', 'after', or 'before'.
 484
 485 ### Returns:
 486
 487 * (*element*) This Element.
 488
 489 ### Examples:
 490
 491 ##### JavaScript
 492
 493         var myFirstElement  = new Element('div', {id: 'myFirstElement'});
 494         var mySecondElement = new Element('div', {id: 'mySecondElement'});
 495         var myThirdElement  = new Element('div', {id: 'myThirdElement'});
 496
 497 ##### Resulting HTML
 498
 499         <div id="myFirstElement"></div>
 500         <div id="mySecondElement"></div>
 501         <div id="myThirdElement"></div>
 502
 503 #### Inject to the bottom:
 504
 505 ##### JavaScript
 506
 507         myFirstElement.inject(mySecondElement);
 508
 509 ##### Resulting HTML
 510
 511         <div id="mySecondElement">
 512                 <div id="myFirstElement"></div>
 513         </div>
 514
 515 #### Inject to the top:
 516
 517 ##### JavaScript
 518
 519         myThirdElement.inject(mySecondElement, 'top');
 520
 521 ##### Resulting HTML
 522
 523         <div id="mySecondElement">
 524                 <div id="myThirdElement"></div>
 525                 <div id="myFirstElement"></div>
 526         </div>
 527
 528 #### Inject before:
 529
 530 ##### JavaScript
 531
 532         myFirstElement.inject(mySecondElement, 'before');
 533
 534 ##### Resulting HTML
 535
 536         <div id="myFirstElement"></div>
 537         <div id="mySecondElement"></div>
 538
 539 #### Inject After:
 540
 541 ##### JavaScript
 542
 543         myFirstElement.inject(mySecondElement, 'after');
 544
 545 ##### Resulting HTML
 546
 547         <div id="mySecondElement"></div>
 548         <div id="myFirstElement"></div>
 549
 550 ### See Also:
 551
 552 [Element:adopt](#Element:adopt), [Element:grab](#Element:grab), [Element:wraps](#Element:wraps)
 553
 554
 555
 556 Element Method: grab {#Element:grab}
 557 ------------------------------------
 558
 559 Works as [Element:inject](#Element:inject), but in reverse.
 560
 561 Appends the Element at a particular place relative to the Element's children (specified by the where parameter).
 562
 563 ### Syntax:
 564
 565         myElement.grab(el[, where]);
 566
 567 ### Arguments:
 568
 569 1. el - (*mixed*) el can be the id of an element or an Element.
 570 2. where - (*string*, optional: default 'bottom') The place to append this Element. Can be 'top', 'bottom', 'before' or 'after'.
 571
 572 ### Returns:
 573
 574 * (*element*) This Element.
 575
 576 ### Examples:
 577
 578 ##### HTML
 579
 580         <div id="first">
 581                 <div id="child"></div>
 582         </div>
 583
 584 ##### JavaScript
 585
 586         var mySecondElement = new Element('div#second');
 587         $('first').grab(mySecondElement);
 588
 589 ##### Resulting HTML
 590
 591         <div id="first">
 592                 <div id="child"></div>
 593                 <div id="second"></div>
 594         </div>
 595
 596 ##### JavaScript
 597
 598         var mySecondElement = new Element('div#second');
 599         myFirstElement.grab(mySecondElement, 'top');
 600
 601 ##### Resulting HTML
 602
 603         <div id="first">
 604                 <div id="second"></div>
 605                 <div id="child"></div>
 606         </div>
 607
 608 ### See Also:
 609
 610 [Element:adopt](#Element:adopt), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
 611
 612
 613
 614 Element Method: adopt {#Element:adopt}
 615 --------------------------------------
 616
 617 Works like [Element:grab](#Element:grab), but allows multiple elements to be adopted and only appended at the bottom.
 618
 619 Inserts the passed element(s) inside the Element (which will then become the parent element).
 620
 621 ### Syntax:
 622
 623         myParent.adopt(el[, others]);
 624
 625 ### Arguments:
 626
 627 1. el - (*mixed*) The id of an element, an Element, or an array of elements.
 628 2. others - (*mixed*, optional) One or more additional Elements separated by a comma or as an array.
 629
 630 ### Returns:
 631
 632 * (*element*) This Element.
 633
 634 ### Examples:
 635
 636 ##### JavaScript
 637
 638         var myFirstElement  = new Element('div#first');
 639         var mySecondElement = new Element('p#second');
 640         var myThirdElement  = new Element('ul#third');
 641         var myFourthElement = new Element('a#fourth');
 642
 643         var myParentElement = new Element('div#parent');
 644
 645         myFirstElement.adopt(mySecondElement);
 646         mySecondElement.adopt('third', myFourthElement);
 647
 648         myParent3.adopt([myFirstElement, new Element('span#another')]);
 649
 650 ##### Resulting HTML
 651
 652         <div id="parent">
 653                 <p id="second">
 654                         <ul id="third"></ul>
 655                         <a id="fourth"></a>
 656                 </p>
 657                 <span id="another"></span>
 658         </div>
 659
 660 ### See Also:
 661
 662 [Element:grab](#Element:grab), [Element:inject](#Element:inject), [Element:wraps](#Element:wraps)
 663
 664
 665
 666 Element Method: wraps {#Element:wraps}
 667 --------------------------------------
 668
 669 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.
 670
 671 ### Syntax:
 672
 673         myParent.wraps(el[, where]);
 674
 675 ### Arguments:
 676
 677 1. el - (*mixed*) The id of an element or an Element.
 678 2. where - (*string*, optional: default 'bottom') The place to insert the passed in element. Can be 'top' or 'bottom'.
 679
 680 ### Returns:
 681
 682 * (*element*) This Element.
 683
 684 ### Examples:
 685
 686 ##### HTML
 687
 688         <div id="first"></div>
 689
 690 ##### JavaScript
 691
 692         var mySecondElement = new Element('div#second').wraps('first');
 693
 694 ##### Resulting HTML
 695
 696         <div id="second">
 697                 <div id="first"></div>
 698         </div>
 699
 700 ##### HTML
 701
 702         <div id="first"></div>
 703         <div id="second">
 704                 <div id="child"></div>
 705         </div>
 706
 707 ##### JavaScript
 708
 709         $('second').wraps('first');
 710
 711 ##### Resulting HTML
 712
 713         <div id="second">
 714                 <div id="child"></div>
 715                 <div id="first"></div>
 716         </div>
 717
 718 ##### JavaScript
 719
 720         $('second').wraps('first', 'top');
 721
 722 ##### Resulting HTML
 723
 724         <div id="second">
 725                 <div id="first"></div>
 726                 <div id="child"></div>
 727         </div>
 728
 729 Element Method: appendText {#Element:appendText}
 730 ------------------------------------------------
 731
 732 Works like [Element:grab](#Element:grab), but instead of accepting an id or an element, it only accepts text.
 733 A text node will be created inside this Element, in either the top or bottom position.
 734
 735 ### Syntax:
 736
 737         myElement.appendText(text[, where]);
 738
 739 ### Arguments:
 740
 741 1. text  - (*string*) The text to append.
 742 1. where - (*string*, optional: default 'bottom') The position to inject the text to. Values accepted are 'top', 'bottom', 'before' and 'after'.
 743
 744 ### Returns:
 745
 746 * (*element*) The current Element instance.
 747
 748 ### Examples:
 749
 750 ##### HTML
 751
 752         <div id="myElement">Hey.</div>
 753
 754 ##### JavaScript
 755
 756         $('myElement').appendText(' Howdy.');
 757
 758 ##### Resulting HTML
 759
 760         <div id="myElement">Hey. Howdy.</div>
 761
 762
 763
 764 Element Method: dispose {#Element:dispose}
 765 ------------------------------------------
 766
 767 Removes the Element from the DOM.
 768
 769
 770 ### Syntax:
 771
 772         var removedElement = myElement.dispose();
 773
 774 ### Returns:
 775
 776 * (*element*) This Element. Useful to always grab the return from this function, as the element could be [injected](#Element:inject) back.
 777
 778 ### Examples:
 779
 780 ##### HTML
 781
 782         <div id="myElement"></div>
 783         <div id="mySecondElement"></div>
 784
 785 ##### JavaScript
 786
 787         $('myElement').dispose();
 788
 789 ##### Resulting HTML
 790
 791         <div id="mySecondElement"></div>
 792
 793 ### See Also:
 794
 795 - [MDC Element:removeChild][]
 796
 797
 798
 799 Element Method: clone {#Element:clone}
 800 --------------------------------------
 801
 802 Clones the Element and returns the cloned one.
 803
 804
 805 ### Syntax:
 806
 807         var copy = myElement.clone([contents, keepid]);
 808
 809 ### Arguments:
 810
 811 1. contents - (*boolean*, optional: defaults to true) When set to false the Element's contents are not cloned.
 812 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.
 813
 814
 815 ### Returns:
 816
 817 * (*element*) The cloned Element.
 818
 819 ### Examples:
 820
 821 ##### HTML
 822
 823         <div id="myElement">ciao</div>
 824
 825 ##### JavaScript
 826
 827         // clones the Element and appends the clone after the Element.
 828         var clone = $('myElement').clone().inject('myElement','after');
 829
 830 ##### Resulting HTML
 831
 832         <div id="myElement">ciao</div>
 833         <div>ciao</div>
 834
 835 ### Note:
 836
 837 - The returned Element does not have attached events. To clone the events use [Element:cloneEvents](/Element/Element.Event#Element:cloneEvents).
 838 - Values stored in Element.Storage are not cloned.
 839 - The clone element and its children are stripped of ids, unless otherwise specified by the keepid parameter.
 840
 841 ### See Also:
 842
 843 - [Element:cloneEvents](/Element/Element.Event#Element:cloneEvents).
 844
 845
 846
 847 Element Method: replaces {#Element:replaces}
 848 --------------------------------------------------
 849
 850 Replaces the passed Element with Element.
 851
 852 ### Syntax:
 853
 854         var element = myElement.replaces(el);
 855
 856 ### Arguments:
 857
 858 1. el - (*mixed*) A string id representing the Element to be replaced, or an Element reference.
 859
 860 ### Returns:
 861
 862 * (*element*) This Element.
 863
 864 ### Examples:
 865
 866         $('myNewElement').replaces($('myOldElement'));
 867         //$('myOldElement') is gone, and $('myNewElement') is in its place.
 868
 869 ### See Also:
 870
 871 - [MDC Element:replaceChild][]
 872
 873
 874
 875 Element Method: hasClass {#Element:hasClass}
 876 --------------------------------------------
 877
 878 Tests the Element to see if it has the passed in className.
 879
 880 ### Syntax:
 881
 882         var result = myElement.hasClass(className);
 883
 884 ### Arguments:
 885
 886 1. className - (*string*) The class name to test.
 887
 888 ### Returns:
 889
 890 * (*boolean*) Returns true if the Element has the class, otherwise false.
 891
 892 ### Examples:
 893
 894 ##### HTML
 895
 896         <div id="myElement" class="testClass"></div>
 897
 898 ##### JavaScript
 899
 900         $('myElement').hasClass('testClass'); // returns true
 901
 902
 903
 904 Element Method: addClass {#Element:addClass}
 905 --------------------------------------------
 906
 907 Adds the passed in class to the Element, if the Element doesnt already have it.
 908
 909 ### Syntax:
 910
 911         myElement.addClass(className);
 912
 913 ### Arguments:
 914
 915 1. className - (*string*) The class name to add.
 916
 917 ### Returns:
 918
 919 * (*element*) This Element.
 920
 921 ### Examples:
 922
 923 ##### HTML
 924
 925         <div id="myElement" class="testClass"></div>
 926
 927 ##### JavaScript
 928
 929         $('myElement').addClass('newClass');
 930
 931 ##### Resulting HTML
 932
 933         <div id="myElement" class="testClass newClass"></div>
 934
 935
 936
 937 Element Method: removeClass {#Element:removeClass}
 938 ----------------------------
 939
 940 Works like [Element:addClass](#Element:addClass), but removes the class from the Element.
 941
 942
 943 ### Syntax:
 944
 945         myElement.removeClass(className);
 946
 947 ### Arguments:
 948
 949 1. className - (*string*) The class name to remove.
 950
 951 ### Returns:
 952
 953 * (*element*) This Element.
 954
 955 ### Examples:
 956
 957 ##### HTML
 958
 959         <div id="myElement" class="testClass newClass"></div>
 960
 961 ##### JavaScript
 962
 963         $('myElement').removeClass('newClass');
 964
 965 ##### Resulting HTML
 966
 967         <div id="myElement" class="testClass"></div>
 968
 969
 970
 971 Element Method: toggleClass {#Element:toggleClass}
 972 --------------------------------------------------
 973
 974 Adds or removes the passed in class name to the Element, depending on whether or not it's already present.
 975
 976 ### Syntax:
 977
 978         myElement.toggleClass(className, force);
 979
 980 ### Arguments:
 981
 982 1. className - (*string*) The class to add or remove.
 983 2. force - (*boolean*, optional) Force the class to be either added or removed
 984
 985 ### Returns:
 986
 987 * (*element*) This Element.
 988
 989 ### Examples:
 990
 991 ##### HTML
 992
 993         <div id="myElement" class="myClass"></div>
 994
 995 ##### JavaScript
 996
 997         $('myElement').toggleClass('myClass');
 998
 999 ##### Resulting HTML
1000
1001         <div id="myElement" class=""></div>
1002
1003 ##### JavaScript
1004
1005         $('myElement').toggleClass('myClass');
1006
1007 ##### Resulting HTML
1008
1009         <div id="myElement" class="myClass"></div>
1010
1011
1012
1013 Element Method: getPrevious {#Element:getPrevious}
1014 --------------------------------------------------
1015
1016 Returns the previousSibling of the Element (excluding text nodes).
1017
1018 ### Syntax:
1019
1020         var previousSibling = myElement.getPrevious([match]);
1021
1022 ### Arguments:
1023
1024 1. match - (*string*, optional): A tag name to match the the found element(s) with. A full CSS selector can be passed.
1025
1026 ### Returns:
1027
1028 * (*mixed*) The previous sibling Element or null if none found.
1029
1030
1031
1032 Element Method: getAllPrevious {#Element:getAllPrevious}
1033 --------------------------------------------------------
1034
1035 Like [Element:getPrevious][], but returns a collection of all the matched previousSiblings.
1036
1037
1038
1039 Element Method: getNext {#Element:getNext}
1040 ------------------------------------------
1041
1042 As [Element:getPrevious][], but tries to find the nextSibling (excluding text nodes).
1043
1044
1045 ### Syntax:
1046
1047         var nextSibling = myElement.getNext([match]);
1048
1049 ### Arguments:
1050
1051 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.
1052
1053 ### Returns:
1054
1055 * (*mixed*) The next sibling Element or null if none found.
1056
1057
1058 Element Method: getAllNext {#Element:getAllNext}
1059 ------------------------------------------------
1060
1061 Like Element.getNext, but returns a collection of all the matched nextSiblings.
1062
1063
1064
1065 Element Method: getFirst {#Element:getFirst}
1066 --------------------------------------------
1067
1068 Gets the first element that matches the passed in expression.
1069
1070
1071 ### Syntax:
1072
1073         var firstElement = myElement.getFirst([match]);
1074
1075 ### Arguments:
1076
1077 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1078
1079 ### Returns:
1080
1081 * (*mixed*) The first found element or null if none found.
1082
1083
1084
1085 Element Method: getLast {#Element:getLast}
1086 ------------------------------------------
1087
1088 Gets the last element that matches the passed in expression.
1089
1090 ### Syntax:
1091
1092         var lastElement = myElement.getLast([match]);
1093
1094 ### Arguments:
1095
1096 1. match - (*string*, optional): A full CSS selector to match the found element(s) with.
1097
1098 ### Returns:
1099
1100 * (*mixed*) The last found element, or returns null if none found.
1101
1102
1103
1104 Element Method: getParent {#Element:getParent}
1105 ----------------------------------------------
1106
1107 Works as [Element:getPrevious][], but tries to find the parentNode.
1108
1109
1110 ### Syntax:
1111
1112         var parent = myElement.getParent([match]);
1113
1114 ### Arguments:
1115
1116 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1117
1118 ### Returns:
1119
1120 * (*mixed*) The target Element's parent or null if no matching parent is found.
1121
1122
1123
1124 Element Method: getParents {#Element:getParents}
1125 ------------------------------------------------
1126
1127 Like [Element:getParent](#Element:getParent), but returns a collection of all the matched parentNodes up the tree.
1128
1129
1130
1131 Element Method: getSiblings {#Element:getSiblings}
1132 --------------------------------------------------
1133
1134 Like [Element:getAllPrevious][] but returns all Element's previous and next siblings (excluding text nodes). Returns as [Elements][].
1135
1136
1137 ### Syntax:
1138
1139         var siblings = myElement.getSiblings([match]);
1140
1141 ### Arguments:
1142
1143 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1144
1145 ### Returns:
1146
1147 * (*array*) A [Elements](#Elements) array with all of the Element's siblings, except the text nodes.
1148
1149
1150
1151 Element Method: getChildren {#Element:getChildren}
1152 --------------------------------------------------
1153
1154 Returns all the Element's children (excluding text nodes). Returns as [Elements][].
1155
1156
1157 ### Syntax:
1158
1159         var children = myElement.getChildren([match]);
1160
1161 ### Arguments:
1162
1163 1. match - (*string*, optional): A tag name to match the found element(s) with. A full CSS selector can be passed.
1164
1165 ### Returns:
1166
1167 * (*array*) A [Elements](#Elements) array with all of the Element's children, except the text nodes.
1168
1169 ### Note:
1170
1171 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.
1172
1173 Element Method: empty {#Element:empty}
1174 --------------------------------------
1175
1176 Empties an Element of all its children.
1177
1178
1179 ### Syntax:
1180
1181         myElement.empty();
1182
1183 ### Returns:
1184
1185 * (*element*) This Element.
1186
1187 ### Examples:
1188
1189 ##### HTML
1190
1191         <div id="myElement">
1192                 <p></p>
1193                 <span></span>
1194         </div>
1195
1196 ##### JavaScript
1197
1198         $('myElement').empty();
1199
1200 ##### Resulting HTML
1201
1202         <div id="myElement"></div>
1203
1204
1205
1206 Element Method: destroy {#Element:destroy}
1207 ------------------------------------------
1208
1209 Removes the Element and its children from the DOM and prepares them for garbage collection.
1210
1211 ### Syntax:
1212
1213         myElement.destroy();
1214
1215 ### Returns:
1216
1217 * (*null*)
1218
1219
1220
1221 Element Method: toQueryString {#Element:toQueryString}
1222 ------------------------------------------------------
1223
1224 Reads the child inputs of the Element and generates a query string based on their values.
1225
1226
1227 ### Syntax:
1228
1229         var query = myElement.toQueryString();
1230
1231 ### Returns:
1232
1233 * (*string*) A string representation of a all the input Elements' names and values.
1234
1235 ### Examples:
1236
1237 ##### HTML
1238
1239         <form id="myForm" action="submit.php">
1240                 <input name="email" value="bob@bob.com" />
1241                 <input name="zipCode" value="90210" />
1242         </form>
1243
1244 ##### JavaScript
1245
1246         $('myForm').toQueryString(); // returns "email=bob@bob.com&zipCode=90210".
1247
1248
1249 Element Method: getSelected {#Element:getSelected}
1250 --------------------------------------------------
1251
1252 Returns the selected options of a select element.
1253
1254
1255 ### Syntax:
1256
1257         var selected = mySelect.getSelected();
1258
1259 ### Returns:
1260
1261 * (*array*) An array of the selected elements.
1262
1263 ### Examples:
1264
1265 ##### HTML
1266
1267         <select id="country-select" name="country">
1268                 <option value="US">United States</option
1269                 <option value ="IT">Italy</option>
1270         </select>
1271
1272 ##### JavaScript
1273
1274         $('country-select').getSelected(); // returns whatever the user selected.
1275
1276 ### Note:
1277
1278 This method returns an array, regardless of the multiple attribute of the select element.
1279 If the select is single, it will return an array with only one item.
1280
1281
1282
1283 Element Method: getProperty {#Element:getProperty}
1284 --------------------------------------------------
1285
1286 Returns a single element attribute.
1287
1288 ### Syntax:
1289
1290         var myProp = myElement.getProperty(property);
1291
1292 ### Arguments:
1293
1294 * property - (*string*) The property to be retrieved.
1295
1296 ### Returns:
1297
1298 * (*string*) A string containing the Element's requested property.
1299
1300 ### Examples:
1301
1302 ##### HTML
1303
1304         <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1305
1306 ##### JavaScript
1307
1308         var imgProps = $('myImage').getProperty('src'); // returns: 'mootools.png'.
1309
1310
1311
1312 Element Method: getProperties {#Element:getProperties}
1313 ------------------------------------------------------
1314
1315 Gets multiple element attributes.
1316
1317 ### Syntax:
1318
1319         var myProps = myElement.getProperties(properties);
1320
1321 ### Arguments:
1322
1323 * properties - (*strings*) Any number of properties to be retrieved.
1324
1325 ### Returns:
1326
1327 * (*object*) An object containing all of the Element's requested properties.
1328
1329 ### Examples:
1330
1331 ##### HTML
1332
1333         <img id="myImage" src="mootools.png" title="MooTools, the compact JavaScript framework" alt="" />
1334
1335 ##### JavaScript
1336
1337         var imgProps = $('myImage').getProperties('id', 'src', 'title', 'alt');
1338         // returns: { id: 'myImage', src: 'mootools.png', title: 'MooTools, the compact JavaScript framework', alt: '' }
1339
1340
1341
1342 Element Method: setProperty {#Element:setProperty}
1343 --------------------------------------------------
1344
1345 Sets an attribute or special property for this Element.
1346
1347
1348 ### Arguments:
1349
1350 1. property - (*string*) The property to assign the value passed in.
1351 2. value - (*mixed*) The value to assign to the property passed in.
1352
1353 ### Returns:
1354
1355 * (*element*) - This Element.
1356
1357 ### Examples:
1358
1359 ##### HTML
1360
1361         <img id="myImage" />
1362
1363 ##### JavaScript
1364
1365         $('myImage').setProperty('src', 'mootools.png');
1366
1367 ##### Resulting HTML
1368
1369         <img id="myImage" src="mootools.png" />
1370
1371 ### Note
1372
1373 - Whenever using [Element:setProperty][] to set an attribute, pass in the lowercase, simplified form of the property. For example:
1374         - use 'for', not 'htmlFor',
1375         - use 'class', not 'className'
1376         - use 'frameborder', not 'frameBorder'
1377         - etc.
1378
1379
1380 Element Method: setProperties {#Element:setProperties}
1381 ------------------------------------------------------
1382
1383 Sets numerous attributes for the Element.
1384
1385
1386 ### Arguments:
1387
1388 1. properties - (*object*) An object with key/value pairs.
1389
1390 ### Returns:
1391
1392 * (*element*) This Element.
1393
1394 ### Examples:
1395
1396 ##### HTML
1397
1398         <img id="myImage" />
1399
1400 ##### JavaScript
1401
1402         $('myImage').setProperties({
1403                 src: 'whatever.gif',
1404                 alt: 'whatever dude'
1405         });
1406
1407 ##### Resulting HTML
1408
1409         <img id="myImage" src="whatever.gif" alt="whatever dude" />
1410
1411
1412
1413 Element Method: removeProperty {#Element:removeProperty}
1414 --------------------------------------------------------
1415
1416 Removes an attribute from the Element.
1417
1418
1419 ### Syntax:
1420
1421         myElement.removeProperty(property);
1422
1423 ### Arguments:
1424
1425 1. property - (*string*) The attribute to remove.
1426
1427 ### Returns:
1428
1429 * (*element*) This Element.
1430
1431 ### Examples:
1432
1433 ##### HTML
1434
1435         <a id="myAnchor" href="#" onmousedown="alert('click');"></a>
1436
1437 ##### JavaScript
1438
1439         //Eww... inline JavaScript is bad! Let's get rid of it.
1440         $('myAnchor').removeProperty('onmousedown');
1441
1442 ##### Resulting HTML
1443
1444         <a id="myAnchor" href="#"></a>
1445
1446
1447
1448 Element Method: removeProperties {#Element:removeProperties}
1449 ------------------------------------------------------------
1450
1451 Removes numerous attributes from the Element.
1452
1453
1454 ### Syntax:
1455
1456         myElement.removeProperties(properties);
1457
1458 ### Arguments:
1459
1460 1. properties - (*strings*) The attributes to remove, separated by comma.
1461
1462 ### Returns:
1463
1464 * (*element*) This Element.
1465
1466 ### Examples:
1467
1468 ##### HTML
1469
1470         <a id="myAnchor" href="#" title="hello world"></a>
1471
1472 ##### JavaScript
1473
1474         $('myAnchor').removeProperties('id', 'href', 'title');
1475
1476 ##### Resulting HTML
1477
1478         <a></a>
1479
1480
1481 Element Method: store {#Element:store}
1482 --------------------------------------
1483
1484 Stores an item in the Elements Storage, linked to this Element.
1485
1486
1487 ### Syntax:
1488
1489         myElement.store(key, value);
1490
1491 ### Arguments:
1492
1493 1. key - (*string*) The key you want to assign to the stored value.
1494 2. value - (*mixed*) Any value you want to store.
1495
1496 ### Returns:
1497
1498 * (*element*) This Element.
1499
1500 ### Example:
1501
1502         $('element').store('someProperty', someValue);
1503
1504
1505 Element Method: retrieve {#Element:retrieve}
1506 --------------------------------------------
1507
1508 Retrieves a value from the Elements storage.
1509
1510
1511 ### Syntax:
1512
1513         myElement.retrieve(key[, default]);
1514
1515 ### Arguments:
1516
1517 1. key - (*string*) The key you want to retrieve from the storage.
1518 2. default - (*mixed*, optional) Default value to store and return if no value is stored.
1519
1520 ### Returns:
1521
1522 * (*mixed*) The value linked to the key.
1523
1524 ### Example:
1525
1526         $('element').retrieve('someProperty'); // returns someValue (see example above)
1527
1528
1529 Element Method: eliminate {#Element:eliminate}
1530 --------------------------------------------
1531
1532 Eliminates a key from the Elements storage.
1533
1534
1535 ### Syntax:
1536
1537         myElement.eliminate(key);
1538
1539 ### Arguments:
1540
1541 1. key - (*string*) The key you want to eliminate from the storage.
1542
1543 ### Returns:
1544
1545 * (*mixed*) The element/window/document.
1546
1547 ### Example:
1548
1549         $('element').eliminate('someProperty');
1550
1551
1552
1553
1554
1555 Object: Element.Properties {#Element-Properties}
1556 ==============================================
1557
1558 This Object contains the functions that respond to the first argument passed in [Element:get][], [Element:set][] and [Element:erase][].
1559
1560 ### Adding a Custom Element Property
1561
1562         Element.Properties.disabled = {
1563
1564                 get: function(){
1565                         return this.disabled;
1566                 },
1567
1568                 set: function(value){
1569                         this.disabled = !!value;
1570                         this.setAttribute('disabled', !!value);
1571                 }
1572
1573         };
1574
1575 ### Using a Custom Element Property
1576
1577         // gets the "disabled" property
1578         $(element).get('disabled');
1579         // sets the "disabled" property to true, along with the attribute
1580         $(element).set('disabled', true);
1581
1582
1583 ### Using an Object:
1584
1585 Additionally, you can access these custom getters and setters using an object as the parameter for the [set](#Element:set) method.
1586
1587 #### Example:
1588
1589         // using set:
1590         $(divElement).set({html: '<p>Hello <em>People</em>!</p>', style: 'background:red'});
1591
1592         // for new Elements (works the same as set):
1593         new Element('input', {type: 'checkbox', checked: true, disabled: true});
1594
1595
1596 ### Notes:
1597
1598 - Automatically returns the element for setters.
1599 - Since MooTools 1.3 this is a native JavaScript Object and not an instance of the deprecated Hash
1600
1601
1602
1603 Element Property: html {#Element-Properties:html}
1604 -------------------------------------------------
1605
1606 ### Setter:
1607
1608 Sets the innerHTML of the Element.
1609
1610 #### Syntax:
1611
1612         myElement.set('html', html);
1613
1614 #### Arguments:
1615
1616 1. html - (*string*) The new content as HTML string.
1617
1618 #### Returns:
1619
1620 * (*element*) This Element.
1621
1622 #### Examples:
1623
1624 ##### HTML
1625
1626         <div id="myElement"></div>
1627
1628 ##### JavaScript
1629
1630         $('myElement').set('html', '<div></div><p></p>');
1631
1632 ##### Resulting HTML
1633
1634         <div id="myElement">
1635                 <div></div>
1636                 <p></p>
1637         </div>
1638
1639 ### Getter:
1640
1641 Returns the inner HTML of the Element.
1642
1643 #### Syntax:
1644
1645         myElement.get('html');
1646
1647 #### Returns:
1648
1649 * (*text*) This Element's innerHTML.
1650
1651
1652
1653 Element Property: text {#Element-Properties:text}
1654 -------------------------------------------------
1655
1656 ### Setter:
1657
1658 Sets the inner text of the Element.
1659
1660 #### Syntax:
1661
1662         myElement.set('text', text);
1663
1664 #### Arguments:
1665
1666 1. text - (*string*) The new text content for the Element.
1667
1668 #### Returns:
1669
1670 * (*element*) This Element.
1671
1672 #### Examples:
1673
1674 ##### HTML
1675
1676         <div id="myElement"></div>
1677
1678 ##### JavaScript
1679
1680         $('myElement').set('text', 'some text');
1681         // the text of myElement is now 'some text'.
1682
1683 ##### Resulting HTML
1684
1685         <div id="myElement">some text</div>
1686
1687 ### Getter:
1688
1689 Gets the inner text of the Element.
1690
1691 #### Syntax:
1692
1693         var myText = myElement.get('text');
1694
1695 #### Returns:
1696
1697 * (*string*) The text of the Element.
1698
1699 #### Examples:
1700
1701 ##### HTML
1702
1703         <div id="myElement">my text</div>
1704
1705 ##### JavaScript
1706
1707         var myText = $('myElement').get('text'); // myText = 'my text'.
1708
1709
1710
1711 Element Property: tag {#Element-Properties:tag}
1712 -----------------------------------------------
1713
1714 ### Getter:
1715
1716 Returns the tag name of the Element in lower case.
1717
1718 #### Syntax:
1719
1720         var myTag = myElement.get('tag');
1721
1722 #### Returns:
1723
1724 * (*string*) The tag name in lower case.
1725
1726 #### Examples:
1727
1728 ##### HTML
1729
1730         <img id="myImage" />
1731
1732 ##### JavaScript
1733
1734         var myTag = $('myImage').get('tag'); // myTag = 'img'
1735
1736
1737
1738 Type: IFrame {#IFrame}
1739 ========================
1740
1741 Custom Type to create and easily work with IFrames.
1742
1743
1744
1745 IFrame Method: constructor {#IFrame:constructor}
1746 ------------------------------------------------
1747
1748 Creates an IFrame HTML Element and extends its window and document with MooTools.
1749
1750
1751 ### Syntax:
1752
1753         var myIFrame = new IFrame([el][, props]);
1754
1755 ### Arguments:
1756
1757 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).
1758 2. props - (*object*, optional) The properties to be applied to the new IFrame. Same as [Element:constructor](#Element:constructor) props argument.
1759
1760 ### Returns:
1761
1762 * (*element*) A new IFrame HTML Element.
1763
1764 ### Examples:
1765
1766         var myIFrame = new IFrame({
1767
1768                 src: 'http://mootools.net/',
1769
1770                 styles: {
1771                         width: 800,
1772                         height: 600,
1773                         border: '1px solid #ccc'
1774                 },
1775
1776                 events: {
1777
1778                         mouseenter: function(){
1779                                 alert('Welcome aboard.');
1780                         },
1781
1782                         mouseleave: function(){
1783                                 alert('Goodbye!');
1784                         },
1785
1786                         load: function(){
1787                                 alert('The iframe has finished loading.');
1788                         }
1789
1790                 }
1791
1792         });
1793
1794
1795 ### Notes:
1796
1797 - If the IFrame already exists and has a different name than id, the name will be made the same as the id.
1798 - An IFrame's window and document will not be extended with MooTools methods.
1799
1800
1801
1802 Type: Elements {#Elements}
1803 ============================
1804
1805 The Elements class allows [Element][] methods to work on an [Elements][] array, as well as [Array][] Methods.
1806
1807
1808
1809 Elements Method: constructor {#Elements:constructor}
1810 ----------------------------------------------------
1811
1812
1813 ### Syntax:
1814
1815         var myElements = new Elements(elements[, options]);
1816
1817 ### Arguments:
1818
1819 1. elements - (*mixed*) An array of elements or an HTMLCollection Object.
1820
1821 ### Returns:
1822
1823 * (*array*) An array-like Elements collection with the [Element][], [Elements][] and [Array][] methods.
1824
1825 ### Examples:
1826
1827 #### Set Every Paragraph's Color to Red:
1828
1829         $$('p').each(function(el){
1830                 el.setStyle('color', 'red');
1831         });
1832
1833         // Because $$('myselector') also accepts Element methods, the below
1834         // example has the same effect as the one above.
1835         $$('p').setStyle('color', 'red');
1836
1837
1838 #### Create Elements From an Array:
1839
1840         var myElements = new Elements(['myElementID', $('myElement'), 'myElementID2', document.getElementById('myElementID3')]);
1841
1842
1843 ### Notes:
1844
1845 - In MooTools, every DOM function which returns a collection of nodes (such as [$$][]) returns the nodes as instances of Elements.
1846 - Because Elements is an array-like-object, it accepts all the [Array][] methods, while giving precedence to [Element][] and [Elements][] methods.
1847 - Every node of the Elements instance has all the [Element][] methods.
1848
1849 ### See Also:
1850
1851 - [$$][], [$][], [Element][], [Elements][], [Array][]
1852
1853
1854
1855 Elements Method: filter {#Elements:filter}
1856 ----------------------------------------------
1857
1858 Filters a collection of elements by a given tag name.  This method will be able to filter by any selector.
1859 It also works like [Array:filter][], by filtering collection of elements with a function.
1860
1861
1862 ### Syntax:
1863
1864         var filteredElements = elements.filter(selector);
1865
1866 ### Arguments:
1867
1868 1. selector - (*mixed*) A single CSS selector.
1869
1870 ### Returns:
1871
1872 * (*array*) A subset of this [Elements][] instance.
1873
1874
1875 Deprecated Functions {#Deprecated-Functions}
1876 ============================================
1877
1878 Element Method: hasChild {#Deprecated-Functions:hasChild}
1879 ---------------------------------------------------------
1880
1881 This method has been deprecated. Use [Element:contains][] instead.
1882
1883 ### Example:
1884
1885         var myElement = document.id('element1');
1886         var myElement2 = document.id('element2');
1887         myElement !== myElement2 && myElement.contains(element2);
1888
1889         // could be implemented as:
1890         Element.implement('hasChild', function(element){
1891                 return this !== element && this.contains(element);
1892         });
1893
1894
1895
1896 [document:id]: #Window:document-id
1897 [$]: #Window:dollar
1898 [$$]: #Window:dollars
1899
1900 [Array]: /core/Types/Array
1901 [Array:filter]: /core/Types/Array#Array:filter
1902
1903 [Element]: #Element
1904 [Elements]: #Elements
1905 [Element:set]: #Element:set
1906 [Element:get]: #Element:get
1907 [Element:erase]: #Element:erase
1908 [Element:setProperty]: #Element:setProperty
1909 [Element:getProperty]: #Element:getProperty
1910 [Element:removeProperty]: #Element:removeProperty
1911 [Element:getElement]: #Element:getElement
1912 [Element:getElements]: #Element:getElements
1913 [Element.Properties]: #Element-Properties
1914 [Element:getPrevious]: #Element:getPrevious
1915 [Element:getAllPrevious]: #Element:getAllPrevious
1916 [Element:contains]: #Element:contains
1917
1918 [Element:addEvents]: /core/Element/Element.Event#Element:addEvents
1919 [Element:setStyles]: /core/Element/Element.Style#Element:setStyles
1920
1921 [The Dollar Safe Mode]: http://mootools.net/blog/2009/06/22/the-dollar-safe-mode/
1922
1923 [MDC Element:removeChild]: https://developer.mozilla.org/En/DOM/Node.removeChild
1924 [MDC Element:replaceChild]: https://developer.mozilla.org/En/DOM/Node.replaceChild