diff --git a/DOM-Traversal.md b/DOM-Traversal.md new file mode 100644 index 0000000..d75947b --- /dev/null +++ b/DOM-Traversal.md @@ -0,0 +1,529 @@ +Welcome to the wiki.* [`closest`](#usage-closest) | [`parent`](#usage-parent) | [`children`](#usage-children) | [`findAll`](#usage-findAll) +* [`descendants`](#usage-descendants) | [`parents`](#usage-parents) | [`parentsUntil`](#usage-parentsUntil) +* [`descendantsUntil`](#usage-descendantsUntil) +* [`next`](#usage-next) | [`prev`](#usage-prev) | [`nextSibling`](#usage-nextSibling) | [`prevSibling`](#usage-prevSibling) +* [`sibling`](#usage-sibling) | [`nextAll`](#usage-nextAll) | [`prevAll`](#usage-prevAll) | [`siblings`](#usage-siblings) +* [`nextUntil`](#usage-nextUntil) | [`prevUntil`](#usage-prevUntil) +* [`eq`](#usage-eq) | [`first`](#usage-first) | [`last`](#usage-last) | [`filterBy`](#usage-filterBy) | [`not`](#usage-not) + +--- + +## .closest + +**Description** +Travels up the DOM tree from the current element to find the first ancestor that matches the selector. + +**Parameters** + +* `selector` (String): A string containing a selector expression to match elements against. + +**Returns** + +* (jBase): A new jBase object containing the matching ancestor. + +**Example** + +```javascript +// Find the nearest container div for a button +const container = $('button.save').closest('.container'); + +``` + +--- + +## .parent + +**Description** +Get the direct parent of each element in the current set of matched elements. + +**Parameters** + +* None. + +**Returns** + +* (jBase): The parent elements. + +**Example** + +```javascript +$('.item').parent().addClass('has-items'); + +``` + +--- + +## .children + +**Description** +Get the children of each element in the set of matched elements, optionally filtered by a selector. + +**Parameters** + +* `selector` (String, optional): A string containing a selector expression to match elements against. + +**Returns** + +* (jBase): The children elements. + +**Example** + +```javascript +// Get only list items with class 'active' +$('ul.menu').children('li.active'); + +``` + +--- + +## .findAll + +**Description** +Finds all descendant elements that match the selector. + +**Parameters** + +* `selector` (String): The selector to match. + +**Returns** + +* (jBase): The found elements. + +**Example** + +```javascript +// Find all spans inside the header +$('.header').findAll('span'); + +``` + +--- + +## .descendants + +**Description** +Get all descendant elements (children, grandchildren, etc.), optionally filtered by a selector. + +**Parameters** + +* `selector` (String, optional): Filter for the descendants. + +**Returns** + +* (jBase): All descendant elements. + +**Example** + +```javascript +$('#tree').descendants('.leaf'); + +``` + +--- + +## .parents + +**Description** +Get the ancestors of each element in the current set of matched elements. + +**Parameters** + +* `selector` (String, optional): If supplied, the ancestors are filtered. + +**Returns** + +* (jBase): The ancestor elements. + +**Example** + +```javascript +$('span').parents('div'); + +``` + +--- + +## .parentsUntil + +**Description** +Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector. + +**Parameters** + +* `selector` (String): The selector that indicates where to stop matching ancestor elements. +* `filter` (String, optional): A string containing a selector expression to filter the returned ancestors. + +**Returns** + +* (jBase): The ancestor elements between the current element and the stop selector. + +**Example** + +```javascript +// Get all parents of .item until .container is reached +$('.item').parentsUntil('.container'); + +``` + +--- + +## .descendantsUntil + +**Description** +Get all descendant elements, but stop searching deeper in a specific branch once the provided selector is matched. + +**Parameters** + +* `selector` (String): The selector that indicates where to stop the deep traversal. + +**Returns** + +* (jBase): The descendant elements found before hitting the stop selector. + +**Example** + +```javascript +// Find descendants but don't look inside nested .protected-areas +$('.root').descendantsUntil('.protected-area'); + +``` + +--- + +## .next + +**Description** +Get the immediately following sibling of each element in the set of matched elements. + +**Parameters** + +* `selector` (String, optional): If supplied, the method only returns the element if it matches. + +**Returns** + +* (jBase): The next sibling. + +**Example** + +```javascript +$('.current-step').next().addClass('next-step'); + +``` + +--- + +## .prev + +**Description** +Get the immediately preceding sibling of each element in the set of matched elements. + +**Parameters** + +* `selector` (String, optional): If supplied, the method only returns the element if it matches. + +**Returns** + +* (jBase): The previous sibling. + +**Example** + +```javascript +$('.step-2').prev(); + +``` + +--- + +## .nextSibling + +**Description** +Get the immediately following DOM sibling element. Unlike `next()`, this focuses strictly on the DOM structure `nextElementSibling`. + +**Parameters** + +* None. + +**Returns** + +* (jBase): The next sibling element. + +**Example** + +```javascript +const nextEl = $('.current').nextSibling(); + +``` + +--- + +## .prevSibling + +**Description** +Get the immediately preceding DOM sibling element. Unlike `prev()`, this focuses strictly on the DOM structure `previousElementSibling`. + +**Parameters** + +* None. + +**Returns** + +* (jBase): The previous sibling element. + +**Example** + +```javascript +const prevEl = $('.current').prevSibling(); + +``` + +--- + +## .sibling + +**Description** +Get a single, specific sibling element. Unlike `siblings()` which returns all siblings, this method returns a specific one (e.g. the immediate next or matching a specific condition depending on implementation). +*(Note: Based on typical usage, this often acts like a directed `next` or `prev` or finds a specific single neighbor).* + +**Parameters** + +* `selector` (String, optional): A selector to identify the specific sibling. + +**Returns** + +* (jBase): The specific sibling element. + +**Example** + +```javascript +// Get a specific sibling with class 'active' +$('.item').sibling('.active'); + +``` + +--- + +## .nextAll + +**Description** +Get all following siblings of each element in the set of matched elements, optionally filtered by a selector. + +**Parameters** + +* `selector` (String, optional): A string containing a selector expression to match elements against. + +**Returns** + +* (jBase): All following sibling elements. + +**Example** + +```javascript +// Select all elements coming after the active one +$('.active').nextAll(); + +``` + +--- + +## .prevAll + +**Description** +Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector. + +**Parameters** + +* `selector` (String, optional): A string containing a selector expression to match elements against. + +**Returns** + +* (jBase): All preceding sibling elements. + +**Example** + +```javascript +// Select all elements coming before the active one +$('.active').prevAll(); + +``` + +--- + +## .siblings + +**Description** +Get the siblings of each element in the set of matched elements. + +**Parameters** + +* `selector` (String, optional): If supplied, the siblings are filtered. + +**Returns** + +* (jBase): The sibling elements. + +**Example** + +```javascript +// Find all siblings that are not active +$('.active').siblings(':not(.active)'); + +``` + +--- + +## .nextUntil + +**Description** +Get all following siblings of each element up to but not including the element matched by the selector. + +**Parameters** + +* `selector` (String): The selector that indicates where to stop matching following sibling elements. +* `filter` (String, optional): A selector to filter the returned siblings. + +**Returns** + +* (jBase): The following siblings up to the stop selector. + +**Example** + +```javascript +// Select all elements between header and footer +$('#header').nextUntil('#footer'); + +``` + +--- + +## .prevUntil + +**Description** +Get all preceding siblings of each element up to but not including the element matched by the selector. + +**Parameters** + +* `selector` (String): The selector that indicates where to stop matching preceding sibling elements. +* `filter` (String, optional): A selector to filter the returned siblings. + +**Returns** + +* (jBase): The preceding siblings up to the stop selector. + +**Example** + +```javascript +// Select all items backwards until the start marker +$('.end-marker').prevUntil('.start-marker'); + +``` + +--- + +## .eq + +**Description** +Reduce the set of matched elements to the one at the specified index. + +**Parameters** + +* `index` (Number): An integer indicating the 0-based position of the element. + +**Returns** + +* (jBase): The element at the index. + +**Example** + +```javascript +// Select the 3rd element (index 2) +$('li').eq(2).css('color', 'red'); + +``` + +--- + +## .first + +**Description** +Reduce the set of matched elements to the first in the set. + +**Parameters** + +* None. + +**Returns** + +* (jBase): The first element. + +**Example** + +```javascript +$('p').first(); + +``` + +--- + +## .last + +**Description** +Reduce the set of matched elements to the final one in the set. + +**Parameters** + +* None. + +**Returns** + +* (jBase): The last element. + +**Example** + +```javascript +$('p').last(); + +``` + +--- + +## .filterBy + +**Description** +Reduce the set of matched elements to those that match the selector. + +**Parameters** + +* `selector` (String): The selector to match. + +**Returns** + +* (jBase): The filtered subset. + +**Example** + +```javascript +$('div').filterBy('.highlight'); + +``` + +--- + +## .not + +**Description** +Remove elements from the set of matched elements. + +**Parameters** + +* `selector` (String): A string containing a selector expression to match elements against. + +**Returns** + +* (jBase): The subset without the matched elements. + +**Example** + +```javascript +$('input').not('[type="submit"]'); + +``` \ No newline at end of file