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