new traversing docs

Author: gjohnson

content/jquery-basics/traversing.md

@@ -5,36 +5,68 @@ title   : "Traversing"
 ---
 ## Traversing
 
-Once you have a jQuery selection, you can find other elements using your selection as a starting point.
+Once you have made an intial selection with jQuery, you may want to traverse a little deeper into what you just selected. Traversing can be broken down into three basic parts: parents, children and sibilings. jQuery has an abundance of easy to use methods for all these parts. You will notice that each of these methods can optionaly be passed another selector or selection in order to refine your selection even more.
 
-For complete documentation of jQuery traversal methods, visit [http://api.jquery.com/category/traversing/](http://api.jquery.com/category/traversing/ "Traversing documentation on api.jquery.com").
 
-<div class="note" markdown="1">
-### Note
+### Parents
 
-Be cautious with traversing long distances in your documents — complex traversal makes it imperative that your document's structure remain the same, something that's difficult to guarantee even if you're the one creating the whole application from server to client. One- or two-step traversal is fine, but you generally want to avoid traversals that take you from one container to another.
+There are four methods for finding the parents from a selection: `$.fn.parent`, `$.fn.parents`, `$.fn.parentsUntil` and `$.fn.closest`. 
+
+<div class="example" markdown="1">
+Selecting an element's direct parent
+
+	$('#myList').parent();
 </div>
+<div class="example" markdown="1">
+Selecting all the parents of an element which match a given selector
 
+	$('#myList').parents('div');
+</div>
 <div class="example" markdown="1">
-Moving around the DOM using traversal methods
+Selecting all the parents of an element up to, but *not including* the selector
 
-    $('h1').next('p');
-    $('div:visible').parent();
-    $('input[name=first_name]').closest('form');
-    $('#myList').children();
-    $('li.selected').siblings();
+	$('#myList').parentsUntil('div');
 </div>
 
-You can also iterate over a selection using `$.fn.each`. This method iterates over all of the elements in a selection, and runs a function for each one. The function receives the index of the current element and the DOM element itself as arguments. Inside the function, the DOM element is also available as `this` by default.
+### Children
 
+There are only 2 methods for finding children elements from a selection: `$.fn.children` and `$.fn.find`. The difference between these methods lies in how far into the child structure the selection is made. `$.fn.children` only operates on direct child nodes, while `$.fn.find` can traverse recursively into children, and children of those children, etc.
+
+<div class="example" markdown="1">
+Selecting an element's direct children
+
+	$('#myList').children();
+</div>
 <div class="example" markdown="1">
-Iterating over a selection
+Finding all the links within a selection that match the selector
+
+	$('#myList').find('a.external');
+</div>
+
+### Sibilings
+
+The rest of the traversal methods within jQuery all deal with finding sibiling selections. There are a few basic methods as far as direction is concerned. You can find previous elements with `$.fn.prev`, next elements with `$.fn.next` and both with `$.fn.sibilings`. There are also a few other methods that build onto these methods, similar to how `$.fn.parentsUntil` works; `$.fn.nextAll`, `$.fn.nextUntil`, `$.fn.prevAll` and `$.fn.prevUntil`.
 
-    $('#myList li').each(function(idx, el) {
-        console.log(
-            'Element ' + idx +
-            'has the following html: ' +
-            $(el).html()
-        );
-    });
+<div class="example" markdown="1">
+Selecting an element's next sibiling that matches the given selector
+
+	$('#myList').next('div.section');
+</div>
+<div class="example" markdown="1">
+Selecting an element's previous sibiling that matches the given selector
+
+	$('#myList').prev('div.section');
+</div>
+<div class="example" markdown="1">
+Selecting an element's sibilings in both directions that matches the given selector
+
+	$('#myList').sibilings('div.section');
+</div>
+
+You can see all these methods metioned and more at the docs [http://api.jquery.com/category/traversing/tree-traversal/](http://api.jquery.com/category/traversing/tree-traversal/ "Traversal documentation on api.jquery.com")
+
+<div class="note" markdown="1">
+### Note
+
+Be cautious with traversing long distances in your documents — complex traversal makes it imperative that your document's structure remain the same, something that's difficult to guarantee even if you're the one creating the whole application from server to client. One- or two-step traversal is fine, but you generally want to avoid traversals that take you from one container to another.
 </div>