From 86511a77137bf43f4b98a9e855424b8286a743eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Go=C5=82=C4=99biowski-Owczarek?= Date: Mon, 19 Dec 2022 14:46:24 +0100 Subject: [PATCH] prevAll: Document issues with reverse doc order `.prevAll()` returns elements in the reverse document order. This can pose issues when used with APIs like `.append()` or `.wrapAll()`. Document how to deal with the issue with help from `jQuery.uniqueSort()`. Ref jquery/jquery#5149 --- entries/prevAll.xml | 95 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 94 insertions(+), 1 deletion(-) diff --git a/entries/prevAll.xml b/entries/prevAll.xml index 73f3f3f5..4b5f6062 100644 --- a/entries/prevAll.xml +++ b/entries/prevAll.xml @@ -7,7 +7,7 @@ A string containing a selector expression to match elements against. - Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector. + Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector, in the reverse document order.

Given a jQuery object that represents a set of DOM elements, the .prevAll() method searches through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements; the elements are returned in order beginning with the closest sibling.

The method optionally accepts a selector expression of the same type that we can pass to the $() function. If the selector is supplied, the elements will be filtered by testing whether they match it.

@@ -26,6 +26,36 @@ $( "li.third-item" ).prevAll().css( "background-color", "red" );

The result of this call is a red background behind items 1 and 2. Since we do not supply a selector expression, these preceding elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.

+

Note: Many APIs, like append or wrapAll process node in the order in which they appear in the jQuery object. This can pose issues with APIs like .prevAll() in which the reverse document order is used. Consider the following example:

+ 

+<div>
+  <div>First</div>
+  <div>Second</div>
+  <div class="last-item">Last</div>
+</div>
+
+

The following call:

+ 

+$( ".last-item" )
+  .prevAll()
+  .wrapAll( "<div class='wrapper'></div>" );
+
+

would result in the following HTML:

+ 

+<div>
+  <div class="wrapper">
+    <div>Second</div>
+    <div>First</div>
+  </div>
+  <div class="last-item">Last</div>
+</div>
+
+

because "Item 2" gets appended to the wrapper div first. To work around the issue, you may use $.uniqueSort() on the .prevAll() output first:

+ 

+var prevSiblings = $( ".last-item" ).prevAll();
+$.uniqueSort( prevSiblings );
+prevSiblings.wrapAll( "<div class='wrapper'></div>" );
+
Locate all the divs preceding the last div and give them a class. @@ -50,6 +80,69 @@ $( "div" ).last().prevAll().addClass( "before" );
+]]> + + + Locate all the divs preceding the last item and wrap them with a div with class wrapper - with or without $.uniqueSort(). + + +