Skip to content

Added documentation for addBack, link and deprecation to andSelf #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
pobocks wants to merge 1 commit into from
Closed

Added documentation for addBack, link and deprecation to andSelf #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions entries/addBack.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
<?xml version="1.0"?>
<entry type="method" name="addBack" return="jQuery">
<title>.addBack()</title>
<signature>
<added>1.6</added>
<argument name="selector" type="Selector" optional="true">
<desc>A string containing a selector expression to match the current set of elements against.</desc>
</argument>
</signature>
<desc>Add the previous set of elements on the stack to the current set, optionally filtered by a selector.</desc>
<longdesc>
<p>As described in the discussion for <code><a href="http://api.jquery.com/end/">.end()</a></code>, jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, <code>.addBack()</code> can help.</p>
<p>Consider a page with a simple list on it:</p>
<pre><code>
&lt;ul&gt;
&lt;li&gt;list item 1&lt;/li&gt;
&lt;li&gt;list item 2&lt;/li&gt;
&lt;li class="third-item"&gt;list item 3&lt;/li&gt;
&lt;li&gt;list item 4&lt;/li&gt;
&lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</code></pre>
<p>The result of the following code is a red background behind items 3, 4 and 5:</p>
<pre><code>$('li.third-item').nextAll().addBack()
.css('background-color', 'red');
</code></pre>
<p>First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to <code>.nextAll()</code> then pushes the set of items 4 and 5 onto the stack. Finally, the <code>.addBack()</code> invocation merges these two sets together, creating a jQuery object that points to all three items in document order: <code>{[&lt;li.third-item&gt;,&lt;li&gt;,&lt;li&gt; ]}</code>.</p>
</longdesc>
<example>
<desc>The <code>.addBack()</code> method causes the previous set of DOM elements in the traversal stack to be added to the current set. In the first example, the top stack contains the set resulting from <code>.find("p")</code>. In the second example, <code>.addBack()</code> adds the previous set of elements on the stack — in this case <code>$("div.after-addback")</code> — to the current set, selecting both the div and its enclosed paragraphs.</desc>
<code><![CDATA[
$("div.left, div.right").find("div, div > p").addClass("border");

// First Example
$("div.before-addback").find("p").addClass("background");

// Second Example
$("div.after-addback").find("p").addBack().addClass("background");
]]></code>
<css><![CDATA[
p, div { margin:5px; padding:5px; }
.border { border: 2px solid red; }
.background { background:yellow; }
.left, .right { width: 45%; float: left;}
.right { margin-left:3%; }
]]></css>
<html><![CDATA[
<div class="left">
<p><strong>Before <code>addBack()</code></strong></p>
<div class="before-addback">
<p>First Paragraph</p>
<p>Second Paragraph</p>
</div>
</div>
<div class="right">
<p><strong>After <code>addBack()</code></strong></p>
<div class="after-addback">
<p>First Paragraph</p>
<p>Second Paragraph</p>
</div>
</div>
]]></html>
</example>
<category slug="traversing/miscellaneous-traversal"/>
<category slug="version/1.2"/>
</entry>
3 changes: 2 additions & 1 deletion entries/andSelf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
<?xml version="1.0"?>
<entry type="method" name="andSelf" return="jQuery">
<entry type="method" name="andSelf" return="jQuery" deprecated="1.7">
<title>.andSelf()</title>
<signature>
<added>1.2</added>
</signature>
<desc>Add the previous set of elements on the stack to the current set.</desc>
<longdesc>
<p><strong>Note:</strong> This function has been deprecated, and is now an alias for <a href="http://api.jquery.com/addBack/"><code>.addBack()</code></a>, which should be preferred going forward.</p>
<p>As described in the discussion for <code><a href="http://api.jquery.com/end/">.end()</a></code>, jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, <code>.andSelf()</code> can help.</p>
<p>Consider a page with a simple list on it:</p>
<pre><code>
Expand Down