Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
14854 lines (14279 sloc) 769 KB
<?xml version="1.0"?>
<api>
<categories>
<category name="Ajax">
<category name="Global Ajax Event Handlers"/>
<category name="Helper Functions"/>
<category name="Low-Level Interface"/>
<category name="Shorthand Methods"/>
</category>
<category name="Attributes"/>
<category name="Core"/>
<category name="CSS"/>
<category name="Data"/>
<category name="Dimensions"/>
<category name="Effects">
<category name="Basics"/>
<category name="Custom"/>
<category name="Fading"/>
<category name="Sliding"/>
</category>
<category name="Events">
<category name="Browser Events"/>
<category name="Document Loading"/>
<category name="Event Handler Attachment"/>
<category name="Event Object"/>
<category name="Form Events"/>
<category name="Keyboard Events"/>
<category name="Mouse Events"/>
</category>
<category name="Forms"/>
<category name="Manipulation">
<category name="Class Attribute"/>
<category name="Copying"/>
<category name="DOM Insertion"/>
<category name="DOM Insertion, Around"/>
<category name="DOM Insertion, Inside"/>
<category name="DOM Insertion, Outside"/>
<category name="DOM Removal"/>
<category name="DOM Replacement"/>
<category name="General Attributes"/>
<category name="Style Properties"/>
</category>
<category name="Miscellaneous">
<category name="Collection Manipulation"/>
<category name="Data Storage"/>
<category name="DOM Element Methods"/>
<category name="Setup Methods"/>
</category>
<category name="Offset"/>
<category name="Plugin Authoring"/>
<category name="Properties">
<category name="Properties of jQuery Object Instances"/>
<category name="Properties of the Global jQuery Object"/>
</category>
<category name="Selectors">
<category name="Attribute"/>
<category name="Basic"/>
<category name="Basic Filter"/>
<category name="Child Filter"/>
<category name="Content Filter"/>
<category name="Form"/>
<category name="Hierarchy"/>
<category name="Visibility Filter"/>
</category>
<category name="Traversing">
<category name="Filtering"/>
<category name="Miscellaneous Traversing"/>
<category name="Tree Traversal"/>
</category>
<category name="Utilities"/>
<category name="Version">
<category name="Version 1.0"/>
<category name="Version 1.0.4"/>
<category name="Version 1.1"/>
<category name="Version 1.1.2"/>
<category name="Version 1.1.3"/>
<category name="Version 1.1.4"/>
<category name="Version 1.2"/>
<category name="Version 1.2.3"/>
<category name="Version 1.2.6"/>
<category name="Version 1.3"/>
<category name="Version 1.4"/>
<category name="Version 1.4.1"/>
<category name="Version 1.4.2"/>
</category>
</categories>
<entries>
<entry type="method" name="undelegate" return="jQuery">
<desc><![CDATA[Remove a handler from the event for all elements which match the current selector, now or in the future, based upon a specific set of root elements.]]></desc>
<signature>
<added>1.4.2</added>
</signature>
<signature>
<added>1.4.2</added>
<argument name="selector" type="String">
<desc><![CDATA[A selector which will be used to filter the event results.]]></desc>
</argument>
<argument name="eventType" type="String">
<desc><![CDATA[A string containing a JavaScript event type, such as "click" or "keydown"]]></desc>
</argument>
</signature>
<signature>
<added>1.4.2</added>
<argument name="selector" type="String">
<desc><![CDATA[A selector which will be used to filter the event results.]]></desc>
</argument>
<argument name="eventType" type="String">
<desc><![CDATA[A string containing a JavaScript event type, such as "click" or "keydown"]]></desc>
</argument>
<argument name="handler" type="Function">
<desc><![CDATA[A function to execute at the time the event is triggered.]]></desc>
</argument>
</signature>
<longdesc><![CDATA[
<p>Undelegate is a way of removing event handlers that have been bound using <a href="/delegate">.delegate()</a>. It works virtually identically to <a href="/die">.die()</a> with the addition of a selector filter argument (which is required for delegation to work).</p>
]]></longdesc>
<example>
<desc><![CDATA[Can bind and unbind events to the colored button.]]></desc>
<code><![CDATA[
function aClick() {
$("div").show().fadeOut("slow");
}
$("#bind").click(function () {
$("body").delegate("#theone", "click", aClick)
.find("#theone").text("Can Click!");
});
$("#unbind").click(function () {
$("body").undelegate("#theone", "click", aClick)
.find("#theone").text("Does nothing...");
});
]]></code>
<css><![CDATA[
button { margin:5px; }
button#theone { color:red; background:yellow; }
]]></css>
<html><![CDATA[<button id="theone">Does nothing...</button>
<button id="bind">Bind Click</button>
<button id="unbind">Unbind Click</button>
<div style="display:none;">Click!</div>]]></html>
</example>
<example>
<desc><![CDATA[To unbind all delegated events from all paragraphs, write:]]></desc>
<code><![CDATA[$("p").undelegate()]]></code>
</example>
<example>
<desc><![CDATA[To unbind all delegated click events from all paragraphs, write:]]></desc>
<code><![CDATA[$("p").undelegate( "click" )]]></code>
</example>
<example>
<desc><![CDATA[To undelegate just one previously bound handler, pass the function in as the third argument:]]></desc>
<code><![CDATA[var foo = function () {
// code to handle some kind of event
};
$("body").delegate("p", "click", foo); // ... now foo will be called when paragraphs are clicked ...
$("body").undelegate("p", "click", foo); // ... foo will no longer be called.]]></code>
</example>
<category name="Event Handler Attachment"/>
<category name="Version 1.4.2"/>
</entry>
<entry type="method" name="delegate" return="jQuery">
<desc><![CDATA[Attach a handler to the event for all elements which match the current selector, now or in the future, based upon a specific set of root elements.]]></desc>
<signature>
<added>1.4.2</added>
<argument name="selector" type="String">
<desc><![CDATA[A selector to filter the elements that trigger the event.]]></desc>
</argument>
<argument name="eventType" type="String">
<desc><![CDATA[A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.]]></desc>
</argument>
<argument name="handler" type="Function">
<desc><![CDATA[A function to execute at the time the event is triggered.]]></desc>
</argument>
</signature>
<signature>
<added>1.4.2</added>
<argument name="selector" type="String">
<desc><![CDATA[A selector to filter the elements that trigger the event.]]></desc>
</argument>
<argument name="eventType" type="String">
<desc><![CDATA[A string containing one or more space-separated JavaScript event types, such as "click" or "keydown," or custom event names.]]></desc>
</argument>
<argument name="eventData" type="Object">
<desc><![CDATA[A map of data that will be passed to the event handler.]]></desc>
</argument>
<argument name="handler" type="Function">
<desc><![CDATA[A function to execute at the time the event is triggered.]]></desc>
</argument>
</signature>
<longdesc><![CDATA[
<p>Delegate is an alternative to using the <a href="/live">.live()</a> method, allowing for each binding of event delegation to specific DOM elements. For example the following delegate code:</p>
<pre>$("table").delegate("td", "hover", function(){
$(this).toggleClass("hover");
});</pre>
<p>Is equivalent to the following code written using <code>.live()</code>:</p>
<pre>$("table").each(function(){
$("td", this).live("hover", function(){
$(this).toggleClass("hover");
});
});</pre>
<p>See also the <a href="/undelegate">.undelegate()</a> method for a way of removing event handlers added in <a href="/delegate">.delegate()</a>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Click a paragraph to add another. Note that .delegate() binds the click event to all paragraphs - even new ones.]]></desc>
<code><![CDATA[
$("body").delegate("p", "click", function(){
$(this).after("<p>Another paragraph!</p>");
});
]]></code>
<css><![CDATA[
p { background:yellow; font-weight:bold; cursor:pointer;
padding:5px; }
p.over { background: #ccc; }
span { color:red; }
]]></css>
<html><![CDATA[<p>Click me!</p>
<span></span>]]></html>
</example>
<example>
<desc><![CDATA[To display each paragraph's text in an alert box whenever it is clicked:]]></desc>
<code><![CDATA[$("body").delegate("p", "click", function(){
alert( $(this).text() );
});]]></code>
</example>
<example>
<desc><![CDATA[To cancel a default action and prevent it from bubbling up, return false:]]></desc>
<code><![CDATA[$("body").delegate("a", "click", function() { return false; })]]></code>
</example>
<example>
<desc><![CDATA[To cancel only the default action by using the preventDefault method.]]></desc>
<code><![CDATA[$("body").delegate("a", "click", function(event){
event.preventDefault();
});]]></code>
</example>
<example>
<desc><![CDATA[Can bind custom events too.]]></desc>
<code><![CDATA[
$("body").delegate("p", "myCustomEvent", function(e, myName, myValue){
$(this).text("Hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent");
});
]]></code>
<css><![CDATA[
p { color:red; }
span { color:blue; }
]]></css>
<html><![CDATA[<p>Has an attached custom event.</p>
<button>Trigger custom event</button>
<span style="display:none;"></span>]]></html>
</example>
<category name="Event Handler Attachment"/>
<category name="Version 1.4.2"/>
</entry>
<entry type="method" name="jQuery.error" return="">
<signature>
<added>1.4.1</added>
<argument name="message" type="String">
<desc><![CDATA[The message to send out.]]></desc>
</argument>
</signature>
<desc><![CDATA[Takes a string and throws an exception containing it.]]></desc>
<longdesc><![CDATA[
<p>This method exists primarily for plugin developers who wish to override it and provide a better display (or more information) for the error messages.</p>
]]></longdesc>
<example>
<desc><![CDATA[Override jQuery.error for display in Firebug.]]></desc>
<code><![CDATA[jQuery.error = console.error;]]></code>
</example>
<category name="Plugin Authoring"/>
<category name="Version 1.4.1"/>
</entry>
<entry type="method" name="jQuery.parseJSON" return="Object">
<signature>
<added>1.4.1</added>
<argument name="json" type="String">
<desc><![CDATA[The JSON string to parse.]]></desc>
</argument>
</signature>
<desc><![CDATA[Takes a well-formed JSON string and returns the resulting JavaScript object.]]></desc>
<longdesc><![CDATA[
<p>Passing in a malformed JSON string will result in an exception being thrown. For example, the following are all malformed JSON strings:</p>
<ul>
<li><code>{test: 1}</code> (test does not have double quotes around it).</li>
<li><code>{'test': 1}</code> ('test' is using single quotes instead of double quotes).</li>
</ul>
<p>Additionally if you pass in nothing, an empty string, null, or undefined, 'null' will be returned from parseJSON.</p>
]]></longdesc>
<example>
<desc><![CDATA[Parse a JSON string.]]></desc>
<code><![CDATA[var obj = jQuery.parseJSON('{"name":"John"}');
alert( obj.name === "John" );]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.4.1"/>
</entry>
<entry type="method" name="jQuery.proxy" return="Function">
<signature>
<added>1.4</added>
<argument name="function" type="Function">
<desc><![CDATA[The function whose context will be changed.]]></desc>
</argument>
<argument name="context" type="Object">
<desc><![CDATA[The object to which the context (`this`) of the function should be set.]]></desc>
</argument>
</signature>
<signature>
<added>1.4</added>
<argument name="context" type="Object">
<desc><![CDATA[The object to which the context of the function should be set.]]></desc>
</argument>
<argument name="name" type="String">
<desc><![CDATA[The name of the function whose context will be changed (should be a property of the 'context' object.]]></desc>
</argument>
</signature>
<desc><![CDATA[Takes a function and returns a new one that will always have a particular context.]]></desc>
<longdesc><![CDATA[
<p>This method is most useful for attaching event handlers to an element where the context is pointing back to a different object. Additionally, jQuery makes sure that even if you bind the function returned from jQuery.proxy() it will still unbind the correct function, if passed the original.</p>
]]></longdesc>
<example>
<desc><![CDATA[Enforce the context of the function.]]></desc>
<code><![CDATA[var obj = {
name: "John",
test: function() {
alert( this.name );
$("#test").unbind("click", obj.test);
}
};
$("#test").click( jQuery.proxy( obj, "test" ) );
// This also works:
// $("#test").click( jQuery.proxy( obj.test, obj ) );]]></code>
</example>
<category name="Event Handler Attachment"/>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="focusout" return="jQuery">
<desc><![CDATA[Bind an event handler to the "focusout" JavaScript event.]]></desc>
<signature>
<added>1.4</added>
<argument name="handler(eventObject)" type="Function">
<desc><![CDATA[A function to execute each time the event is triggered.]]></desc>
</argument>
</signature>
<longdesc><![CDATA[
<p>This method is a shortcut for <code>.bind('focusout', handler)</code>.</p>
<p>The <code>focusout</code> event is sent to an element when it, or any element inside of it, loses focus. This is distinct from the <a href="/blur">blur</a> event in that it supports detecting the loss of focus from parent elements (in other words, it supports events bubbling).</p>
<p>This event will likely be used together with the <a href="/focusin">focusin</a> event.</p>
]]></longdesc>
<example>
<desc><![CDATA[Watch for a loss of focus to occur within the paragraphs on the page.]]></desc>
<css><![CDATA[span {display:none;}]]></css>
<code><![CDATA[
$("p").focusout(function() {
$(this).find("span").css('display','inline').fadeOut(1000);
});
]]></code>
<html><![CDATA[
<p>
<input type="text" />
<span>focusout fire</span>
</p>
<p>
<input type="password" />
<span>focusout fire</span>
</p>]]></html>
</example>
<category name="Keyboard Events"/>
<category name="Mouse Events"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="focusin" return="jQuery">
<desc><![CDATA[Bind an event handler to the "focusin" JavaScript event.]]></desc>
<signature>
<added>1.4</added>
<argument name="handler(eventObject)" type="Function">
<desc><![CDATA[A function to execute each time the event is triggered.]]></desc>
</argument>
</signature>
<longdesc><![CDATA[
<p>This method is a shortcut for <code>.bind('focusin', handler)</code>.</p>
<p>The <code>focusin</code> event is sent to an element when it, or any element inside of it, gains focus. This is distinct from the <a href="/focus">focus</a> event in that it supports detecting the focus event on parent elements.</p>
<p>This event will likely be used together with the <a href="/focusout">focusout</a> event.</p>
]]></longdesc>
<example>
<desc><![CDATA[Watch for a focus to occur within the paragraphs on the page.]]></desc>
<css><![CDATA[span {display:none;}]]></css>
<code><![CDATA[
$("p").focusin(function() {
$(this).find("span").css('display','inline').fadeOut(1000);
});
]]></code>
<html><![CDATA[<p><input type="text" /> <span>focusin fire</span></p>
<p><input type="password" /> <span>focusin fire</span></p>]]></html>
</example>
<category name="Keyboard Events"/>
<category name="Mouse Events"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="has" return="jQuery">
<signature>
<added>1.4</added>
<argument name="selector" type="String">
<desc><![CDATA[A string containing a selector expression to match elements against.]]></desc>
</argument>
</signature>
<signature>
<added>1.4</added>
<argument name="contained" type="Element">
<desc><![CDATA[A DOM element to match elements against.]]></desc>
</argument>
</signature>
<desc><![CDATA[Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.]]></desc>
<longdesc><![CDATA[
<p>Given a jQuery object that represents a set of DOM elements, the <code>.has()</code> method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against the descendants of the matching elements; the element will be included in the result if any of its descendant elements matches the selector.</p>
<p>Consider a page with a nested list as follows:</p>
<pre>
&lt;ul&gt;
&lt;li&gt;list item 1&lt;/li&gt;
&lt;li&gt;list item 2
&lt;ul&gt;
&lt;li&gt;list item 2-a&lt;/li&gt;
&lt;li&gt;list item 2-b&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;list item 3&lt;/li&gt;
&lt;li&gt;list item 4&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can apply this method to the set of list items as follows:</p>
<pre>$('li').has('ul').css('background-color', 'red');</pre>
<p>The result of this call is a red background for item 2, as it is the only <code>&lt;li&gt;</code> that has a <code>&lt;ul&gt;</code> among its descendants.</p>
]]></longdesc>
<example>
<desc><![CDATA[Check if an element is inside another.]]></desc>
<code><![CDATA[
$("ul").append("<li>" + ($("ul").has("li").length ? "Yes" : "No") + "</li>");
$("ul").has("li").addClass("full");
]]></code>
<css><![CDATA[
.full { border: 1px solid red; }
]]></css>
<html><![CDATA[
<ul><li>Does the UL contain an LI?</li></ul>
]]></html>
</example>
<category name="Filtering"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.contains" return="Boolean">
<signature>
<added>1.4</added>
<argument name="container" type="Element">
<desc><![CDATA[The DOM element that may contain the other element.]]></desc>
</argument>
<argument name="contained" type="Element">
<desc><![CDATA[The DOM node that may be contained by the other element.]]></desc>
</argument>
</signature>
<desc><![CDATA[Check to see if a DOM node is within another DOM node.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Check if an element is inside another.]]></desc>
<code><![CDATA[jQuery.contains(document.documentElement, document.body); // true
jQuery.contains(document.body, document.documentElement); // false]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.noop" return="Function">
<signature>
<added>1.4</added>
</signature>
<desc><![CDATA[An empty function.]]></desc>
<longdesc><![CDATA[
<p>You can use this empty function when you wish to pass around a function that will do nothing.</p>
<p>This is useful for plugin authors who offer optional callbacks; in the case that no callback is given, something like <code>jQuery.noop</code> could execute.</p>
]]></longdesc>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="delay" return="jQuery">
<signature>
<added>1.4</added>
<argument name="duration" type="Integer">
<desc><![CDATA[An integer indicating the number of milliseconds to delay execution of the next item in the queue.]]></desc>
</argument>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
</signature>
<desc><![CDATA[Set a timer to delay execution of subsequent items in the queue.]]></desc>
<longdesc><![CDATA[
<p>Added to jQuery in version 1.4, the <code>.delay()</code> method allows us to delay the execution of functions that follow it in the queue. It can be used with the standard effects queue or with a custom queue. </p>
<p>Durations are given in milliseconds; higher values indicate slower animations, not faster ones. The strings <code>'fast'</code> and <code>'slow'</code> can be supplied to indicate durations of 200 and 600 milliseconds, respectively.</p>
<p>Using the standard effects queue, we can, for example, set an 800-millisecond delay between the <code>.slideUp()</code> and <code>.fadeIn()</code> of <code>&lt;div id="foo"&gt;</code>:</p>
<pre>$('#foo').slideUp(300).delay(800).fadeIn(400);</pre>
<p>When this statement is executed, the element slides up for 300 milliseconds and then pauses for 800 milliseconds before fading in for 400 milliseconds.</p>
]]></longdesc>
<example>
<desc><![CDATA[Animate the hiding and showing of two divs, delaying the first before showing it.]]></desc>
<css><![CDATA[
div { width: 60px; height: 60px; float: left; }
.first { background-color: #3f3; }
.second { background-color: #33f;}]]></css>
<code><![CDATA[
$("button").click(function() {
$("div.first").slideUp(300).delay(800).fadeIn(400);
$("div.second").slideUp(300).fadeIn(400);
});]]></code>
<html><![CDATA[
<p><button>Run</button></p>
<div class="first"></div>
<div class="second"></div>]]></html>
</example>
<category name="Custom"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="parentsUntil" return="jQuery">
<signature>
<added>1.4</added>
<argument name="selector" optional="true" type="Selector">
<desc><![CDATA[A string containing a selector expression to indicate where to stop matching ancestor elements.]]></desc>
</argument>
</signature>
<desc><![CDATA[Get the ancestors of each element in the current set of matched elements, up to but not including the element matched by the selector.]]></desc>
<longdesc><![CDATA[
<p>Given a jQuery object that represents a set of DOM elements, the <code>.parentsUntil()</code> method traverses through the ancestors of these elements until it reaches an element matched by the selector passed in the method's argument. The resulting jQuery object contains all of the ancestors up to but not including the one matched by the <code>.parentsUntil()</code> selector. Consider a page with a basic nested list as follows:</p>
<pre>&lt;ul class="level-1"&gt;
&lt;li class="item-i"&gt;I&lt;/li&gt;
&lt;li class="item-ii"&gt;II
&lt;ul class="level-2"&gt;
&lt;li class="item-a"&gt;A&lt;/li&gt;
&lt;li class="item-b"&gt;B
&lt;ul class="level-3"&gt;
&lt;li class="item-1"&gt;1&lt;/li&gt;
&lt;li class="item-2"&gt;2&lt;/li&gt;
&lt;li class="item-3"&gt;3&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li class="item-c"&gt;C&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li class="item-iii"&gt;III&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at item A, we can find its ancestors up to but not including <code>&lt;ul class="level-1"&gt;</code> as follows:</p>
<pre>$('li.item-a').parentsUntil('.level-1')
.css('background-color', 'red');</pre>
<p>The result of this call is a red background for the level-2 list and the item II. </p>
<p>If the .parentsUntil() selector is not matched, or if no selector is supplied, the returned jQuery object contains all of the previous jQuery object's ancestors. For example, let's say we begin at item A again, but this time we use a selector that is not matched by any of its ancestors:</p>
<pre>$('li.item-a').parentsUntil('.not-here')
.css('background-color', 'red');</pre>
<p>The result of this call is a red background-color style applied to the level-2 list, the item II, the level-1 list, the <code>&lt;body&gt;</code> element, and the <code>&lt;html&gt;</code> element.</p>
]]></longdesc>
<example>
<desc><![CDATA[Find the ancestors of &lt;li class="item-a"&gt; up to &lt;ul class="level-1"&gt; and give them a red background color.]]></desc>
<code><![CDATA[
$('li.item-a').parentsUntil('.level-1')
.css('background-color', 'red');
]]></code>
<html><![CDATA[
<ul class="level-1">
<li class="item-i">I</li>
<li class="item-ii">II
<ul class="level-2">
<li class="item-a">A</li>
<li class="item-b">B
<ul class="level-3">
<li class="item-1">1</li>
<li class="item-2">2</li>
<li class="item-3">3</li>
</ul>
</li>
<li class="item-c">C</li>
</ul>
</li>
<li class="item-iii">III</li>
</ul>]]></html>
</example>
<category name="Tree Traversal"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="prevUntil" return="jQuery">
<signature>
<added>1.4</added>
<argument name="selector" optional="true" type="Selector">
<desc><![CDATA[A string containing a selector expression to indicate where to stop matching preceding sibling elements.]]></desc>
</argument>
</signature>
<desc><![CDATA[Get all preceding siblings of each element up to but not including the element matched by the selector.]]></desc>
<longdesc><![CDATA[
<p>Given a jQuery object that represents a set of DOM elements, the <code>.prevUntil()</code> method allows us to search through the predecessors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all previous siblings up to but not including the one matched by the <code>.prevUntil()</code> selector.</p>
<p>If the selector is not matched or is not supplied, all previous siblings will be selected; in these cases it selects the same elements as the <code>.prevAll()</code> method does when no filter selector is provided.</p>
<p>Consider a page with a simple definition list as follows:</p>
<pre>
&lt;dl&gt;
&lt;dt&gt;term 1&lt;/dt&gt;
&lt;dd&gt;definition 1-a&lt;/dd&gt;
&lt;dd&gt;definition 1-b&lt;/dd&gt;
&lt;dd&gt;definition 1-c&lt;/dd&gt;
&lt;dd&gt;definition 1-d&lt;/dd&gt;
&lt;dt id="term-2"&gt;term 2&lt;/dt&gt;
&lt;dd&gt;definition 2-a&lt;/dd&gt;
&lt;dd&gt;definition 2-b&lt;/dd&gt;
&lt;dd&gt;definition 2-c&lt;/dd&gt;
&lt;dt&gt;term 3&lt;/dt&gt;
&lt;dd&gt;definition 3-a&lt;/dd&gt;
&lt;dd&gt;definition 3-b&lt;/dd&gt;
&lt;/dl&gt;
</pre>
<p>If we begin at the second term, we can find the elements which come after it until a preceding <code>&lt;dt&gt;</code>.</p>
<pre>$('#term-2').prevUntil('dt').css('background-color', 'red');</pre>
<p>The result of this call is a red background behind definitions <code>1-a</code>, <code>1-b</code>, <code>1-c</code>, and <code>1-d</code>. </p>
]]></longdesc>
<example>
<desc><![CDATA[Find the siblings that precede &lt;dt id="term-2"&gt; up to the preceding &lt;dt&gt; and give them a red background color.]]></desc>
<code><![CDATA[
$("#term-2").prevUntil("dt")
.css("background-color", "red")
]]></code>
<html><![CDATA[<dl>
<dt>term 1</dt>
<dd>definition 1-a</dd>
<dd>definition 1-b</dd>
<dd>definition 1-c</dd>
<dd>definition 1-d</dd>
<dt id="term-2">term 2</dt>
<dd>definition 2-a</dd>
<dd>definition 2-b</dd>
<dd>definition 2-c</dd>
<dt>term 3</dt>
<dd>definition 3-a</dd>
<dd>definition 3-b</dd>
</dl>]]></html>
</example>
<category name="Tree Traversal"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="nextUntil" return="jQuery">
<signature>
<added>1.4</added>
<argument name="selector" optional="true" type="Selector">
<desc><![CDATA[A string containing a selector expression to indicate where to stop matching following sibling elements.]]></desc>
</argument>
</signature>
<desc><![CDATA[Get all following siblings of each element up to but not including the element matched by the selector.]]></desc>
<longdesc><![CDATA[
<p>Given a jQuery object that represents a set of DOM elements, the <code>.nextUntil()</code> method allows us to search through the successors of these elements in the DOM tree, stopping when it reaches an element matched by the method's argument. The new jQuery object that is returned contains all following siblings up to but not including the one matched by the <code>.nextUntil()</code> selector.</p>
<p>If the selector is not matched or is not supplied, all following siblings will be selected; in these cases it selects the same elements as the <code>.nextAll()</code> method does when no filter selector is provided.</p>
<p>Consider a page with a simple definition list as follows:</p>
<pre>
&lt;dl&gt;
&lt;dt&gt;term 1&lt;/dt&gt;
&lt;dd&gt;definition 1-a&lt;/dd&gt;
&lt;dd&gt;definition 1-b&lt;/dd&gt;
&lt;dd&gt;definition 1-c&lt;/dd&gt;
&lt;dd&gt;definition 1-d&lt;/dd&gt;
&lt;dt id="term-2"&gt;term 2&lt;/dt&gt;
&lt;dd&gt;definition 2-a&lt;/dd&gt;
&lt;dd&gt;definition 2-b&lt;/dd&gt;
&lt;dd&gt;definition 2-c&lt;/dd&gt;
&lt;dt&gt;term 3&lt;/dt&gt;
&lt;dd&gt;definition 3-a&lt;/dd&gt;
&lt;dd&gt;definition 3-b&lt;/dd&gt;
&lt;/dl&gt;
</pre>
<p>If we begin at the second term, we can find the elements which come after it until a following <code>&lt;dt&gt;</code>.</p>
<pre>$('#term-2').nextUntil('dt').css('background-color', 'red');</pre>
<p>The result of this call is a red background behind definitions <code>2-a</code>, <code>2-b</code>, and <code>2-c</code>. </p>
]]></longdesc>
<example>
<desc><![CDATA[Find the siblings that follow &lt;dt id="term-2"&gt; up to the next &lt;dt&gt; and give them a red background color.]]></desc>
<code><![CDATA[
$("#term-2").nextUntil("dt")
.css("background-color", "red")
]]></code>
<html><![CDATA[<dl>
<dt>term 1</dt>
<dd>definition 1-a</dd>
<dd>definition 1-b</dd>
<dd>definition 1-c</dd>
<dd>definition 1-d</dd>
<dt id="term-2">term 2</dt>
<dd>definition 2-a</dd>
<dd>definition 2-b</dd>
<dd>definition 2-c</dd>
<dt>term 3</dt>
<dd>definition 3-a</dd>
<dd>definition 3-b</dd>
</dl>]]></html>
</example>
<category name="Tree Traversal"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="event.isImmediatePropagationStopped" return="Boolean">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[ Returns whether event.stopImmediatePropagation() was ever called on this event object. ]]></desc>
<longdesc><![CDATA[
<p>This property was introduced in <a href="http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/events.html#Events-Event-isImmediatePropagationStopped">DOM level 3</a>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Checks whether event.stopImmediatePropagation() was called.]]></desc>
<code><![CDATA[$("p").click(function(event){
alert( event.isImmediatePropagationStopped() );
event.stopImmediatePropagation();
alert( event.isImmediatePropagationStopped() );
}); ]]></code>
<html><![CDATA[]]></html>
<results><![CDATA[]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="event.stopImmediatePropagation" return="">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[ Keeps the rest of the handlers from being executed.
]]></desc>
<longdesc><![CDATA[
<p>This method also stops the bubbling by implicitly calling <code>event.stopPropagation()</code>. Use <code>event.isImmediatePropagationStopped()</code> to know whether this method was ever called (on that event object).</p>
]]></longdesc>
<example>
<desc><![CDATA[Prevents other event handlers from being called.]]></desc>
<css><![CDATA[
p { height: 30px; width: 150px; background-color: #ccf; }
div {height: 30px; width: 150px; background-color: #cfc; }
]]></css>
<code><![CDATA[
$("p").click(function(event){
event.stopImmediatePropagation();
});
$("p").click(function(event){
// This function won't be executed
$(this).css("background-color", "#f00");
});
$("div").click(function(event) {
// This function will be executed
$(this).css("background-color", "#f00");
});]]></code>
<html><![CDATA[<p>paragraph</p>
<div>division</div>]]></html>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="event.isPropagationStopped" return="Boolean">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[ Returns whether <a href="/event.stopPropagation">event.stopPropagation()</a> was ever called on this event object. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[Checks whether event.stopPropagation() was called]]></desc>
<code><![CDATA[$("p").click(function(event){
alert( event.isPropagationStopped() );
event.stopPropagation();
alert( event.isPropagationStopped() );
}); ]]></code>
<html><![CDATA[]]></html>
<results><![CDATA[]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="event.stopPropagation" return="">
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[ This method prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event. ]]></desc>
<longdesc><![CDATA[
<p>We can use <code>.isPropagationStopped()</code> to determine if this method has been called by an event handler that was triggered by this event. </p>
<p>This method works for custom events triggered with <a href="/trigger">trigger()</a>, as well.</p>
<p>Note that this will not prevent other handlers <em>on the same element</em> from running. Use the method <a href="/event.isPropagationStopped">event.isPropagationStopped()</a> to know whether this method was ever called (on that event object). </p>
]]></longdesc>
<example>
<desc><![CDATA[Kill the bubbling on the click event.]]></desc>
<code><![CDATA[$("p").click(function(event){
event.stopPropagation();
// do something
}); ]]></code>
<html><![CDATA[]]></html>
<results><![CDATA[]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.0"/>
</entry>
<entry type="method" name="event.isDefaultPrevented" return="Boolean">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[Returns whether <a href="/event.preventDefault">event.preventDefault()</a> was ever called on this event object. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[Checks whether event.preventDefault() was called.]]></desc>
<code><![CDATA[$("a").click(function(event){
alert( event.isDefaultPrevented() ); // false
event.preventDefault();
alert( event.isDefaultPrevented() ); // true
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry name="event.preventDefault" type="method" return="undefined">
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[ If this method is called, the default action of the event will not be triggered. ]]></desc>
<longdesc><![CDATA[
<p>For example, clicked anchors will not take the browser to a new URL. We can use <code>event.isDefaultPrevented()</code> to determine if this method has been called by an event handler that was triggered by this event.</p>
]]></longdesc>
<example>
<desc><![CDATA[Cancel the default action (navigation) of the click.]]></desc>
<code><![CDATA[
$("a").click(function(event) {
event.preventDefault();
$('<div/>')
.append('default ' + event.type + ' prevented')
.appendTo('#log');
});
]]></code>
<html><![CDATA[
<a href="http://jquery.com">default click action is prevented</a>
<div id="log"></div>
]]></html>
</example>
<category name="Event Object"/>
<category name="Version 1.0"/>
</entry>
<entry type="property" name="event.timeStamp" return="Number">
<signature>
<added>1.2.6</added>
</signature>
<desc><![CDATA[ This attribute returns the number of milliseconds since January 1, 1970, when the event is triggered. ]]></desc>
<longdesc><![CDATA[ It can be useful for profiling the performance of certain jQuery functions. ]]></longdesc>
<example>
<desc><![CDATA[Alert the time since click handler last executed.]]></desc>
<code><![CDATA[var last;
$(document.body).click(function(event) {
if( last )
alert( "time since last event " + event.timeStamp - last );
last = event.timeStamp;
}); ]]></code>
<html><![CDATA[]]></html>
<results><![CDATA[]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.2.6"/>
</entry>
<entry type="property" name="event.result" return="Object">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[ This attribute contains the last value returned by an event handler that was triggered by this event, unless the value was <code>undefined</code>. ]]></desc>
<longdesc><![CDATA[ It can be useful for getting previous return values of custom events. ]]></longdesc>
<example>
<desc><![CDATA[Alert previous handler's return value]]></desc>
<code><![CDATA[$("p").click(function(event) {
return "hey"
});
$("p").click(function(event) {
alert( event.result );
}); ]]></code>
<html><![CDATA[]]></html>
<results><![CDATA["hey" ]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="property" name="event.which" return="String">
<signature>
<added>1.1.3</added>
</signature>
<desc><![CDATA[ For key or button events, this attribute indicates the specific button or key that was pressed. ]]></desc>
<longdesc><![CDATA[
<p><code>event.which</code> normalizes <code>event.keyCode</code> and <code>event.charCode</code>. It is recommended to watch <code>event.which</code> for keyboard key input. For more detail, read about <a href="https://developer.mozilla.org/en/DOM/event.charCode#Notes">event.charCode on the MDC</a>. </p>
]]></longdesc>
<example>
<desc><![CDATA[Log what key was depressed.]]></desc>
<code><![CDATA[$('#whichkey').bind('keydown',function(e){
$('#log').html(e.type + ': ' + e.which );
}); ]]></code>
<html><![CDATA[
<input id="whichkey" value="type something">
<div id="log"></div>]]></html>
<results><![CDATA["keydown" 74 ]]></results>
</example>
<category name="Event Object"/>
<category name="Version 1.1.3"/>
</entry>
<entry type="property" name="event.pageY" return="Number">
<signature>
<added>1.0.4</added>
</signature>
<desc><![CDATA[The mouse position relative to the top edge of the document. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[Show the mouse position relative to the left and top edges of the document (within this iframe).]]></desc>
<css>body {background-color: #eef; }
div { padding: 20px; }</css>
<html><![CDATA[<div id="log"></div>]]></html>
<code><![CDATA[$(document).bind('mousemove',function(e){
$("#log").text("e.pageX: " + e.pageX + ", e.pageY: " + e.pageY);
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.0.4"/>
</entry>
<entry type="property" name="event.pageX" return="Number">
<signature>
<added>1.0.4</added>
</signature>
<desc><![CDATA[The mouse position relative to the left edge of the document. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[Show the mouse position relative to the left and top edges of the document (within the iframe).]]></desc>
<css>body {background-color: #eef; }
div { padding: 20px; }</css>
<html><![CDATA[<div id="log"></div>]]></html>
<code><![CDATA[$(document).bind('mousemove',function(e){
$("#log").text("e.pageX: " + e.pageX + ", e.pageY: " + e.pageY);
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.0.4"/>
</entry>
<entry type="property" name="event.currentTarget" return="Element">
<signature>
<added>1.3</added>
</signature>
<desc><![CDATA[ The current DOM element within the event bubbling phase. ]]></desc>
<longdesc><![CDATA[
<p>This property will always be equal to the <code>this</code> of the function.</p>
]]></longdesc>
<example>
<desc><![CDATA[Alert that currentTarget matches the `this` keyword.]]></desc>
<code><![CDATA[$("p").click(function(event) {
alert( event.currentTarget === this ); // true
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="property" name="event.relatedTarget" return="Element">
<signature>
<added>1.1.4</added>
</signature>
<desc><![CDATA[ The other DOM element involved in the event, if any. ]]></desc>
<longdesc><![CDATA[
<p>For <code>mouseout</code>, indicates the element being entered; for <code>mousein</code>, indicates the element being exited. </p>
]]></longdesc>
<example>
<desc><![CDATA[On mouseout of anchors, alert the element type being entered.]]></desc>
<code><![CDATA[$("a").mouseout(function(event) {
alert(event.relatedTarget.nodeName); // "DIV"
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="property" name="event.data" return="Anything">
<signature>
<added>1.1</added>
</signature>
<desc><![CDATA[ Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[The description of the example.]]></desc>
<code><![CDATA[$("a").each(function(i) {
$(this).bind('click', {index:i}, function(e){
alert('my index is ' + e.data.index);
});
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.1"/>
</entry>
<entry type="property" name="event.target" return="Element">
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[ The DOM element that initiated the event. ]]></desc>
<longdesc><![CDATA[
<p>This can be the element that registered for the event or a child of it. It is often useful to compare <code>event.target</code> to <code>this</code> in order to determine if the event is being handled due to event bubbling. This property is very useful in event delegation, when events bubble.</p>
]]></longdesc>
<example>
<desc><![CDATA[Display the tag's name on click]]></desc>
<code><![CDATA[$("body").click(function(event) {
$("#log").html("clicked: " + event.target.nodeName);
}); ]]></code>
<css>
span, strong, p {
padding: 8px; display: block; border: 1px solid #999; }
</css>
<html><![CDATA[
<div id="log"></div>
<div>
<p>
<strong><span>click</span></strong>
</p>
</div>]]></html>
</example>
<example>
<desc><![CDATA[Implements a simple event delegation: The click handler is added to an unordered list, and the children of its li children are hidden. Clicking one of the li children toggles (see toggle()) their children.]]></desc>
<code><![CDATA[function handler(event) {
var $target = $(event.target);
if( $target.is("li") ) {
$target.children().toggle();
}
}
$("ul").click(handler).find("ul").hide();]]></code>
<html><![CDATA[
<ul>
<li>item 1
<ul>
<li>sub item 1-a</li>
<li>sub item 1-b</li>
</ul>
</li>
<li>item 2
<ul>
<li>sub item 2-a</li>
<li>sub item 2-b</li>
</ul>
</li>
</ul>]]></html>
</example>
<category name="Event Object"/>
<category name="Version 1.0"/>
</entry>
<entry type="property" name="event.type" return="String">
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[ Describes the nature of the event. ]]></desc>
<longdesc><![CDATA[ ]]></longdesc>
<example>
<desc><![CDATA[On all anchor clicks, alert the event type.]]></desc>
<code><![CDATA[$("a").click(function(event) {
alert(event.type); // "click"
}); ]]></code>
</example>
<category name="Event Object"/>
<category name="Version 1.0"/>
</entry>
<entry type="property" name="jQuery.fx.off" return="Boolean">
<desc><![CDATA[Globally disable all animations.]]></desc>
<signature>
<added>1.3</added>
</signature>
<longdesc><![CDATA[
<p>When this property is set to <code>true</code>, all animation methods will immediately set elements to their final state when called, rather than displaying an effect. This may be desirable for a couple reasons:</p>
<ul>
<li>jQuery is being used on a low-resource device.</li>
<li>Users are encountering accessibility problems with the animations (see the article <a href="http://www.jdeegan.phlegethon.org/turn_off_animation.html">Turn Off Animation</a> for more information).</li>
</ul>
<p>Animations can be turned back on by setting the property to <code>false</code>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Toggle animation on and off]]></desc>
<code><![CDATA[
var toggleFx = function() {
$.fx.off = !$.fx.off;
};
toggleFx();
$("button").click(toggleFx)
$("input").click(function(){
$("div").toggle("slow");
});
]]></code>
<css><![CDATA[
div { width:50px; height:30px; margin:5px; float:left;
background:green; }
]]></css>
<html><![CDATA[<p><input type="button" value="Run"/> <button>Toggle fx</button></p>
<div></div>]]></html>
</example>
<category name="Custom"/>
<category name="Properties of the Global jQuery Object"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="each" return="jQuery">
<signature>
<added>1.0</added>
<argument name="function(index, Element)" type="Function">
<desc><![CDATA[A function to execute for each matched element.]]></desc>
</argument>
</signature>
<desc><![CDATA[Iterate over a jQuery object, executing a function for each matched element. ]]></desc>
<longdesc><![CDATA[
<p>The <code>.each()</code> method is designed to make DOM looping constructs concise and less error-prone. When called it iterates over the DOM elements that are part of the jQuery object. Each time the callback runs, it is passed the current loop iteration, beginning from 0. More importantly, the callback is fired in the context of the current DOM element, so the keyword <code>this</code> refers to the element.</p>
<p>Suppose we had a simple unordered list on the page:</p>
<pre>&lt;ul&gt;
&lt;li&gt;foo&lt;/li&gt;
&lt;li&gt;bar&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can select the list items and iterate across them:</p>
<pre>$('li').each(function(index) {
alert(index + ': ' + $(this).text());
});
</pre>
<p>A message is thus alerted for each item in the list:</p>
<p>
<span class="output">0: foo</span>
<br/>
<span class="output">1: bar</span>
</p>
<p>We can stop the loop from within the callback function by returning <code>false</code>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Iterates over three divs and sets their color property.]]></desc>
<code><![CDATA[
$(document.body).click(function () {
$("div").each(function (i) {
if (this.style.color != "blue") {
this.style.color = "blue";
} else {
this.style.color = "";
}
});
});]]></code>
<css><![CDATA[
div { color:red; text-align:center; cursor:pointer;
font-weight:bolder; width:300px; }
]]></css>
<html><![CDATA[<div>Click here</div>
<div>to iterate through</div>
<div>these divs.</div>]]></html>
</example>
<example>
<desc><![CDATA[If you want to have the jQuery object instead of the regular DOM element, use the $(this) function, for example:]]></desc>
<code><![CDATA[
$("span").click(function () {
$("li").each(function(){
$(this).toggleClass("example");
});
});
]]></code>
<css><![CDATA[
ul { font-size:18px; margin:0; }
span { color:blue; text-decoration:underline; cursor:pointer; }
.example { font-style:italic; }
]]></css>
<html><![CDATA[To do list: <span>(click here to change)</span>
<ul>
<li>Eat</li>
<li>Sleep</li>
<li>Be merry</li>
</ul>]]></html>
</example>
<example>
<desc><![CDATA[You can use 'return' to break out of each() loops early.]]></desc>
<code><![CDATA[
$("button").click(function () {
$("div").each(function (index, domEle) {
// domEle == this
$(domEle).css("backgroundColor", "yellow");
if ($(this).is("#stop")) {
$("span").text("Stopped at div index #" + index);
return false;
}
});
});
]]></code>
<css><![CDATA[
div { width:40px; height:40px; margin:5px; float:left;
border:2px blue solid; text-align:center; }
span { color:red; }
]]></css>
<html><![CDATA[<button>Change colors</button>
<span></span>
<div></div>
<div></div>
<div></div>
<div></div>
<div id="stop">Stop here</div>
<div></div>
<div></div>
<div></div>]]></html>
</example>
<category name="Collection Manipulation"/>
<category name="Version 1.0"/>
</entry>
<entry type="method" name="jQuery.pushStack" return="jQuery">
<signature>
<added>1.0</added>
<argument name="elements" type="Array">
<desc><![CDATA[An array of elements to push onto the stack and make into a new jQuery object.]]></desc>
</argument>
</signature>
<signature>
<added>1.3</added>
<argument name="elements" type="Array">
<desc><![CDATA[An array of elements to push onto the stack and make into a new jQuery object.]]></desc>
</argument>
<argument name="name" type="String">
<desc><![CDATA[The name of a jQuery method that generated the array of elements.]]></desc>
</argument>
<argument name="arguments" type="Array">
<desc><![CDATA[The arguments that were passed in to the jQuery method (for serialization).]]></desc>
</argument>
</signature>
<desc><![CDATA[Add a collection of DOM elements onto the jQuery stack.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Add some elements onto the jQuery stack, then pop back off again.]]></desc>
<code><![CDATA[jQuery([])
.pushStack( document.getElementsByTagName("div") )
.remove()
.end();]]></code>
</example>
<category name="Plugin Authoring"/>
<category name="Version 1.0"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="jQuery.globalEval" return="">
<signature>
<added>1.0.4</added>
<argument name="code" type="String">
<desc><![CDATA[The JavaScript code to execute.]]></desc>
</argument>
</signature>
<desc><![CDATA[Execute some JavaScript code globally.]]></desc>
<longdesc><![CDATA[
<p>This method behaves differently from using a normal JavaScript <code>eval()</code> in that it's executed within the global context (which is important for loading external scripts dynamically).</p>
]]></longdesc>
<example>
<desc><![CDATA[Execute a script in the global context.]]></desc>
<code><![CDATA[function test(){
jQuery.globalEval("var newVar = true;")
}
test();
// newVar === true]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.0.4"/>
</entry>
<entry type="method" name="jQuery.isXMLDoc" return="Boolean">
<signature>
<added>1.1.4</added>
<argument name="node" type="Element">
<desc><![CDATA[The DOM node that will be checked to see if it's in an XML document.]]></desc>
</argument>
</signature>
<desc><![CDATA[Check to see if a DOM node is within an XML document (or is an XML document).]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Check an object to see if it's in an XML document.]]></desc>
<code><![CDATA[jQuery.isXMLDoc(document) // false
jQuery.isXMLDoc(document.body) // false]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="method" name="jQuery.removeData" return="jQuery">
<signature>
<added>1.2.3</added>
<argument name="element" type="Element">
<desc><![CDATA[A DOM element from which to remove data.]]></desc>
</argument>
<argument name="name" type="String" optional="true">
<desc><![CDATA[A string naming the piece of data to remove.]]></desc>
</argument>
</signature>
<desc><![CDATA[Remove a previously-stored piece of data.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method, you should probably use <code><a href="/removeData">.removeData()</a></code> instead.</p>
<p>The <code>jQuery.removeData()</code> method allows us to remove values that were previously set using <code><a href="/jQuery.data">jQuery.data()</a></code>. When called with the name of a key, <code>jQuery.removeData()</code> deletes that particular value; when called with no arguments, all values are removed.</p>
]]></longdesc>
<example>
<desc><![CDATA[Set a data store for 2 names then remove one of them.]]></desc>
<code><![CDATA[
var div = $("div")[0];
$("span:eq(0)").text("" + $("div").data("test1"));
jQuery.data(div, "test1", "VALUE-1");
jQuery.data(div, "test2", "VALUE-2");
$("span:eq(1)").text("" + jQuery.data(div, "test1"));
jQuery.removeData(div, "test1");
$("span:eq(2)").text("" + jQuery.data(div, "test1"));
$("span:eq(3)").text("" + jQuery.data(div, "test2"));]]></code>
<css><![CDATA[
div { margin:2px; color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>value1 before creation: <span></span></div>
<div>value1 after creation: <span></span></div>
<div>value1 after removal: <span></span></div>
<div>value2 after removal: <span></span></div>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2.3"/>
</entry>
<entry type="method" name="jQuery.data" return="jQuery">
<signature>
<added>1.2.3</added>
<argument name="element" type="Element">
<desc><![CDATA[The DOM element to associate with the data.]]></desc>
</argument>
<argument name="key" type="String">
<desc><![CDATA[A string naming the piece of data to set.]]></desc>
</argument>
<argument name="value" type="Object">
<desc><![CDATA[The new data value.]]></desc>
</argument>
</signature>
<desc><![CDATA[Store arbitrary data associated with the specified element.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method; you should probably use <code><a href="/data">.data()</a></code> instead.</p>
<p>The <code>jQuery.data()</code> method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can set several distinct values for a single element and retrieve them later:</p>
<pre>jQuery.data(document.body, 'foo', 52);
jQuery.data(document.body, 'bar', 'test');</pre>
]]></longdesc>
<example>
<desc><![CDATA[Store then retrieve a value from the div element.]]></desc>
<code><![CDATA[var div = $("div")[0];
jQuery.data(div, "test", { first: 16, last: "pizza!" });
$("span:first").text(jQuery.data(div, "test").first);
$("span:last").text(jQuery.data(div, "test").last);]]></code>
<css><![CDATA[
div { color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>
The values stored were
<span></span>
and
<span></span>
</div>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.data" return="Object">
<signature>
<added>1.2.3</added>
<argument name="element" type="Element">
<desc><![CDATA[The DOM element to query for the data.]]></desc>
</argument>
<argument name="key" type="String">
<desc><![CDATA[Name of the data stored.]]></desc>
</argument>
</signature>
<signature>
<added>1.4</added>
<argument name="element" type="Element">
<desc><![CDATA[The DOM element to query for the data.]]></desc>
</argument>
</signature>
<desc><![CDATA[Returns value at named data store for the element, as set by <code>jQuery.data(element, name, value)</code>, or the full data store for the element.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method; you should probably use <code><a href="/data">.data()</a></code> instead.</p>
<p>The <code>jQuery.data()</code> method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:</p>
<pre>alert(jQuery.data( document.body, 'foo' );
alert(jQuery.data( document.body ));</pre>
<p>The above lines alert the data values that were set on the <code>body</code> element. If nothing was set on that element, an empty string is returned.</p>
<p>Calling <code>jQuery.data(element)</code> retrieves all of the element's associated values as a JavaScript object. Note that jQuery itself uses this method to store data for internal use, such as event handlers, so do not assume that it contains only data that your own code has stored.</p>
]]></longdesc>
<example>
<desc><![CDATA[Get the data named "blah" stored at for an element.]]></desc>
<code><![CDATA[
$("button").click(function(e) {
var value, div = $("div")[0];
switch ($("button").index(this)) {
case 0 :
value = jQuery.data(div, "blah");
break;
case 1 :
jQuery.data(div, "blah", "hello");
value = "Stored!";
break;
case 2 :
jQuery.data(div, "blah", 86);
value = "Stored!";
break;
case 3 :
jQuery.removeData(div, "blah");
value = "Removed!";
break;
}
$("span").text("" + value);
});
]]></code>
<css><![CDATA[
div { margin:5px; background:yellow; }
button { margin:5px; font-size:14px; }
p { margin:5px; color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>A div</div>
<button>Get "blah" from the div</button>
<button>Set "blah" to "hello"</button>
<button>Set "blah" to 86</button>
<button>Remove "blah" from the div</button>
<p>The "blah" value of this div is <span>?</span></p>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.dequeue" return="jQuery">
<signature>
<added>1.3</added>
<argument name="element" type="Element">
<desc><![CDATA[A DOM element from which to remove and execute a queued function.]]></desc>
</argument>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
</signature>
<desc><![CDATA[Execute the next function on the queue for the matched element.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method, you should probably use <code><a href="/dequeue">.dequeue()</a></code> instead.</p>
<p>When <code>jQuery.dequeue()</code> is called, the next function on the queue is removed from the queue, and then executed. This function should in turn (directly or indirectly) cause <code>jQuery.dequeue()</code> to be called, so that the sequence can continue.</p>
]]></longdesc>
<example>
<desc><![CDATA[Use dequeue to end a custom queue function which allows the queue to keep going.]]></desc>
<code><![CDATA[$("button").click(function () {
$("div").animate({left:'+=200px'}, 2000);
$("div").animate({top:'0px'}, 600);
$("div").queue(function () {
$(this).toggleClass("red");
$.dequeue( this );
});
$("div").animate({left:'10px', top:'30px'}, 700);
});]]></code>
<css><![CDATA[div { margin:3px; width:50px; position:absolute;
height:50px; left:10px; top:30px;
background-color:yellow; }
div.red { background-color:red; } ]]></css>
<html><![CDATA[<button>Start</button> <div></div>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="jQuery.queue" return="Array">
<signature>
<added>1.3</added>
<argument name="element" type="Element">
<desc><![CDATA[A DOM element to inspect for an attached queue.]]></desc>
</argument>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
</signature>
<desc><![CDATA[Show the queue of functions to be executed on the matched element.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method, you should probably use <code><a href="/queue">.queue()</a></code> instead.</p>
]]></longdesc>
<example>
<desc><![CDATA[Show the length of the queue.]]></desc>
<code><![CDATA[$("#show").click(function () {
var n = jQuery.queue( $("div")[0], "fx" );
$("span").text("Queue length is: " + n.length);
});
function runIt() {
$("div").show("slow");
$("div").animate({left:'+=200'},2000);
$("div").slideToggle(1000);
$("div").slideToggle("fast");
$("div").animate({left:'-=200'},1500);
$("div").hide("slow");
$("div").show(1200);
$("div").slideUp("normal", runIt);
}
runIt();]]></code>
<css><![CDATA[div { margin:3px; width:40px; height:40px;
position:absolute; left:0px; top:30px;
background:green; display:none; }
div.newcolor { background:blue; }
span { color:red; } ]]></css>
<html><![CDATA[<button id="show">Show Length of Queue</button>
<span></span>
<div></div>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="jQuery.queue" return="jQuery">
<signature>
<added>1.3</added>
<argument name="element" type="Element">
<desc><![CDATA[A DOM element where the array of queued functions is attached.]]></desc>
</argument>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
<argument name="newQueue" type="Array">
<desc><![CDATA[An array of functions to replace the current queue contents.]]></desc>
</argument>
</signature>
<signature>
<added>1.3</added>
<argument name="element" type="Element">
<desc><![CDATA[A DOM element on which to add a queued function.]]></desc>
</argument>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
<argument name="callback()" type="Function">
<desc><![CDATA[The new function to add to the queue.]]></desc>
</argument>
</signature>
<desc><![CDATA[Manipulate the queue of functions to be executed on the matched element.]]></desc>
<longdesc><![CDATA[
<p><strong>Note:</strong> This is a low-level method, you should probably use <code><a href="/queue">.queue()</a></code> instead.</p>
<p>Every element can have one or more queues of functions attached to it by jQuery. In most applications, only one queue (called <code>fx</code>) is used. Queues allow a sequence of actions to be called on an element asynchronously, without halting program execution.</p>
<p>The <code>jQuery.queue()</code> method allows us to directly manipulate this queue of functions. Calling <code>jQuery.queue()</code> with a callback is particularly useful; it allows us to place a new function at the end of the queue.</p>
<p>Note that when adding a function with <code>jQuery.queue()</code>, we should ensure that <code>jQuery.dequeue()</code> is eventually called so that the next function in line executes.</p>
]]></longdesc>
<example>
<desc><![CDATA[Queue a custom function.]]></desc>
<code><![CDATA[$(document.body).click(function () {
$("div").show("slow");
$("div").animate({left:'+=200'},2000);
jQuery.queue( $("div")[0], function () {
$(this).addClass("newcolor");
jQuery.dequeue( this );
});
$("div").animate({left:'-=200'},500);
jQuery.queue( $("div")[0], function () {
$(this).removeClass("newcolor");
jQuery.dequeue( this );
});
$("div").slideUp();
});]]></code>
<css><![CDATA[
div { margin:3px; width:40px; height:40px;
position:absolute; left:0px; top:30px;
background:green; display:none; }
div.newcolor { background:blue; }
]]></css>
<html><![CDATA[Click here...
<div></div>]]></html>
</example>
<example>
<desc><![CDATA[Set a queue array to delete the queue.]]></desc>
<code><![CDATA[$("#start").click(function () {
$("div").show("slow");
$("div").animate({left:'+=200'},5000);
jQuery.queue( $("div")[0], function () {
$(this).addClass("newcolor");
jQuery.dequeue( this );
});
$("div").animate({left:'-=200'},1500);
jQuery.queue( $("div")[0], function () {
$(this).removeClass("newcolor");
jQuery.dequeue( this );
});
$("div").slideUp();
});
$("#stop").click(function () {
jQuery.queue( $("div")[0], "fx", [] );
$("div").stop();
});]]></code>
<css><![CDATA[
div { margin:3px; width:40px; height:40px;
position:absolute; left:0px; top:30px;
background:green; display:none; }
div.newcolor { background:blue; }
]]></css>
<html><![CDATA[<button id="start">Start</button>
<button id="stop">Stop</button>
<div></div>]]></html>
</example>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.3"/>
</entry>
<entry type="method" name="clearQueue" return="jQuery">
<signature>
<added>1.4</added>
<argument name="queueName" optional="true" type="String">
<desc><![CDATA[A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.]]></desc>
</argument>
</signature>
<desc><![CDATA[Remove from the queue all items that have not yet been run.]]></desc>
<longdesc><![CDATA[
<p>When the <code>.clearQueue()</code> method is called, all functions on the queue that have not been executed are removed from the queue. When used without an argument, <code>.clearQueue()</code> removes the remaining functions from <code>fx</code>, the standard effects queue. In this way it is similar to <code>.stop(true)</code>. However, while the <code>.stop()</code> method is meant to be used only with animations, <code>.clearQueue()</code> can also be used to remove any function that has been added to a generic jQuery queue with the <code>.queue()</code> method. </p>
]]></longdesc>
<example>
<desc><![CDATA[Empty the queue.]]></desc>
<code><![CDATA[$("#start").click(function () {
$("div").show("slow");
$("div").animate({left:'+=200'},5000);
$("div").queue(function () {
$(this).addClass("newcolor");
$(this).dequeue();
});
$("div").animate({left:'-=200'},1500);
$("div").queue(function () {
$(this).removeClass("newcolor");
$(this).dequeue();
});
$("div").slideUp();
});
$("#stop").click(function () {
$("div").clearQueue();
$("div").stop();
});]]></code>
<css><![CDATA[
div { margin:3px; width:40px; height:40px;
position:absolute; left:0px; top:30px;
background:green; display:none; }
div.newcolor { background:blue; }
]]></css>
<html><![CDATA[<button id="start">Start</button>
<button id="stop">Stop</button>
<div></div>]]></html>
</example>
<category name="Custom"/>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="toArray" return="Array">
<signature>
<added>1.4</added>
</signature>
<desc><![CDATA[Retrieve all the DOM elements contained in the jQuery set, as an array.]]></desc>
<longdesc><![CDATA[
<p><code>.toArray()</code> returns all of the elements in the jQuery set:</p>
<pre>alert($('li').toArray());</pre>
<p>All of the matched DOM nodes are returned by this call, contained in a standard array:</p>
<p>
<span class="result">[&lt;li id="foo"&gt;, &lt;li id="bar"&gt;]</span>
</p>
]]></longdesc>
<example>
<desc><![CDATA[Selects all divs in the document and returns the DOM Elements as an Array, then uses the built-in reverse-method to reverse that array.]]></desc>
<code><![CDATA[
function disp(divs) {
var a = [];
for (var i = 0; i < divs.length; i++) {
a.push(divs[i].innerHTML);
}
$("span").text(a.join(" "));
}
disp( $("div").toArray().reverse() );
]]></code>
<css><![CDATA[
span { color:red; }
]]></css>
<html><![CDATA[Reversed - <span></span>
<div>One</div>
<div>Two</div>
<div>Three</div>]]></html>
</example>
<category name="DOM Element Methods"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.isEmptyObject" return="Boolean">
<signature>
<added>1.4</added>
<argument name="object" type="Object">
<desc><![CDATA[The object that will be checked to see if it's empty.]]></desc>
</argument>
</signature>
<desc><![CDATA[Check to see if an object is empty (contains no properties).]]></desc>
<longdesc><![CDATA[
<p>As of jQuery 1.4 this method checks both properties on the object itself and properties inherited from prototypes (in that it doesn't use hasOwnProperty).</p>
]]></longdesc>
<example>
<desc><![CDATA[Check an object to see if it's empty.]]></desc>
<code><![CDATA[jQuery.isEmptyObject({}) // true
jQuery.isEmptyObject({ foo: "bar" }) // false]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="jQuery.isPlainObject" return="Boolean">
<signature>
<added>1.4</added>
<argument name="object" type="Object">
<desc><![CDATA[The object that will be checked to see if it's a plain object.]]></desc>
</argument>
</signature>
<desc><![CDATA[Check to see if an object is a plain object (created using "{}" or "new Object").]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Check an object to see if it's a plain object.]]></desc>
<code><![CDATA[jQuery.isPlainObject({}) // true
jQuery.isPlainObject("test") // false]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="keydown" return="jQuery">
<signature>
<added>1.0</added>
<argument name="handler(eventObject)" type="Function">
<desc><![CDATA[A function to execute each time the event is triggered.]]></desc>
</argument>
</signature>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.]]></desc>
<longdesc><![CDATA[
<p>This method is a shortcut for <code>.bind('keydown', handler)</code> in the first variation, and <code>.trigger('keydown')</code> in the second.</p>
<p>The <code>keydown</code> event is sent to an element when the user first presses a key on the keyboard. It can be attached to any element, but the event is only sent to the element that has the focus. Focusable elements can vary between browsers, but form elements can always get focus so are reasonable candidates for this event type.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;form&gt;
&lt;input id="target" type="text" value="Hello there" /&gt;
&lt;/form&gt;
&lt;div id="other"&gt;
Trigger the handler
&lt;/div&gt;</pre>
<p>The event handler can be bound to the input field:</p>
<pre>$('#target').keydown(function() {
alert('Handler for .keydown() called.');
});</pre>
<p>Now when the insertion point is inside the field and a key is pressed, the alert is displayed:</p>
<p>
<span class="output">Handler for .keydown() called.</span>
</p>
<p>We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
$('#target').keydown();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>If key presses anywhere need to be caught (for example, to implement global shortcut keys on a page), it is useful to attach this behavior to the <code>document</code> object. Because of event bubbling, all key presses will make their way up the DOM to the <code>document</code> object unless explicitly stopped.</p>
<p>To determine which key was pressed, we can examine the event object that is passed to the handler function. While browsers use differing properties to store this information, jQuery normalizes the <code>.which</code> property so we can reliably use it to retrieve the key code. This code corresponds to a key on the keyboard, including codes for special keys such as arrows. For catching actual text entry, <code>.keypress()</code> may be a better choice.</p>
]]></longdesc>
<example>
<desc><![CDATA[Show the event object for the keydown handler when a key is pressed in the input.]]></desc>
<code><![CDATA[
var xTriggered = 0;
$('#target').keydown(function(event) {
if (event.keyCode == '13') {
event.preventDefault();
}
xTriggered++;
var msg = 'Handler for .keydown() called ' + xTriggered + ' time(s).';
$.print(msg, 'html');
$.print(event);
});
$('#other').click(function() {
$('#target').keydown();
});]]></code>
<css><![CDATA[
fieldset { margin-bottom: 1em; }
input { display: block; margin-bottom: .25em; }
#print-output {
width: 100%;
}
.print-output-line {
white-space: pre;
padding: 5px;
font-family: monaco, monospace;
font-size: .7em;
}
]]></css>
<height>460</height>
<html><![CDATA[<form>
<fieldset>
<label for="target">Type Something:</label>
<input id="target" type="text" />
</fieldset>
</form>
<button id="other">
Trigger the handler
</button>
<script type="text/javascript" src="/scripts/events.js"></script>]]></html>
</example>
<category name="Keyboard Events"/>
<category name="Version 1.0"/>
</entry>
<entry type="method" name="index" return="Number">
<signature>
<added>1.4</added>
</signature>
<signature>
<added>1.4</added>
<argument name="selector" type="Selector">
<desc><![CDATA[A selector representing a jQuery collection in which to look for an element.]]></desc>
</argument>
</signature>
<signature>
<added>1.0</added>
<argument name="element" type="Element, jQuery">
<desc><![CDATA[The DOM element or first element within the jQuery object to look for.]]></desc>
</argument>
</signature>
<desc><![CDATA[Search for a given element from among the matched elements.]]></desc>
<longdesc><![CDATA[
<h4>Return Values</h4>
<p>If no argument is passed to the <code>.index()</code> method, the return value is an integer indicating the position of the first element within the jQuery object relative to its sibling elements.</p>
<p>If <code>.index()</code> is called on a collection of elements and a DOM element or jQuery object is passed in, <code>.index()</code> returns an integer indicating the position of the passed element relative to the original collection.</p>
<p>If a selector string is passed as an argument, <code>.index()</code> returns an integer indicating the position of the original element relative to the elements matched by the selector. If the element is not found, <code>.index()</code> will return -1.</p>
<h4>Detail</h4>
<p>The complementary operation to <code>.get()</code>, which accepts an index and returns a DOM node, <code>.index()</code> can take a DOM node and returns an index. Suppose we have a simple unordered list on the page:</p>
<pre>
&lt;ul&gt;
&lt;li id="foo"&gt;foo&lt;/li&gt;
&lt;li id="bar"&gt;bar&lt;/li&gt;
&lt;li id="baz"&gt;baz&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we retrieve one of the three list items (for example, through a DOM function or as the context to an event handler), <code>.index()</code> can search for this list item within the set of matched elements:</p>
<pre>
var listItem = document.getElementById('bar');
alert('Index: ' + $('li').index(listItem));
We get back the zero-based position of the list item:
</pre>
<p>
<span class="output">Index: 1</span>
</p>
<p>Similarly, if we retrieve a jQuery object consisting of one of the three list items, <code>.index()</code> will search for that list item:</p>
<pre>
var listItem = $('#bar');
alert('Index: ' + $('li').index(listItem));
</pre>
<p>We get back the zero-based position of the list item:</p>
<p>
<span class="output">Index: 1</span>
</p>
<p>Note that if the jQuery collection used as the <code>.index()</code> method's argument contains more than one element, the first element within the matched set of elements will be used.</p>
<pre>
var listItems = $('li:gt(0)');
alert('Index: ' + $('li').index(listItems));
</pre>
<p>We get back the zero-based position of the first list item within the matched set:</p>
<p>
<span class="output">Index: 1</span>
</p>
<p>If we use a string as the <code>.index()</code> method's argument, it is interpreted as a jQuery selector string. The first element among the object's matched elements which also matches this selector is located.</p>
<pre>
var listItem = $('#bar');
alert('Index: ' + listItem.index('li'));
</pre>
<p>We get back the zero-based position of the list item:</p>
<p>
<span class="output">Index: 1</span>
</p>
<p>If we omit the argument, <code>.index()</code> will return the position of the first element within the set of matched elements in relation to its siblings:</p>
<pre>alert('Index: ' + $('#bar').index();</pre>
<p>Again, we get back the zero-based position of the list item:</p>
<p>
<span class="output">Index: 1</span>
</p>
]]></longdesc>
<example>
<desc><![CDATA[On click, returns the index (based zero) of that div in the page.]]></desc>
<code><![CDATA[
$("div").click(function () {
// this is the dom element clicked
var index = $("div").index(this);
$("span").text("That was div index #" + index);
});
]]></code>
<css><![CDATA[
div { background:yellow; margin:5px; }
span { color:red; }
]]></css>
<html><![CDATA[<span>Click a div!</span>
<div>First div</div>
<div>Second div</div>
<div>Third div</div>]]></html>
</example>
<example>
<desc><![CDATA[Returns the index for the element with ID bar.]]></desc>
<css>div { font-weight: bold; color: #090; }</css>
<code><![CDATA[var listItem = $('#bar');
$('div').html( 'Index: ' + $('li').index(listItem) );]]></code>
<html><![CDATA[<ul>
<li id="foo">foo</li>
<li id="bar">bar</li>
<li id="baz">baz</li>
</ul>
<div></div>]]></html>
</example>
<example>
<desc><![CDATA[Returns the index for the first item in the jQuery collection.]]></desc>
<css>div { font-weight: bold; color: #090; }</css>
<code><![CDATA[var listItems = $('li:gt(0)');
$('div').html( 'Index: ' + $('li').index(listItems) );
]]></code>
<html><![CDATA[<ul>
<li id="foo">foo</li>
<li id="bar">bar</li>
<li id="baz">baz</li>
</ul>
<div></div>]]></html>
</example>
<example>
<desc><![CDATA[Returns the index for the element with ID bar in relation to all &lt;li&gt; elements.]]></desc>
<css>div { font-weight: bold; color: #090; }</css>
<code><![CDATA[$('div').html('Index: ' + $('#bar').index('li') );]]></code>
<html><![CDATA[<ul>
<li id="foo">foo</li>
<li id="bar">bar</li>
<li id="baz">baz</li>
</ul>
<div></div>]]></html>
</example>
<example>
<desc><![CDATA[Returns the index for the element with ID bar in relation to its siblings.]]></desc>
<css>div { font-weight: bold; color: #090; }</css>
<code><![CDATA[var barIndex = $('#bar').index();
$('div').html( 'Index: ' + barIndex );]]></code>
<html><![CDATA[<ul>
<li id="foo">foo</li>
<li id="bar">bar</li>
<li id="baz">baz</li>
</ul>
<div></div>]]></html>
</example>
<example>
<desc><![CDATA[Returns -1, as there is no element with ID foobar.]]></desc>
<css>div { font-weight: bold; color: #090; }</css>
<code><![CDATA[var foobar = $("li").index( $('#foobar') );
$('div').html('Index: ' + foobar);]]></code>
<html><![CDATA[<ul>
<li id="foo">foo</li>
<li id="bar">bar</li>
<li id="baz">baz</li>
</ul>
<div></div>]]></html>
</example>
<category name="DOM Element Methods"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="removeData" return="jQuery">
<signature>
<added>1.2.3</added>
<argument name="name" type="String" optional="true">
<desc><![CDATA[A string naming the piece of data to delete.]]></desc>
</argument>
</signature>
<desc><![CDATA[Remove a previously-stored piece of data.]]></desc>
<longdesc><![CDATA[
<p>The <code>.removeData()</code> method allows us to remove values that were previously set using <code>.data()</code>. When called with the name of a key, <code>.removeData()</code> deletes that particular value; when called with no arguments, all values are removed.</p>
]]></longdesc>
<example>
<desc><![CDATA[Set a data store for 2 names then remove one of them.]]></desc>
<code><![CDATA[
$("span:eq(0)").text("" + $("div").data("test1"));
$("div").data("test1", "VALUE-1");
$("div").data("test2", "VALUE-2");
$("span:eq(1)").text("" + $("div").data("test1"));
$("div").removeData("test1");
$("span:eq(2)").text("" + $("div").data("test1"));
$("span:eq(3)").text("" + $("div").data("test2"));
]]></code>
<css><![CDATA[
div { margin:2px; color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>value1 before creation: <span></span></div>
<div>value1 after creation: <span></span></div>
<div>value1 after removal: <span></span></div>
<div>value2 after removal: <span></span></div>]]></html>
</example>
<category name="Data Storage"/>
<category name="Version 1.2.3"/>
</entry>
<entry type="method" name="data" return="jQuery">
<signature>
<added>1.2.3</added>
<argument name="key" type="String">
<desc><![CDATA[A string naming the piece of data to set.]]></desc>
</argument>
<argument name="value" type="Object">
<desc><![CDATA[The new data value; it can be any Javascript type including Array or Object.]]></desc>
</argument>
</signature>
<signature>
<added>1.4</added>
<argument name="obj" type="Object">
<desc><![CDATA[An object of key-value pairs of data to set.]]></desc>
</argument>
</signature>
<desc><![CDATA[Store arbitrary data associated with the matched elements.]]></desc>
<longdesc><![CDATA[
<p>The <code>.data()</code> method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks.</p>
<p> We can set several distinct values for a single element and retrieve them later:</p>
<pre>
$('body').data('foo', 52);
$('body').data('bar', { myType: 'test', count: 40 });
$('body').data('foo'); // 52
$('body').data(); // {foo: 52, bar: { myType: 'test', count: 40 }}
</pre>
<p>Note: Setting an element's data object with <code>.data(obj)</code> replaces all data previously stored with that element, including events that have been bound to the element. </p>
<pre>
$('body').data('foo', 52);
$('body').data({one: 1, two: 2});
$('body').data('foo'); // undefined
$('body').data(); // {one: 1, two: 2}
</pre>
]]></longdesc>
<example>
<desc><![CDATA[Store then retrieve a value from the div element.]]></desc>
<code><![CDATA[
$("div").data("test", { first: 16, last: "pizza!" });
$("span:first").text($("div").data("test").first);
$("span:last").text($("div").data("test").last);
]]></code>
<css><![CDATA[
div { color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>
The values stored were
<span></span>
and
<span></span>
</div>]]></html>
</example>
<category name="Data Storage"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="data" return="Object">
<signature>
<added>1.2.3</added>
<argument name="key" type="String">
<desc><![CDATA[Name of the data stored.]]></desc>
</argument>
</signature>
<signature>
<added>1.4</added>
</signature>
<desc><![CDATA[Returns value at named data store for the element, as set by data(name, value).]]></desc>
<longdesc><![CDATA[
<p>The <code>.data()</code> method allows us to attach data of any type to DOM elements in a way that is safe from circular references and therefore from memory leaks. We can retrieve several distinct values for a single element one at a time, or as a set:</p>
<pre>
alert($('body').data('foo'));
alert($('body').data());
</pre>
<p>The above lines alert the data values that were set on the <code>body</code> element. If nothing was set on that element, an empty string is returned:</p>
<p>Calling <code>.data()</code> with no parameters retrieves all of the values as a JavaScript object.</p>
]]></longdesc>
<example>
<desc><![CDATA[Get the data named "blah" stored at for an element.]]></desc>
<code><![CDATA[
$("button").click(function(e) {
var value;
switch ($("button").index(this)) {
case 0 :
value = $("div").data("blah");
break;
case 1 :
$("div").data("blah", "hello");
value = "Stored!";
break;
case 2 :
$("div").data("blah", 86);
value = "Stored!";
break;
case 3 :
$("div").removeData("blah");
value = "Removed!";
break;
}
$("span").text("" + value);
});
]]></code>
<css><![CDATA[
div { margin:5px; background:yellow; }
button { margin:5px; font-size:14px; }
p { margin:5px; color:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<div>A div</div>
<button>Get "blah" from the div</button>
<button>Set "blah" to "hello"</button>
<button>Set "blah" to 86</button>
<button>Remove "blah" from the div</button>
<p>The "blah" value of this div is <span>?</span></p>]]></html>
</example>
<category name="Data Storage"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
</entry>
<entry type="method" name="get" return="Element, Array">
<signature>
<added>1.0</added>
<argument name="index" type="Number" optional="true">
<desc><![CDATA[A zero-based integer indicating which element to retrieve.]]></desc>
</argument>
</signature>
<desc><![CDATA[Retrieve the DOM elements matched by the jQuery object.]]></desc>
<longdesc><![CDATA[
<p>The <code>.get()</code> method grants us access to the DOM nodes underlying each jQuery object. Suppose we had a simple unordered list on the page:</p>
<pre>
&lt;ul&gt;
&lt;li id="foo"&gt;foo&lt;/li&gt;
&lt;li id="bar"&gt;bar&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>Without a parameter, <code>.get()</code> returns all of the elements:</p>
<pre>alert($('li').get());</pre>
<p>All of the matched DOM nodes are returned by this call, contained in a standard array:</p>
<p>
<span class="result">[&lt;li id="foo"&gt;, &lt;li id="bar"&gt;]</span>
</p>
<p>With an index specified, .get() will retrieve a single element:</p>
<pre>($('li').get(0));</pre>
<p>Since the index is zero-based, the first list item is returned:</p>
<p>
<span class="output">&lt;li id="foo"&gt;</span>
</p>
<p>Each jQuery object also masquerades as an array, so we can use the array dereferencing operator to get at the list item instead:</p>
<pre>alert($('li')[0]);</pre>
<p>However, this syntax lacks some of the additional capabilities of .get(), such as specifying a negative index:</p>
<pre>alert($('li').get(-1));</pre>
<p>A negative index is counted from the end of the matched set, so this example will return the last item in the list:</p>
<p>
<span class="output">&lt;li id="bar"&gt;</span>
</p>
]]></longdesc>
<example>
<desc><![CDATA[Selects all divs in the document and returns the DOM Elements as an Array, then uses the built-in reverse-method to reverse that array.]]></desc>
<code><![CDATA[
function disp(divs) {
var a = [];
for (var i = 0; i < divs.length; i++) {
a.push(divs[i].innerHTML);
}
$("span").text(a.join(" "));
}
disp( $("div").get().reverse() );
]]></code>
<css><![CDATA[
span { color:red; }
]]></css>
<html><![CDATA[Reversed - <span></span>
<div>One</div>
<div>Two</div>
<div>Three</div>]]></html>
</example>
<example>
<desc><![CDATA[Gives the tag name of the element clicked on.]]></desc>
<code><![CDATA[
$("*", document.body).click(function (e) {
e.stopPropagation();
var domEl = $(this).get(0);
$("span:first").text("Clicked on - " + domEl.tagName);
});
]]></code>
<css><![CDATA[
span { color:red; }
div { background:yellow; }
]]></css>
<html><![CDATA[<span>&nbsp;</span>
<p>In this paragraph is an <span>important</span> section</p>
<div><input type="text" /></div>]]></html>
</example>
<category name="DOM Element Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type="method" name="size" return="Number">
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Return the number of DOM elements matched by the jQuery object.]]></desc>
<longdesc><![CDATA[Suppose we had a simple unordered list on the page:
<pre>
&lt;ul&gt;
&lt;li&gt;foo&lt;/li&gt;
&lt;li&gt;bar&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can determine the number of list items by calling <code>.size()</code>:</p>
<pre>alert('Size: ' + $('li').size());</pre>
<p>This will alert the count of items:</p>
<p><span class="output">Size: 2</span></p>
<p>The <a href="/length/">.length</a> property is a slightly faster way to get this information.</p>
]]></longdesc>
<example>
<desc><![CDATA[Count the divs. Click to add more.]]></desc>
<code><![CDATA[$(document.body).click(function () { $(document.body).append($("<div>"));
var n = $("div").size();
$("span").text("There are " + n + " divs." + "Click to add more.");}).click(); // trigger the click to start]]></code>
<css><![CDATA[body { cursor:pointer; }
div { width:50px; height:30px; margin:5px; float:left; background:blue; }
span { color:red; }
]]></css>
<html><![CDATA[<span></span>
<div></div>]]></html>
</example>
<category name="DOM Element Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type="method" name="jQuery.noConflict" return="Object">
<signature>
<added>1.0</added>
<argument name="removeAll" type="Boolean" optional="true">
<desc><![CDATA[A Boolean indicating whether to remove all jQuery variables from the global scope (including jQuery itself).]]></desc>
</argument>
</signature>
<desc><![CDATA[Relinquish jQuery's control of the <code>$</code> variable.]]></desc>
<longdesc><![CDATA[
<p>Many JavaScript libraries use <code> $</code> as a function or variable name, just as jQuery does. In jQuery's case, <code> $</code> is just an alias for <code>jQuery</code>, so all functionality is available without using <code> $</code>. If we need to use another JavaScript library alongside jQuery, we can return control of <code> $</code> back to the other library with a call to <code>$.noConflict()</code>:</p>
<pre>
&lt;script type="text/javascript" src="other_lib.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jquery.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript"&gt;
$.noConflict();
// Code that uses other library's $ can follow here.
&lt;/script&gt;
</pre>
<p>This technique is especially effective in conjunction with the .ready() method's ability to alias the jQuery object, as within callback passed to .ready() we can use $ if we wish without fear of conflicts later:</p>
<pre>
&lt;script type="text/javascript" src="other_lib.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jquery.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript"&gt;
$.noConflict();
jQuery(document).ready(function($) {
// Code that uses jQuery's $ can follow here.
});
// Code that uses other library's $ can follow here.
&lt;/script&gt;
</pre>
<p>If necessary, we can free up the <code> jQuery</code> name as well by passing <code>true</code> as an argument to the method. This is rarely necessary, and if we must do this (for example, if we need to use multiple versions of the <code>jQuery</code> library on the same page), we need to consider that most plug-ins rely on the presence of the jQuery variable and may not operate correctly in this situation.</p>
]]></longdesc>
<example>
<desc><![CDATA[Maps the original object that was referenced by $ back to $.]]></desc>
<code><![CDATA[jQuery.noConflict();
// Do something with jQuery
jQuery("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';]]></code>
</example>
<example>
<desc><![CDATA[Reverts the $ alias and then creates and executes a function to provide the $ as a jQuery alias inside the functions scope. Inside the function the original $ object is not available. This works well for most plugins that don't rely on any other library.
]]></desc>
<code><![CDATA[jQuery.noConflict();
(function($) {
$(function() {
// more code using $ as alias to jQuery
});
})(jQuery);
// other code using $ as an alias to the other library]]></code>
</example>
<example>
<desc><![CDATA[You can chain the jQuery.noConflict() with the shorthand ready for a compact code.
]]></desc>
<code><![CDATA[jQuery.noConflict()(function(){
// code using jQuery
});
// other code using $ as an alias to the other library]]></code>
</example>
<example>
<desc><![CDATA[Creates a different alias instead of jQuery to use in the rest of the script.]]></desc>
<code><![CDATA[var j = jQuery.noConflict();
// Do something with jQuery
j("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';]]></code>
</example>
<example>
<desc><![CDATA[Completely move jQuery to a new namespace in another object.]]></desc>
<code><![CDATA[var dom = {};
dom.query = jQuery.noConflict(true);]]></code>
<results><![CDATA[// Do something with the new jQuery
dom.query("div p").hide();
// Do something with another library's $()
$("content").style.display = 'none';
// Do something with another version of jQuery
jQuery("div > p").hide();]]></results>
</example>
<category name="Core"/>
<category name="Setup Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="selected" return="">
<sample>:selected</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements that are selected.]]></desc>
<longdesc><![CDATA[
<p>The <code>:selected</code> selector works for <code>&lt;option&gt;</code> elements. It does not work for checkboxes or radio inputs; use <code>:checked</code> for them.</p>
]]></longdesc>
<example>
<desc><![CDATA[Attaches a change event to the select that gets the text for each selected option and writes them in the div. It then triggers the event for the initial text draw.]]></desc>
<code><![CDATA[
$("select").change(function () {
var str = "";
$("select option:selected").each(function () {
str += $(this).text() + " ";
});
$("div").text(str);
})
.trigger('change');
]]></code>
<css><![CDATA[
div { color:red; }
]]></css>
<html><![CDATA[<select name="garden" multiple="multiple">
<option>Flowers</option>
<option selected="selected">Shrubs</option>
<option>Trees</option>
<option selected="selected">Bushes</option>
<option>Grass</option>
<option>Dirt</option>
</select>
<div></div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="checked" return="">
<sample>:checked</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Matches all elements that are checked.]]></desc>
<longdesc><![CDATA[
<p>The <code>:checked</code> selector works for checkboxes and radio buttons. For select elements, use the <code>:selected</code> selector.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all input elements that are checked.]]></desc>
<code><![CDATA[
function countChecked() {
var n = $("input:checked").length;
$("div").text(n + (n <= 1 ? " is" : " are") + " checked!");
}
countChecked();
$(":checkbox").click(countChecked);
]]></code>
<css><![CDATA[
div { color:red; }
]]></css>
<html><![CDATA[<form>
<input type="checkbox" name="newsletter" checked="checked" value="Hourly" />
<input type="checkbox" name="newsletter" value="Daily" />
<input type="checkbox" name="newsletter" value="Weekly" />
<input type="checkbox" name="newsletter" checked="checked" value="Monthly" />
<input type="checkbox" name="newsletter" value="Yearly" />
</form>
<div></div>]]></html>
<results><![CDATA[<input type="checkbox" name="newsletter" checked="checked" value="Daily" />,
<input type="checkbox" name="newsletter" checked="checked" value="Monthly" /> ]]]></results>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="disabled" return="">
<sample>:disabled</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements that are disabled.]]></desc>
<longdesc><![CDATA[
<p>As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':disabled')</code> is equivalent to <code>$('*:disabled')</code>, so <code>$('input:disabled')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all input elements that are disabled.]]></desc>
<code><![CDATA[$("input:disabled").val("this is it");]]></code>
<html><![CDATA[<form>
<input name="email" disabled="disabled" />
<input name="id" />
</form>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="enabled" return="">
<sample>:enabled</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements that are enabled.]]></desc>
<longdesc><![CDATA[
<p>As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':enabled')</code> is equivalent to <code>$('*:enabled')</code>, so <code>$('input:enabled')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all input elements that are enabled.]]></desc>
<code><![CDATA[$("input:enabled").val("this is it");]]></code>
<html><![CDATA[<form>
<input name="email" disabled="disabled" />
<input name="id" />
</form>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="file" return="">
<sample>:file</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type file.]]></desc>
<longdesc><![CDATA[
<p>As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':file')</code> is equivalent to <code>$('*:file')</code>, so <code>$('input:file')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all file inputs.]]></desc>
<code><![CDATA[
var input = $("input:file").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="button" return="">
<sample>:button</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all button elements and elements of type button.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Finds all button inputs.]]></desc>
<code><![CDATA[
var input = $(":button").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="reset" return="">
<sample>:reset</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type reset.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Finds all reset inputs.]]></desc>
<code><![CDATA[
var input = $("input:reset").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="image" return="">
<sample>:image</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type image.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Finds all image inputs.]]></desc>
<code><![CDATA[
var input = $("input:image").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="submit" return="">
<sample>:submit</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type submit.]]></desc>
<longdesc><![CDATA[
<p>The <code>:submit</code> selector typically applies to button or input elements. Note that some browsers treat <code>&lt;button&gt;</code> element as <code>type="default"</code> implicitly while others (such as Internet Explorer) do not. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all submit elements that are descendants of a td element.]]></desc>
<code><![CDATA[
var submitEl = $("td :submit")
.parent('td')
.css({background:"yellow", border:"3px red solid"})
.end();
$('#result').text('jQuery matched ' + submitEl.length + ' elements.');
// so it won't submit
$("form").submit(function () { return false; });
// Extra JS to make the HTML easier to edit (None of this is relevant to the ':submit' selector
$('#exampleTable').find('td').each(function(i, el) {
var inputEl = $(el).children(),
inputType = inputEl.attr('type') ? ' type="' + inputEl.attr('type') + '"' : '';
$(el).before('<td>' + inputEl[0].nodeName + inputType + '</td>');
})
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[
<table>
<form>
<table id="exampleTable" border="1" cellpadding="10" align="center">
<tr>
<th>
Element Type
</th>
<th>
Element
</th>
</tr
<tr>
<td>
<input type="button" value="Input Button"/>
</td>
</tr>
<tr>
<td>
<input type="checkbox" />
</td>
</tr>
<tr>
<td>
<input type="file" />
</td>
</tr>
<tr>
<td>
<input type="hidden" />
</td>
</tr>
<tr>
<td>
<input type="image" />
</td>
</tr>
<tr>
<td>
<input type="password" />
</td>
</tr>
<tr>
<td>
<input type="radio" />
</td>
</tr>
<tr>
<td>
<input type="reset" />
</td>
</tr>
<tr>
<td>
<input type="submit" />
</td>
</tr>
<tr>
<td>
<input type="text" />
</td>
</tr>
<tr>
<td>
<select><option>Option</option></select>
</td>
</tr>
<tr>
<td>
<textarea></textarea>
</td>
</tr>
<tr>
<td>
<button>Button</button>
</td>
</tr>
<tr>
<td>
<button type="submit">Button type="submit"</button>
</td>
</tr>
</table>
</form>
<div id="result"></div>
]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="checkbox" return="">
<sample>:checkbox</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type checkbox.]]></desc>
<longdesc><![CDATA[
<p><code>$(':checkbox')</code> is equivalent to <code>$('[type=checkbox]')</code>. As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':checkbox')</code> is equivalent to <code>$('*:checkbox')</code>, so <code>$('input:checkbox')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all checkbox inputs.]]></desc>
<code><![CDATA[
var input = $("form input:checkbox").wrap('<span></span>').parent().css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:25px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="radio" return="">
<sample>:radio</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type radio.]]></desc>
<longdesc><![CDATA[
<p><code>$(':radio')</code> is equivalent to <code>$('[type=radio]')</code>. As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':radio')</code> is equivalent to <code>$('*:radio')</code>, so <code>$('input:radio')</code> should be used instead. </p>
<p>To select a set of associated radio buttons, you might use: <code>$('input[name=gender]:radio')</code></p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all radio inputs.]]></desc>
<code><![CDATA[
var input = $("form input:radio").wrap('<span></span>').parent().css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:25px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" name="asdf" />
<input type="radio" name="asdf" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="password" return="">
<sample>:password</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type password.]]></desc>
<longdesc><![CDATA[
<p><code>$(':password')</code> is equivalent to <code>$('[type=password]')</code>. As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':password')</code> is equivalent to <code>$('*:password')</code>, so <code>$('input:password')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all password inputs.]]></desc>
<code><![CDATA[
var input = $("input:password").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:45px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option<option/></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="text" return="">
<sample>:text</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all elements of type text.]]></desc>
<longdesc><![CDATA[
<p><code>$(':text')</code> is equivalent to <code>$('[type=text]')</code> and thus selects all <code>&lt;input type="text"&gt;</code> elements. As with other pseudo-class selectors (those that begin with a ":") it is recommended to precede it with a tag name or some other selector; otherwise, the universal selector ("*") is implied. In other words, the bare <code>$(':text')</code> is equivalent to <code>$('*:text')</code>, so <code>$('input:text')</code> should be used instead. </p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all text inputs.]]></desc>
<code><![CDATA[
var input = $("form input:text").css({background:"yellow", border:"3px red solid"});
$("div").text("For this type jQuery found " + input.length + ".")
.css("color", "red");
$("form").submit(function () { return false; }); // so it won't submit
]]></code>
<css><![CDATA[
textarea { height:25px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option</option></select>
<textarea></textarea>
<button>Button</button>
</form>
<div>
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="input" return="">
<sample>:input</sample>
<signature>
<added>1.0</added>
</signature>
<desc><![CDATA[Selects all input, textarea, select and button elements.]]></desc>
<longdesc><![CDATA[
<p>The <code>:input</code> selector basically selects all form controls.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all input elements.]]></desc>
<code><![CDATA[
var allInputs = $(":input");
var formChildren = $("form > *");
$("#messages").text("Found " + allInputs.length + " inputs and the form has " +
formChildren.length + " children.");
// so it won't submit
$("form").submit(function () { return false; });
]]></code>
<css><![CDATA[
textarea { height:25px; }
]]></css>
<html><![CDATA[<form>
<input type="button" value="Input Button"/>
<input type="checkbox" />
<input type="file" />
<input type="hidden" />
<input type="image" />
<input type="password" />
<input type="radio" />
<input type="reset" />
<input type="submit" />
<input type="text" />
<select><option>Option</option></select>
<textarea></textarea>
<button>Button</button>
</form>
<div id="messages">
</div>]]></html>
</example>
<category name="Form"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="only-child" return="">
<sample>:only-child</sample>
<signature>
<added>1.1.4</added>
</signature>
<desc><![CDATA[Selects all elements that are the only child of their parent.]]></desc>
<longdesc><![CDATA[
<p>If the parent has other child elements, nothing is matched.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds the button with no siblings in each matched div and modifies look.]]></desc>
<code><![CDATA[$("div button:only-child").text("Alone").css("border", "2px blue solid");]]></code>
<css><![CDATA[
div { width:100px; height:80px; margin:5px; float:left; background:#b9e }
]]></css>
<html><![CDATA[<div>
<button>Sibling!</button>
<button>Sibling!</button>
</div>
<div>
<button>Sibling!</button>
</div>
<div>
None
</div>
<div>
<button>Sibling!</button>
<button>Sibling!</button>
<button>Sibling!</button>
</div>
<div>
<button>Sibling!</button>
</div>]]></html>
<results><![CDATA[[ <li>Glen</li> ] ]]></results>
</example>
<category name="Child Filter"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="selector" name="last-child" return="">
<sample>:last-child</sample>
<signature>
<added>1.1.4</added>
</signature>
<desc><![CDATA[Selects all elements that are the last child of their parent.]]></desc>
<longdesc><![CDATA[
<p>While <a href="/last-selector">:last</a> matches only a single element, <code>:last-child</code> can match more than one: one for each parent.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds the last span in each matched div and adds some css plus a hover state.]]></desc>
<code><![CDATA[
$("div span:last-child")
.css({color:"red", fontSize:"80%"})
.hover(function () {
$(this).addClass("solast");
}, function () {
$(this).removeClass("solast");
});
]]></code>
<css><![CDATA[
span.solast { text-decoration:line-through; }
]]></css>
<html><![CDATA[<div>
<span>John,</span>
<span>Karl,</span>
<span>Brandon,</span>
<span>Sam</span>
</div>
<div>
<span>Glen,</span>
<span>Tane,</span>
<span>Ralph,</span>
<span>David</span>
</div>]]></html>
</example>
<category name="Child Filter"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="selector" name="first-child" return="">
<sample>:first-child</sample>
<signature>
<added>1.1.4</added>
</signature>
<desc><![CDATA[Selects all elements that are the first child of their parent.]]></desc>
<longdesc><![CDATA[
<p>While <a href="/first-selector">:first</a> matches only a single element, the <code>:first-child</code> selector can match more than one: one for each parent. This is equivalent to <code>:nth-child(1)</code>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds the first span in each matched div to underline and add a hover state.]]></desc>
<code><![CDATA[
$("div span:first-child")
.css("text-decoration", "underline")
.hover(function () {
$(this).addClass("sogreen");
}, function () {
$(this).removeClass("sogreen");
});
]]></code>
<css><![CDATA[
span { color:#008; }
span.sogreen { color:green; font-weight: bolder; }
]]></css>
<html><![CDATA[<div>
<span>John,</span>
<span>Karl,</span>
<span>Brandon</span>
</div>
<div>
<span>Glen,</span>
<span>Tane,</span>
<span>Ralph</span>
</div>]]></html>
</example>
<category name="Child Filter"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="selector" name="nth-child" return="">
<sample>:nth-child(index/even/odd/equation)</sample>
<signature>
<added>1.1.4</added>
<argument name="index" type="Number/String">
<desc><![CDATA[The index of each child to match, starting with <code>1</code>, the string <code>even</code> or <code>odd</code>, or an equation ( eg. <code>:nth-child(even)</code>, <code>:nth-child(4n)</code> )]]></desc>
</argument>
</signature>
<desc><![CDATA[Selects all elements that are the nth-child of their parent.]]></desc>
<longdesc><![CDATA[
<p>Because jQuery's implementation of <code>:nth-child(n)</code> is strictly derived from the CSS specification, the value of <code>n</code> is "1-indexed", meaning that the counting starts at 1. For all other selector expressions, however, jQuery follows JavaScript's "0-indexed" counting. Therefore, given a single <code>&lt;ul&gt;</code> containing two <code>&lt;li&gt;</code>s, <code>$('li:nth-child(1)')</code> selects the first <code>&lt;li&gt;</code> while <code>$('li:eq(1)')</code> selects the second.</p>
<p>The <code>:nth-child(n)</code> pseudo-class is easily confused with <code>:eq(n)</code>, even though the two can result in dramatically different matched elements. With <code>:nth-child(n)</code>, all children are counted, regardless of what they are, and the specified element is selected only if it matches the selector attached to the pseudo-class. With <code>:eq(n)</code> only the selector attached to the pseudo-class is counted, not limited to children of any other element, and the nth one is selected.</p>
<p>Further discussion of this unusual usage can be found in the <a href="http://www.w3.org/TR/css3-selectors/#nth-child-pseudo">W3C CSS specification</a>.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds the second li in each matched ul and notes it.]]></desc>
<code><![CDATA[$("ul li:nth-child(2)").append("<span> - 2nd!</span>");]]></code>
<css><![CDATA[
div { float:left; }
span { color:blue; }
]]></css>
<html><![CDATA[<div><ul>
<li>John</li>
<li>Karl</li>
<li>Brandon</li>
</ul></div>
<div><ul>
<li>Sam</li>
</ul></div>
<div><ul>
<li>Glen</li>
<li>Tane</li>
<li>Ralph</li>
<li>David</li>
</ul></div>]]></html>
</example>
<example>
<desc><![CDATA[This is a playground to see how the selector works with different strings. Notice that this is different from the :even and :odd which have no regard for parent and just filter the list of elements to every other one. The :nth-child, however, counts the index of the child to its particular parent. In any case, it's easier to see than explain so...]]></desc>
<code><![CDATA[
$("button").click(function () {
var str = $(this).text();
$("tr").css("background", "white");
$("tr" + str).css("background", "#ff0000");
$("#inner").text(str);
});
]]></code>
<css><![CDATA[
button { display:block; font-size:12px; width:100px; }
div { float:left; margin:10px; font-size:10px;
border:1px solid black; }
span { color:blue; font-size:18px; }
#inner { color:red; }
td { width:50px; text-align:center; }
]]></css>
<html><![CDATA[<div>
<button>:nth-child(even)</button>
<button>:nth-child(odd)</button>
<button>:nth-child(3n)</button>
<button>:nth-child(2)</button>
</div>
<div>
<button>:nth-child(3n+1)</button>
<button>:nth-child(3n+2)</button>
<button>:even</button>
<button>:odd</button>
</div>
<div><table>
<tr><td>John</td></tr>
<tr><td>Karl</td></tr>
<tr><td>Brandon</td></tr>
<tr><td>Benjamin</td></tr>
</table></div>
<div><table>
<tr><td>Sam</td></tr>
</table></div>
<div><table>
<tr><td>Glen</td></tr>
<tr><td>Tane</td></tr>
<tr><td>Ralph</td></tr>
<tr><td>David</td></tr>
<tr><td>Mike</td></tr>
<tr><td>Dan</td></tr>
</table></div>
<span>
tr<span id="inner"></span>
</span>]]></html>
</example>
<category name="Child Filter"/>
<category name="Version 1.1.4"/>
</entry>
<entry type="selector" name="attributeContainsPrefix" return="">
<sample>[attribute|=value]</sample>
<signature>
<added>1.0</added>
<argument name="attribute" type="String">
<desc><![CDATA[An attribute name.]]></desc>
</argument>
<argument name="value" type="String">
<desc><![CDATA[An attribute value. Quotes are optional.]]></desc>
</argument>
</signature>
<desc><![CDATA[Selects elements that have the specified attribute with a value either equal to a given string or starting with that string followed by a hyphen (-).]]></desc>
<longdesc><![CDATA[
<p>This selector was introduced into the CSS specification to handle language attributes.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all links with an hreflang attribute that is english.]]></desc>
<code><![CDATA[$('a[hreflang|=en]').css('border','3px dotted green');]]></code>
<html><![CDATA[
<a href="example.html" hreflang="en">Some text</a>
<a href="example.html" hreflang="en-UK">Some other text</a>
]]></html>
</example>
<category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="attributeContainsWord" return="">
<sample>[attribute~=value]</sample>
<signature>
<added>1.0</added>
<argument name="attribute" type="String">
<desc><![CDATA[An attribute name.]]></desc>
</argument>
<argument name="value" type="String">
<desc><![CDATA[An attribute value. Quotes are optional.]]></desc>
</argument>
</signature>
<desc><![CDATA[Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.]]></desc>
<longdesc><![CDATA[
<p>This selector matches the test string against each word in the attribute value, where a "word" is defined as a string delimited by whitespace. The selector matches if the test string is exactly equal to any of the words.</p>
]]></longdesc>
<example>
<desc><![CDATA[Finds all inputs with a name attribute that contains the word 'man' and sets the value with some text.]]></desc>
<code><![CDATA[$("input[name~=man]").val("mr. man is in it!");]]></code>
<html><![CDATA[<input name="man-news" />
<input name="milk man" />
<input name="letterman2" />
<input name="newmilk" />]]></html>
</example>
<category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="attributeMultiple" return="">
<sample>[attributeFilter1][attributeFilter2][attributeFilterN]</sample>
<signature>
<added>1.0</added>
<argument name="attributeFilter1" type="Selector">
<desc><![CDATA[An attribute filter.]]></desc>
</argument>
<argument name="attributeFilter2" type="Selector">
<desc><![CDATA[Another attribute filter, reducing the selection even more]]></desc>
</argument>
<argument name="attributeFilterN" optional="true" type="Selector">
<desc><![CDATA[As many more attribute filters as necessary]]></desc>
</argument>
</signature>
<desc><![CDATA[Matches elements that match all of the specified attribute filters.]]></desc>
<longdesc/>
<example>
<desc><![CDATA[Finds all inputs that have an id attribute and whose name attribute ends with man and sets the value.]]></desc>
<code><![CDATA[$("input[id][name$='man']").val("only this one");]]></code>
<html><![CDATA[<input id="man-news" name="man-news" />
<input name="milkman" />
<input id="letterman" name="new-letterman" />
<input name="newmilk" />]]></html>
</example>
<category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
<entry type="selector" name="attributeContains" return="">
<sample>[attribute*=value]</sample>
<signature>
<added>1.0</added>
<argument name="attribute" type="String">
<desc><![CDATA[An attribute name.]]></desc>
</argument>
<argument name="value" type="String"