From dd02fb5af31a64bdcdac4e08a159fc3c1bab8f10 Mon Sep 17 00:00:00 2001 From: Dave Methvin Date: Sun, 26 Jan 2014 16:58:59 -0500 Subject: [PATCH] More emphasis about avoiding .add(), ref gh-240 --- entries/add.xml | 2 +- entries/jQuery.xml | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/entries/add.xml b/entries/add.xml index cf110550..e93025df 100644 --- a/entries/add.xml +++ b/entries/add.xml @@ -37,7 +37,7 @@ Add elements to the set of matched elements.

Given a jQuery object that represents a set of DOM elements, the .add() method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add() can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.

-

Do not assume that this method appends the elements to the existing collection in the order they are passed to the .add() method. When all elements are members of the same document, the resulting collection from .add() will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order, use the $(array_of_DOM_elements) signature.

+

Do not assume that this method appends the elements to the existing collection in the order they are passed to the .add() method. When all elements are members of the same document, the resulting collection from .add() will be sorted in document order; that is, in order of each element's appearance in the document. If the collection consists of elements from different documents or ones not in any document, the sort order is undefined. To create a jQuery object with elements in a well-defined order and without sorting overhead, use the $(array_of_DOM_elements) signature.

The updated set of elements can be used in a following (chained) method, or assigned to a variable for later use. For example:


 $( "p" ).add( "div" ).addClass( "widget" );
diff --git a/entries/jQuery.xml b/entries/jQuery.xml
index 3cd7dedb..014a5fcf 100644
--- a/entries/jQuery.xml
+++ b/entries/jQuery.xml
@@ -57,9 +57,8 @@ $( "div.foo" ).click(function() {
       
Internally, selector context is implemented with the .find() method, so  $( "span", this ) is equivalent to  $( this ).find( "span" ).

 
       
Using DOM elements

-      
The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way.

-      
Note: These formulations are meant to consume only DOM elements; feeding mixed data to the elementArray form is particularly discouraged.

-      
A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

+      
The second and third formulations of this function create a jQuery object using one or more DOM elements that were already selected in some other way. When passing an array, each element must be a DOM element; mixed data is not supported. A jQuery object is created from the array elements in the order they appeared in the array; unlike most other multi-element jQuery operations, the elements are not sorted in DOM order.

+      
A common use of single-DOM-element construction is to call jQuery methods on an element that has been passed to a callback function through the keyword this:

       

 $( "div.foo" ).click(function() {
   $( this ).slideUp();