jQueryAPI.en_US.xml

<?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="Internals"/>
    <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.4.4"/>
      <category name="Version 1.4.3"/>
      <category name="Version 1.4.2"/>
      <category name="Version 1.4.1"/>
      <category name="Version 1.4"/>
      <category name="Version 1.3"/>
      <category name="Version 1.2.6"/>
      <category name="Version 1.2.3"/>
      <category name="Version 1.2"/>
      <category name="Version 1.1.4"/>
      <category name="Version 1.1.3"/>
      <category name="Version 1.1.2"/>
      <category name="Version 1.1"/>
      <category name="Version 1.0.4"/>
      <category name="Version 1.0"/>
   </category>
  </categories>
    <entries>
    <entry type='method' name="fadeToggle" return="jQuery">
  <desc>Display or hide the matched elements by animating their opacity.</desc>
  <signature>
    <added>1.4.4</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Function" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <longdesc>
  <p>The <code>.fadeToggle()</code> method animates the opacity of the matched elements. When called on a visible element, the element's <code>display</code> style property is set to <code>none</code> once the opacity reaches 0, so the element no longer affects the layout of the page.</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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
 <p>The string representing an easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
  <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
  </longdesc>
   <example>
        <desc>Fades first paragraph in or out, completing the animation within 600 milliseconds and using a linear easing. Fades last paragraph in or out for 200 milliseconds, inserting a "finished" message upon completion. </desc>
        <code><![CDATA[
$("button:first").click(function() {
  $("p:first").fadeToggle("slow", "linear");
});
$("button:last").click(function () {
  $("p:last").fadeToggle("fast", function () {
    $("#log").append("<div>finished</div>");
  });
});
]]></code>
<html><![CDATA[
<button>fadeToggle p1</button>
<button>fadeToggle p2</button>
<p>This paragraph has a slow, linear fade.</p>

<p>This paragraph has a fast animation.</p>
<div id="log"></div>
]]></html>
</example>
 
<category name="Effects"/>
<category name="Fading"/>
<category name="Version 1.4.4"/>
</entry>
  <entry type='method' name="jQuery.type" return="String">
                <signature>
                  <added>1.4.3</added>
                    <argument name="obj" type="Object">
                       <desc>Object to get the internal JavaScript [[Class]] of.</desc>
                    </argument>
                </signature>
                <desc>Determine the internal JavaScript [[Class]] of an object.</desc>
                <longdesc><p>A number of different aspects are utilized to determine the exact return value for an object. The logic can be determined as follows:</p>
<ul>
<li>If the object is undefined or null then "undefined" or "null" is returned accordingly.</li>
<li>If the object has an internal [[Class]] equivalent to one of the browser's built-in objects we return the associated name. (<a href="http://perfectionkills.com/instanceof-considered-harmful-or-how-to-write-a-robust-isarray/">More details about this technique.</a>)<ul>
<li>jQuery.type(true) === "boolean"</li>
<li>jQuery.type(3) === "number"</li>
<li>jQuery.type("test") === "string"</li>
<li>jQuery.type(function(){}) === "function"</li>
<li>jQuery.type([]) === "array"</li>
<li>jQuery.type(new Date()) === "date"</li>
<li>jQuery.type(/test/) === "regexp"</li>
</ul></li>
<li>Everything else will return "object" as its type.</li>
</ul>
</longdesc>
                <example>
                    <desc>Finds out if the parameter is a RegExp.</desc>
                    <code><![CDATA[$("b").append( "" + jQuery.type(/test/) );]]></code>
                    <html><![CDATA[Is it a RegExp? <b></b>]]></html>
                </example>
            <category name="Utilities"/>
<category name="Version 1.4.3"/>
</entry>
  <entry type='method' name="jQuery.isWindow" return="boolean">
                <signature>
                  <added>1.4.3</added>
                    <argument name="obj" type="Object">
                       <desc>Object to test whether or not it is a window.</desc>
                    </argument>
                </signature>
                <desc>Determine whether the argument is a window.</desc>
                <longdesc><p>This is used in a number of places in jQuery to determine if we're operating against a browser window (such as the current window or an iframe).</p></longdesc>
                <example>
                    <desc>Finds out if the parameter is a window.</desc>
                    <code><![CDATA[$("b").append( "" + $.isWindow(window) );]]></code>
                    <html><![CDATA[Is 'window' a window? <b></b>]]></html>
                </example>
            <category name="Utilities"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="toggle" return="jQuery">
  <desc>Bind two or more handlers to the matched elements, to be executed on alternate clicks.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute every even time the element is clicked.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute every odd time the element is clicked.</desc>
    </argument>
    <argument name="handler(eventObject)" optional="true" type="Function">
      <desc>Additional handlers to cycle through after clicks.</desc>
    </argument>
  </signature>

<longdesc>
<p>The <code>.toggle()</code> method binds a handler for the <code>click</code> event, so the rules outlined for the triggering of <code>click</code> apply here as well.</p>
<pre>For example, consider the HTML:
&lt;div id="target"&gt;
  Click here
&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_05.png" alt="" />
</p>
<p>Event handlers can then be bound to the <code>&lt;div&gt;</code>:</p>
<pre>$('#target').toggle(function() {
  alert('First handler for .toggle() called.');
}, function() {
  alert('Second handler for .toggle() called.');
});</pre>
<p>As the element is clicked repeatedly, the messages alternate:</p>
<p>
  <span class="output">First handler for .toggle() called.</span><br />
  <span class="output">Second handler for .toggle() called.</span><br />
  <span class="output">First handler for .toggle() called.</span><br />
  <span class="output">Second handler for .toggle() called.</span><br />
  <span class="output">First handler for .toggle() called.</span>
</p>
<p>If more than two handlers are provided, <code>.toggle()</code> will cycle among all of them. For example, if there are three handlers, then the first handler will be called on the first click, the fourth click, the seventh click, and so on.</p>
<blockquote><p>Note: jQuery also provides an animation method named <a href="http://api.jquery.com/toggle/">.toggle()</a> that toggles the visibility of elements. Whether the animation or the event method is fired depends on the set of arguments passed.</p></blockquote>

<p>The <code>.toggle()</code> method is provided for convenience. It is relatively straightforward to implement the same behavior by hand, and this can be necessary if the assumptions built into <code>.toggle()</code> prove limiting. For example, <code>.toggle()</code> is not guaranteed to work correctly if applied twice to the same element. Since <code>.toggle()</code> internally uses a <code>click</code> handler to do its work, we must unbind <code>click</code> to remove a behavior attached with <code>.toggle()</code>, so other <code>click</code> handlers can be caught in the crossfire. The implementation also calls <code>.preventDefault()</code> on the event, so links will not be followed and buttons will not be clicked if <code>.toggle()</code> has been called on the element.</p>
</longdesc>
                <example>
                    <desc>Click to toggle highlight on the list item.</desc>
                    <code><![CDATA[
    $("li").toggle(
      function () {
        $(this).css({"list-style-type":"disc", "color":"blue"});
      },
      function () {
        $(this).css({"list-style-type":"disc", "color":"red"});
      },
      function () {
        $(this).css({"list-style-type":"", "color":""});
      }
    );

]]></code>
                    <css><![CDATA[
  ul { margin:10px; list-style:inside circle; font-weight:bold; }
  li { cursor:pointer; }
  ]]></css>
                    <html><![CDATA[<ul>
    <li>Go to the store</li>
    <li>Pick up dinner</li>
    <li>Debug crash</li>

    <li>Take a jog</li>
  </ul>]]></html>
                </example>
                <example>
                    <desc>To toggle a style on table cells:</desc>
                    <code><![CDATA[$("td").toggle(
  function () {
    $(this).addClass("selected");
  },
  function () {
    $(this).removeClass("selected");
  }
);]]></code>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
</entry>
<entry type='property' name="jQuery.fx.interval" return="Number">
  <desc>The rate (in milliseconds) at which animations fire.</desc>
  <signature>
    <added>1.4.3</added>
  </signature>
  <longdesc>
    <p>This property can be manipulated to adjust the number of frames per second at which animations will run. The default is 13 milliseconds. Making this a lower number could make the animations run smoother in faster browsers (such as Chrome) but there may be performance and CPU implications of doing so.</p>
    <p>Since jQuery uses one global interval, no animation should be running or all animations should stop for the change of this property to take effect.</p>
  </longdesc>
  <example>
    <desc>Cause all animations to run with less frames.</desc>
    <code><![CDATA[
jQuery.fx.interval = 100;

$("input").click(function(){
  $("div").toggle( 3000 );
});
  ]]></code>
<css><![CDATA[
    div { width:50px; height:30px; margin:5px; float:left;
          background:green; }
    ]]></css>
      <html><![CDATA[<p><input type="button" value="Run"/></p>
<div></div>]]></html>
                  </example>
<category name="Custom"/>
<category name="Properties of the Global jQuery Object"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='property' name="event.namespace" return="String">
    <signature>
        <added>1.4.3</added>
    </signature>
    <desc>The namespace specified when the event was triggered.</desc>
    <longdesc><p>This will likely be used primarily by plugin authors who wish to handle tasks differently depending on the event namespace used.</p></longdesc>
    <example>
        <desc>Determine the event namespace used.</desc>
        <code><![CDATA[
$("p").bind("test.something", function(event) {
  alert( event.namespace );
});
$("button").click(function(event) {
  $("p").trigger("test.something");
});  
]]></code>
<html><![CDATA[
<button>display event.namespace</button>
<p></p>
]]></html>
        
    </example>
<category name="Event Object"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="undelegate" return="jQuery">
  <desc>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>A selector which will be used to filter the event results.</desc>
    </argument>
    <argument name="eventType" type="String">
      <desc>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>A selector which will be used to filter the event results.</desc>
    </argument>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as "click" or "keydown"</desc>
    </argument>
    <argument name="handler" type="Function">
      <desc>A function to execute at the time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc>
  <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>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>To unbind all delegated events from all paragraphs, write:</desc>
                <code><![CDATA[$("p").undelegate()]]></code>
            </example>
            <example>
                <desc>To unbind all delegated click events from all paragraphs, write:</desc>
                <code><![CDATA[$("p").undelegate( "click" )]]></code>
            </example>
            <example>
                <desc>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>Attach a handler to one or more events for all elements that match the selector, now or in the future, based on a specific set of root elements.</desc>
  <signature>
    <added>1.4.2</added>
    <argument name="selector" type="String">
      <desc>A selector to filter the elements that trigger the event.</desc>
    </argument>
    <argument name="eventType" type="String">
      <desc>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>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>A selector to filter the elements that trigger the event.</desc>
    </argument>
    <argument name="eventType" type="String">
      <desc>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>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler" type="Function">
      <desc>A function to execute at the time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc>
  <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>
<p>Passing and handling event data works <a href="http://api.jquery.com/bind/#passing-event-data">the same way as it does for .bind()</a>.</p>
</longdesc>
  <example>
    <desc>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>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>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>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>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>The message to send out.</desc>
                  </argument>
                </signature>
                <desc>Takes a string and throws an exception containing it.</desc>
                <longdesc><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>Override jQuery.error for display in Firebug.</desc>
                    <code><![CDATA[jQuery.error = console.error;]]></code>
                </example>
            <category name="Internals"/>
<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>The JSON string to parse.</desc>
                  </argument>
                </signature>
                <desc>Takes a well-formed JSON string and returns the resulting JavaScript object.</desc>
                <longdesc><p>Passing in a malformed JSON string may 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. Where the browser provides a native implementation of <code>JSON.parse</code>, jQuery uses it to parse the string. For details on the JSON format, see <a href="http://json.org/">http://json.org/</a>.
</p></longdesc>
                <example>
                    <desc>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>The function whose context will be changed.</desc>
                  </argument>
                  <argument name="context" type="Object">
                    <desc>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>The object to which the context of the function should be set.</desc>
                  </argument>
                  <argument name="name" type="String">
                    <desc>The name of the function whose context will be changed (should be a property of the 'context' object.</desc>
                  </argument>
                </signature>
                <desc>Takes a function and returns a new one that will always have a particular context.</desc>
                <longdesc><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>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>Bind an event handler to the "focusout" JavaScript event.</desc>
  <signature>
    <added>1.4</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc><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 event bubbling).</p>
<p>This event will likely be used together with the <a href="/focusin">focusin</a> event.</p></longdesc>
  <example>
  <desc>Watch for a loss of focus to occur inside paragraphs and note the difference between the <code>focusout</code> count and the <code>blur</code> count.</desc>
  <css><![CDATA[
.inputs { float: left; margin-right: 1em; }
.inputs p { margin-top: 0; }
]]></css>
  <code><![CDATA[
var fo = 0, b = 0;
$("p").focusout(function() {
  fo++;
  $("#fo")
    .text("focusout fired: " + fo + "x");
}).blur(function() {
  b++;
  $("#b")
    .text("blur fired: " + b + "x");
  
});
]]></code>
    <html><![CDATA[
<div class="inputs">
  <p>
    <input type="text" /><br />
    <input type="text" /> 
  </p>
  <p>
    <input type="password" />
  </p>
</div>
<div id="fo">focusout fire</div>
<div id="b">blur fire</div>
]]></html>
  </example>
<category name="Keyboard Events"/>
<category name="Mouse Events"/>
<category name="Version 1.4"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="focusin" return="jQuery">
  <desc>Bind an event handler to the "focusin" JavaScript event.</desc>
  <signature>
    <added>1.4</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc><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>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"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="has" return="jQuery">
  <signature>
    <added>1.4</added>
    <argument name="selector" type="String">
      <desc>A string containing a selector expression to match elements against.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="contained" type="Element">
      <desc>A DOM element to match elements against.</desc>
    </argument>
  </signature>
  <desc>Reduce the set of matched elements to those that have a descendant that matches the selector or DOM element.</desc>
  <longdesc>
    <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>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>The DOM element that may contain the other element.</desc>
                  </argument>
                  <argument name="contained" type="Element">
                    <desc>The DOM node that may be contained by the other element.</desc>
                  </argument>
                </signature>
                <desc>Check to see if a DOM node is within another DOM node.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>An empty function.</desc>
                <longdesc><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>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>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
  </argument>
</signature>
<desc>Set a timer to delay execution of subsequent items in the queue.</desc>
<longdesc><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. Only subsequent events in a queue are delayed; for example this will <em>not</em> delay the no-arguments forms of <code>.show()</code> or <code>.hide()</code>  which do not use the effects 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>
<blockquote><p><strong>The <code>.delay()</code> method is best for delaying between queued jQuery effects. Because it is limited—it doesn't, for example, offer a way to cancel the delay—<code>.delay()</code> is not a replacement for JavaScript's native <a href="https://developer.mozilla.org/en/DOM/window.setTimeout">setTimeout</a> function, which may be more appropriate for certain use cases.</strong></p></blockquote>
</longdesc>
<example>
  <desc>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>A string containing a selector expression to indicate where to stop matching ancestor elements.</desc>
    </argument>
  </signature>
  <desc>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><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>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>A string containing a selector expression to indicate where to stop matching preceding sibling elements.</desc>
    </argument>
  </signature>
  <desc>Get all preceding siblings of each element up to but not including the element matched by the selector.</desc>
  <longdesc><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>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>A string containing a selector expression to indicate where to stop matching following sibling elements.</desc>
    </argument>
  </signature>
  <desc>Get all following siblings of each element up to but not including the element matched by the selector.</desc>
  <longdesc><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>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>  Returns whether event.stopImmediatePropagation() was ever called on this event object. </desc>
    <longdesc> <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>Checks whether event.stopImmediatePropagation() was called.</desc>
  <code><![CDATA[

function immediatePropStopped(e) {
  var msg = "";
  if ( e.isImmediatePropagationStopped() ) {
    msg =  "called"
  } else {
    msg = "not called";
  }
  $("#stop-log").append( "<div>" + msg + "</div>" );
}

$("button").click(function(event) {
  immediatePropStopped(event);
  event.stopImmediatePropagation();
  immediatePropStopped(event);
});  
]]></code>
  <html><![CDATA[
  <button>click me</button>
  <div id="stop-log"></div>
  ]]></html>
    </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> Keeps the rest of the handlers from being executed and prevents the event from bubbling up the DOM tree.
  </desc>
    <longdesc><p>In addition to keeping any additional handlers on an element from being executed, this method also stops the bubbling by implicitly calling <code>event.stopPropagation()</code>. To simply prevent the event from bubbling to ancestor elements but allow other event handlers to execute on the same element, we can use <code><a href="http://api.jquery.com/event.stopPropagation">event.stopPropagation()</a></code> instead.</p>
<p>Use <code><a href="http://api.jquery.com/event.isImmediatePropagationStopped">event.isImmediatePropagationStopped()</a></code> to know whether this method was ever called (on that event object).</p> </longdesc>
    <example>
        <desc>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>  Returns whether <a href="/event.stopPropagation">event.stopPropagation()</a> was ever called on this event object. </desc>
    <longdesc><p>This event method is described in the <a href="http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331/events.html#Events-Event-isPropagationStopped">W3C DOM Level 3 specification</a>.</p></longdesc>
    <example>
  <desc>Checks whether event.stopPropagation() was called</desc>
  <code><![CDATA[

function propStopped(e) {
  var msg = "";
  if ( e.isPropagationStopped() ) {
    msg =  "called"
  } else {
    msg = "not called";
  }
  $("#stop-log").append( "<div>" + msg + "</div>" );
}

$("button").click(function(event) {
  propStopped(event);
  event.stopPropagation();
  propStopped(event);
});  
]]></code>
  <html><![CDATA[
  <button>click me</button>
  <div id="stop-log"></div>
  ]]></html>
    </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>Prevents the event from bubbling up the DOM tree, preventing any parent handlers from being notified of the event.   </desc>
    <longdesc>  <p>We can use <code><a href="/event.isPropagationStopped">event.isPropagationStopped()</a></code> to determine if this method was ever called (on that event object). </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. </p> </longdesc>
    <example>
        <desc>Kill the bubbling on the click event.</desc>
        <code><![CDATA[$("p").click(function(event){
  event.stopPropagation();
  // do something
});  ]]></code>
</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>Returns whether <a href="/event.preventDefault">event.preventDefault()</a> was ever called on this event object. </desc>
    <longdesc>   </longdesc>
    <example>
        <desc>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> If this method is called, the default action of the event will not be triggered. </desc>
    <longdesc> <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>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>The difference in milliseconds between the time an event is triggered and January 1, 1970.</desc>
  <longdesc><p>This property can be useful for profiling the performance of certain jQuery functions by getting the <code>event.timeStamp</code> value at two points in the code and noting the difference.</p> </longdesc>
  <example>
    <desc>Display the time since the click handler last executed.</desc>
<css><![CDATA[
div { height: 100px; width: 300px; margin: 10px; 
      background-color: #ffd; overflow: auto; }
]]></css>
<code><![CDATA[
var last, diff;
$('div').click(function(event) {
  if ( last ) {
    diff = event.timeStamp - last
    $('div').append('time since last event: ' + diff + '<br/>');
  } else {
    $('div').append('Click again.<br/>');
  }
  last = event.timeStamp;
});  
]]></code>
<html><![CDATA[
<div>Click.</div>]]></html>
    </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> The last value returned by an event handler that was triggered by this event, unless the value was <code>undefined</code>.  </desc>
    <longdesc> <p>This property can be useful for getting previous return values of custom events. </p></longdesc>
    <example>
        <desc>Display previous handler's return value</desc>
        <code><![CDATA[
$("button").click(function(event) {
  return "hey";
});
$("button").click(function(event) {
  $("p").html( event.result );
});  
]]></code>
<html><![CDATA[
<button>display event.result</button>
<p></p>
]]></html>
        
    </example>
<category name="Event Object"/>
<category name="Version 1.3"/>
</entry>
<entry type='property' name="event.which" return="Number">
    <signature>
        <added>1.1.3</added>
    </signature>
    <desc> For key or button events, this attribute indicates the specific button or key that was pressed.  </desc>
    <longdesc> <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>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>The mouse position relative to the top edge of the document. </desc>
    <longdesc>   </longdesc>
    <example>
        <desc>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>The mouse position relative to the left edge of the document. </desc>
    <longdesc>   </longdesc>
        <example>
        <desc>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> The current DOM element within the event bubbling phase.  </desc>
    <longdesc><p>This property will typically be equal to the <code>this</code> of the function.</p>
<p><em>If you are using <a href="/jQuery.proxy">jQuery.proxy</a> or another form of scope manipulation, <code>this</code> will be equal to whatever context you have provided, not <code>event.currentTarget</code></em></p>
  </longdesc>
    <example>
        <desc>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>  The other DOM element involved in the event, if any. </desc>
    <longdesc><p>For <code>mouseout</code>, indicates the element being entered; for <code>mousein</code>, indicates the element being exited. </p> </longdesc>
    <example>
        <desc>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> The optional data passed to jQuery.fn.bind when the current executing handler was bound.  </desc>
    <longdesc>   </longdesc>
    <example>
        <desc>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> The DOM element that initiated the event.  </desc>
    <longdesc> <p>The <code>target</code> property can be the element that registered for the event or a descendant 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>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>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> Describes the nature of the event.  </desc>
    <longdesc>   </longdesc>
    <example>
        <desc>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>Globally disable all animations.</desc>
  <signature>
    <added>1.3</added>
  </signature>
  <longdesc>
    <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>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>A function to execute for each matched element.</desc>
                  </argument>
                </signature>
                <desc>Iterate over a jQuery object, executing a function for each matched element. </desc>
<longdesc>
  <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>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>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>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="Traversing"/>
<category name="Version 1.0"/>
</entry>

            <entry type='method' name="pushStack" return="jQuery">
                <signature>
                  <added>1.0</added>
                  <argument name="elements" type="Array">
                    <desc>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>An array of elements to push onto the stack and make into a new jQuery object.</desc>
                  </argument>
                  <argument name="name" type="String">
                    <desc>The name of a jQuery method that generated the array of elements.</desc>
                  </argument>
                  <argument name="arguments" type="Array">
                    <desc>The arguments that were passed in to the jQuery method (for serialization).</desc>
                  </argument>
                </signature>
                <desc>Add a collection of DOM elements onto the jQuery stack.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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="Internals"/>
<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>The JavaScript code to execute.</desc>
                  </argument>
                </signature>
                <desc>Execute some JavaScript code globally.</desc>
                <longdesc><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>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>The DOM node that will be checked to see if it's in an XML document.</desc>
                  </argument>
                </signature>
                <desc>Check to see if a DOM node is within an XML document (or is an XML document).</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>A DOM element from which to remove data.</desc>
		</argument>

		<argument name="name" type="String" optional="true">
			<desc>A string naming the piece of data to remove.</desc>
		</argument>
	</signature>
	<desc>Remove a previously-stored piece of data.</desc>
	<longdesc><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>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>The DOM element to associate with the data.</desc>
		</argument>
		<argument name="key" type="String">
			<desc>A string naming the piece of data to set.</desc>
		</argument>
		<argument name="value" type="Object">
			<desc>The new data value.</desc>
		</argument>
	</signature>
	<desc>Store arbitrary data associated with the specified element.</desc>
	<longdesc><p><strong>Note:</strong> This is a low-level method; a more convenient <code><a href='/data'>.data()</a></code> is also available.</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 free from memory leaks. jQuery ensures that the data is removed when DOM elements are removed via jQuery methods, and when the user leaves the page. 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>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"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="jQuery.data" return="Object">
	<signature>
		<added>1.2.3</added>
		<argument name="element" type="Element">
	<desc>The DOM element to query for the data.</desc>
		</argument>
		<argument name="key" type="String">
				<desc>Name of the data stored.</desc>
		</argument>
	</signature>
	<signature>
		<added>1.4</added>
		<argument name="element" type="Element">
	<desc>The DOM element to query for the data.</desc>
		</argument>
	</signature>
	<desc>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><p><strong>Note:</strong> This is a low-level method; a more convenient <code><a href='/data'>.data()</a></code> is also available.</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>
<p><strong>HTML 5 data- Attributes</strong></p>
<p>As of jQuery 1.4.3 <a href="http://ejohn.org/blog/html-5-data-attributes/">HTML 5 data- attributes</a> will be automatically pulled in to jQuery's data object.</p>

<p>For example, given the following HTML:</p>

<pre>&lt;div data-role="page" data-hidden="true" data-options='{"name":"John"}'&gt;&lt;/div&gt;</pre>

<p>All of the following jQuery code will work.</p>

<pre>$("div").data("role") === "page";
$("div").data("hidden") === true;
$("div").data("options").name === "John";</pre>

<p>Note that strings are left intact while JavaScript values are converted to their associated value (this includes booleans, numbers, objects, arrays, and null). When the data attribute is an object (starts with '{') or array (starts with '[') then <code>jQuery.parseJSON</code> is used to parse the string; it must follow valid JSON syntax <em>including quoted property names</em>. The data- attributes are pulled in the first time the data property is accessed and then are no longer accessed or mutated (all data values are then stored internally in jQuery).</p>
</longdesc>
  <example>
    <desc>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"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="jQuery.dequeue" return="jQuery">
  <signature>
    <added>1.3</added>
    <argument name="element" type="Element">
      <desc>A DOM element from which to remove and execute a queued function.</desc>
    </argument>

    <argument name="queueName" optional="true" type="String">
      <desc>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
    </argument>
  </signature>
                <desc>Execute the next function on the queue for the matched element.</desc>
                <longdesc><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>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>A DOM element to inspect for an attached queue.</desc>
		</argument>
		<argument name="queueName" optional="true" type="String">
			<desc>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
		</argument>
	</signature>
	<desc>Show the queue of functions to be executed on the matched element.</desc>
	<longdesc><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>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>A DOM element where the array of queued functions is attached.</desc>
		</argument>
		<argument name="queueName" type="String">
			<desc>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>An array of functions to replace the current queue contents.</desc>
		</argument>
	</signature>
	<signature>
		<added>1.3</added>
		<argument name="element" type="Element">
		  <desc>A DOM element on which to add a queued function.</desc>
		</argument>
		<argument name="queueName" type="String">
			<desc>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>The new function to add to the queue.</desc>
		</argument>
	</signature>
	<desc>Manipulate the queue of functions to be executed on the matched element.</desc>
	<longdesc><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>Queue a custom function.</desc>
		<code><![CDATA[
   $(document.body).click(function () {
      $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      jQuery.queue( $("div")[0], "fx", function () {
        $(this).addClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").animate({left:'-=200'},500);
      jQuery.queue( $("div")[0], "fx", 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>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], "fx", function () {
        $(this).addClass("newcolor");
        jQuery.dequeue( this );
      });
      $("div").animate({left:'-=200'},1500);
      jQuery.queue( $("div")[0], "fx", 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>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
  </argument>
</signature>
<desc>Remove from the queue all items that have not yet been run.</desc>
<longdesc><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>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>Retrieve all the DOM elements contained in the jQuery set, as an array.</desc>
              <longdesc><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>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>The object that will be checked to see if it's empty.</desc>
                  </argument>
                </signature>
                <desc>Check to see if an object is empty (contains no properties).</desc>
                <longdesc><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>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>The object that will be checked to see if it's a plain object.</desc>
                  </argument>
                </signature>
                <desc>Check to see if an object is a plain object (created using "{}" or "new Object").</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>
  <desc>Bind an event handler to the "keydown" JavaScript event, or trigger that event on an element.</desc>
<longdesc>
<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 <a href="http://api.jquery.com/category/events/event-object/">event object</a> 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>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"/>
<category name="Version 1.4.3"/>
</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>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>The DOM element or first element within the jQuery object to look for.</desc>
                </argument>
              </signature>
              <desc>Search for a given element from among the matched elements.</desc>
              <longdesc><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>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>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>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>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>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>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>A string naming the piece of data to delete.</desc>
                </argument>
              </signature>
              <desc>Remove a previously-stored piece of data.</desc>
              <longdesc><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><p>NOTE: Starting with jQuery 1.4.3, calling <code>.removeData()</code> will cause the value of the property being removed to revert to the value of the data attribute of the same name in the DOM, rather than being set to <code>undefined</code>.</p></longdesc>
                <example>
                    <desc>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"/>
<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>A string naming the piece of data to set.</desc>
    </argument>
    <argument name="value" type="Object">
      <desc>The new data value; it can be any Javascript type including Array or Object.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="obj" type="Object">
      <desc>An object of key-value pairs of data to update.</desc>
    </argument>
  </signature>
  <desc>Store arbitrary data associated with the matched elements.</desc>
  <longdesc><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>In jQuery 1.4.3 setting an element's data object with <code>.data(obj)</code> extends the data previously stored with that element. jQuery itself uses the <code>.data()</code> method to save information under the names 'events' and 'handle', and also reserves any data name starting with an underscore ('_') for internal use.</p>
<p>Prior to jQuery 1.4.3 (starting in jQuery 1.4) the .data() method completely replaced all data, instead of just extending the data object. If you are using third-party plugins it may not be advisable to completely replace the element's data object, since plugins may have also set data.</p>
<p>Due to the way browsers interact with plugins and external code, the <code>.data()</code> method cannot be used on <code>&lt;object&gt;</code> (unless it's a Flash plugin), <code>&lt;applet&gt;</code> or <code>&lt;embed&gt;</code> elements.</p>
<p><strong>HTML 5 data- Attributes</strong></p>
<p>As of jQuery 1.4.3 <a href="http://ejohn.org/blog/html-5-data-attributes/">HTML 5 data- attributes</a> will be automatically pulled in to jQuery's data object.</p>

<p>For example, given the following HTML:</p>

<pre>&lt;div data-role="page" data-hidden="true" data-options='{"name":"John"}'&gt;&lt;/div&gt;</pre>

<p>All of the following jQuery code will work.</p>

<pre>$("div").data("role") === "page";
$("div").data("hidden") === true;
$("div").data("options").name === "John";</pre>

<p>Note that strings are left intact while JavaScript values are converted to their associated value (this includes booleans, numbers, objects, arrays, and null). When the data attribute is an object (starts with '{') or array (starts with '[') then <code>jQuery.parseJSON</code> is used to parse the string; it must follow valid JSON syntax <em>including quoted property names</em>. The data- attributes are pulled in the first time the data property is accessed and then are no longer accessed or mutated (all data values are then stored internally in jQuery).</p>
</longdesc>
<example>
    <desc>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"/>
<category name="Data Storage"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="data" return="Object">
  <signature>
    <added>1.2.3</added>
    <argument name="key" type="String">
        <desc>Name of the data stored.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
  </signature>
  <desc>Returns value at named data store for the first element in the jQuery collection, as set by data(name, value).</desc>
  <longdesc>
<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, null is returned.</p>
<p>Calling <code>.data()</code> with no parameters retrieves all of the values as a JavaScript object. This object can be safely cached in a variable as long as a new object is not set with <code>.data(obj)</code>. Using the object directly to get or set values is faster than making individual calls to <code>.data()</code> to get or set each value:</p>
<pre>
var mydata = $("#mydiv").data();
if ( mydata.count &lt; 9 ) {
    mydata.count = 43;
    mydata.status = "embiggened";
}
</pre>
</longdesc>
<example>
      <desc>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"/>
<category name="Data Storage"/>
<category name="Version 1.2.3"/>
<category name="Version 1.4"/>
<category name="Version 1.4.3"/>
</entry>

            <entry type='method' name="get" return="Element, Array">
              <signature>
                <added>1.0</added>
                <argument name="index" type="Number" optional="true">
                   <desc>A zero-based integer indicating which element to retrieve.</desc>
                </argument>
              </signature>
              <desc>Retrieve the DOM elements matched by the jQuery object.</desc>
              <longdesc><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>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>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>Return the number of DOM elements matched by the jQuery object.</desc>
              <longdesc>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><strong>You should use the <a href="/length/">.length</a> property instead, which is slightly faster.</strong></p>
</longdesc>
                <example>
                    <desc>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>A Boolean indicating whether to remove all jQuery variables from the global scope (including jQuery itself).</desc>
                  </argument>
                </signature>
                <desc>Relinquish jQuery's control of the <code>$</code> variable.</desc>
                <longdesc><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>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>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>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>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>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>Selects all elements that are selected.</desc>
                <longdesc><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>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>Matches all elements that are checked.</desc>
                <longdesc><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>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>Selects all elements that are disabled.</desc>
                <longdesc><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>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>Selects all elements that are enabled.</desc>
                <longdesc><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>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>Selects all elements of type file.</desc>
                <longdesc><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>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>Selects all button elements and elements of type button.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>Selects all elements of type reset.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>Selects all elements of type image.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>Selects all elements of type submit.</desc>
                <longdesc><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>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>Selects all elements of type checkbox.</desc>
                <longdesc><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>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>Selects all  elements of type radio.</desc>
                <longdesc><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>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>Selects all elements of type password.</desc>
                <longdesc><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>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>Selects all elements of type text.</desc>
                <longdesc><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>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>Selects all input, textarea, select and button elements.</desc>
                <longdesc><p>The <code>:input</code> selector basically selects all form controls.</p></longdesc>
                <example>
                    <desc>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>Selects all elements that are the only child of their parent.</desc>
                <longdesc><p>If the parent has other child elements, nothing is matched.</p></longdesc>
                <example>
                    <desc>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>Selects all elements that are the last child of their parent.</desc>
                <longdesc><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>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>Selects all elements that are the first child of their parent.</desc>
                <longdesc><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>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>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>Selects all elements that are the nth-child of their parent.</desc>
                <longdesc><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 (n+1)th one (n is 0-based) 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>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>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>An attribute name.</desc>
  </argument>
  <argument name="value" type="String">
      <desc>An attribute value. Quotes are mandatory.</desc>
  </argument> </signature>
  <desc>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><p>This selector was introduced into the CSS specification to handle language attributes.</p></longdesc>
<example>
  <desc>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>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute with a value containing a given word, delimited by spaces.</desc>
                <longdesc><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>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>An attribute filter.</desc>
                </argument>
                <argument name="attributeFilter2" type="Selector">
                    <desc>Another attribute filter, reducing the selection even more</desc>
                </argument>
                <argument name="attributeFilterN" optional="true" type="Selector">
                    <desc>As many more attribute filters as necessary</desc>
                </argument></signature>
                <desc>Matches elements that match all of the specified attribute filters.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>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>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute with a value containing the a given substring.</desc>
                <longdesc><p>This is the most generous of the jQuery attribute selectors that match against a value. It will select an element if the selector's string appears anywhere within the element's attribute value. Compare this selector with the Attribute Contains Word selector (e.g. [attr~="word"]), which is more appropriate in many cases.</p></longdesc>
                <example>
                    <desc>Finds all inputs with a name attribute that contains 'man' and sets the value with some text.</desc>
                    <code><![CDATA[$('input[name*="man"]').val('has man in it!');]]></code>
                    <html><![CDATA[<input name="man-news" />

  <input name="milkman" />
  <input name="letterman2" />
  <input name="newmilk" />]]></html>
                </example>
              <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="attributeEndsWith" return="" >
                <sample>[attribute$="value"]</sample>
                 <signature><added>1.0</added>
                <argument name="attribute" type="String">
                    <desc>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute with a value ending exactly with a given string. The comparison is case sensitive.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>Finds all inputs with an attribute name that ends with 'letter' and puts text in them.</desc>
                    <code><![CDATA[$('input[name$="letter"]').val('a letter');]]></code>
                    <html><![CDATA[<input name="newsletter" />

  <input name="milkman" />
  <input name="jobletter" />]]></html>
                </example>
            <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="attributeStartsWith" return=""  >
                <sample>[attribute^="value"]</sample>
                 <signature><added>1.0</added>
                <argument name="attribute" type="String">
                    <desc>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute with a value beginning exactly with a given string.</desc>
                <longdesc><p>This selector can be useful for identifying elements in pages produced by server-side frameworks that produce HTML with systematic element IDs. However it will be slower than using a class selector so leverage classes, if you can, to group like elements.</p></longdesc>
                <example>
                    <desc>Finds all inputs with an attribute name that starts with 'news' and puts text in them.</desc>
                    <code><![CDATA[$('input[name^="news"]').val('news here!');]]></code>
                    <html><![CDATA[<input name="newsletter" />

  <input name="milkman" />
  <input name="newsboy" />]]></html>
                </example>
            <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="attributeNotEqual" return=""  >
                <sample>[attribute!="value"]</sample>
                 <signature><added>1.0</added>
                <argument name="attribute" type="String">
                    <desc>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Select elements that either don't have the specified attribute, or do have the specified attribute but not with a certain value.</desc>
                <longdesc><p>This selector is equivalent to <code>:not([attr="value"])</code>.</p> </longdesc>
                <example>
                    <desc>Finds all inputs that don't have the name 'newsletter' and appends text to the span next to it.</desc>
                    <code><![CDATA[$('input[name!="newsletter"]').next().append('<b>; not newsletter</b>');]]></code>
                    <html><![CDATA[<div>

    <input type="radio" name="newsletter" value="Hot Fuzz" />
    <span>name is newsletter</span>

  </div>
  <div>
    <input type="radio" value="Cold Fusion" />
    <span>no name</span>

  </div>
  <div>
    <input type="radio" name="accept" value="Evil Plans" />

    <span>name is accept</span>
  </div>]]></html>
                </example>
            <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="attributeEquals" return="" >
                <sample>[attribute="value"]</sample>
                <signature> <added>1.0</added>
                <argument name="attribute" type="String">
                    <desc>An attribute name.</desc>
                </argument>
                <argument name="value" type="String">
                    <desc>An attribute value. Quotes are mandatory.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute with a value exactly equal to a certain value.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>Finds all inputs with name 'newsletter' and changes the text of the span next to it.</desc>
                    <code><![CDATA[$('input[name="newsletter"]').next().text(' is newsletter');]]></code>
                    <html><![CDATA[<div>

    <input type="radio" name="newsletter" value="Hot Fuzz" />
    <span>name?</span>

  </div>
  <div>
    <input type="radio" name="newsletters" value="Cold Fusion" />

    <span>name?</span>
  </div>
  <div>
    <input type="radio" name="accept" value="Evil Plans" />

    <span>name?</span>
  </div>]]></html>
                </example>
            <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="attributeHas" return="" >
                <sample>[attribute]</sample>
                <signature> <added>1.0</added>
                <argument name="attribute" type="String">
                    <desc>An attribute name.</desc>
                </argument></signature>
                <desc>Selects elements that have the specified attribute, with any value. </desc>
                <longdesc></longdesc>
                <example>
                    <desc>Bind a single click that adds the div id to its text.</desc>
                    <code><![CDATA[

    $('div[id]').one('click', function(){
      var idString = $(this).text() + ' = ' + $(this).attr('id');
      $(this).text(idString);
    });
]]></code>
                    <html><![CDATA[<div>no id</div>
  <div id="hey">with id</div>

  <div id="there">has an id</div>
  <div>nope</div>]]></html>
                </example>
            <category name="Attribute"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="visible" return="" >
                <sample>:visible</sample>
                <signature> <added>1.0</added> </signature>
                <desc>Selects all elements that are visible.</desc>
                <longdesc> <p>Elements can be considered hidden for several reasons:</p>
<ul>
<li>They have a CSS <code>display</code> value of <code>none</code>.</li>
<li>They are form elements with <code>type="hidden"</code>.</li>
<li>Their width and height are explicitly set to 0.</li>
<li>An ancestor element is hidden, so the element is not shown on the page.</li>
</ul>
<p>Elements with <code>visibility: hidden</code> or <code>opacity: 0</code> are considered to be visible, since they still consume space in the layout. During animations that hide an element, the element is considered to be visible until the end of the animation. During animations to show an element, the element is considered to be visible at the start at the animation.</p>
<p>How <code>:visible</code> is calculated was changed in jQuery 1.3.2. The <a href="http://docs.jquery.com/Release:jQuery_1.3.2#:visible.2F:hidden_Overhauled">release notes</a> outline the changes in more detail.</p></longdesc>
                <example>
                    <desc>Make all visible divs turn yellow on click.</desc>
                    <code><![CDATA[
    $("div:visible").click(function () {
      $(this).css("background", "yellow");
    });
    $("button").click(function () {
      $("div:hidden").show("fast");
    });

]]></code>
                    <css><![CDATA[
  div { width:50px; height:40px; margin:5px; border:3px outset green; float:left; }
  .starthidden { display:none; }
  ]]></css>
                    <html><![CDATA[<button>Show hidden to see they don't change</button>
  <div></div>
  <div class="starthidden"></div>
  <div></div>

  <div></div>
  <div style="display:none;"></div>]]></html>
                </example>
            <category name="Version 1.0"/>
<category name="Visibility Filter"/>
</entry>
            <entry type='selector'   name="hidden" return="" >
                <sample>:hidden</sample>
                <signature> <added>1.0</added> </signature>
                <desc>Selects all elements that are hidden.</desc>
                <longdesc>
                    <p>Elements can be considered hidden for several reasons:</p>
<ul>
<li>They have a CSS <code>display</code> value of <code>none</code>.</li>
<li>They are form elements with <code>type="hidden"</code>.</li>
<li>Their width and height are explicitly set to 0.</li>
<li>An ancestor element is hidden, so the element is not shown on the page.</li>
</ul>
<p>Elements with <code>visibility: hidden</code> or <code>opacity: 0</code> are considered to be visible, since they still consume space in the layout. During animations that hide an element, the element is considered to be visible until the end of the animation. During animations to show an element, the element is considered to be visible at the start at the animation.</p>
<p>How <code>:hidden</code> is determined was changed in jQuery 1.3.2. An element is assumed to be hidden if it or any of its parents consumes no space in the document. CSS visibility isn't taken into account (therefore <code>$(elem).css('visibility','hidden').is(':hidden') == false</code>). The <a href="http://docs.jquery.com/Release:jQuery_1.3.2#:visible.2F:hidden_Overhauled">release notes</a> outline the changes in more detail.</p></longdesc>
                <example>
                    <desc>Shows all hidden divs and counts hidden inputs.</desc>
                    <code><![CDATA[
    // in some browsers :hidden includes head, title, script, etc... so limit to body
    $("span:first").text("Found " + $(":hidden", document.body).length + 
                         " hidden elements total.");
    $("div:hidden").show(3000);
    $("span:last").text("Found " + $("input:hidden").length + " hidden inputs."); 
]]></code>
                    <css><![CDATA[
  div { width:70px; height:40px; background:#ee77ff; margin:5px; float:left; }
  span { display:block; clear:left; color:red; }
  .starthidden { display:none; }
  ]]></css>
                    <html><![CDATA[<span></span>
  <div></div>
  <div style="display:none;">Hider!</div>
  <div></div>

  <div class="starthidden">Hider!</div>
  <div></div>
  <form>
    <input type="hidden" />

    <input type="hidden" />
    <input type="hidden" />
  </form>
  <span>

  </span>]]></html>
                </example>
            <category name="Version 1.0"/>
<category name="Visibility Filter"/>
</entry>
<entry type='selector' name="parent" return="">
  <sample>:parent</sample>
  <signature><added>1.0</added> </signature>
  <desc>Select all elements that are the parent of another element, including text nodes.</desc>
  <longdesc>
    <p>This is the inverse of <code>:empty</code>. </p>
<p>One important thing to note regarding the use of <code>:parent</code> (and <code>:empty</code>) is that child elements include text nodes.</p>
<p>The W3C recommends that the <code>&lt;p&gt;</code> element have at least one child node, even if that child is merely text (see <a href="http://www.w3.org/TR/html401/struct/text.html#edef-P">http://www.w3.org/TR/html401/struct/text.html#edef-P</a>). Some other elements, on the other hand, are empty (i.e. have no children) by definition:<code> &lt;input&gt;</code>, <code>&lt;img&gt;</code>, <code>&lt;br&gt;</code>, and <code>&lt;hr&gt;</code>, for example.</p>
    
  </longdesc>
    <example>
      <desc>Finds all tds with children, including text.</desc>
      <code><![CDATA[$("td:parent").fadeTo(1500, 0.3);]]></code>
<css><![CDATA[
  td { width:40px; background:green; }
  ]]></css>
<html><![CDATA[<table border="1">

  <tr><td>Value 1</td><td></td></tr>
  <tr><td>Value 2</td><td></td></tr>

</table>]]></html>
    </example>
<category name="Content Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector' name="has" return="">
                <sample>:has(selector)</sample>
                 <signature><added>1.1.4</added>
                    <argument name="selector" type="Selector">
                        <desc>Any selector.</desc>
                    </argument>
                </signature>
                <desc>Selects elements which contain at least one element that matches the specified selector.</desc>
                <longdesc><p>The expression <code>$('div:has(p)')</code> matches a <code>&lt;div&gt;</code> if a <code>&lt;p&gt;</code> exists anywhere among its descendants, not just as a direct child.</p> </longdesc>
                
                <example>
                    <desc>Adds the class "test" to all divs that have a paragraph inside of them.</desc>
                    <code><![CDATA[$("div:has(p)").addClass("test");]]></code>
                    <html><![CDATA[<div><p>Hello in a paragraph</p></div>

  <div>Hello again! (with no paragraph)</div>]]></html>
                    <css><![CDATA[
  .test{ border: 3px inset red; }
  ]]></css>
                </example>
            <category name="Content Filter"/>
<category name="Version 1.1.4"/>
</entry>
            <entry type='selector'   name="empty" return=""  >
                <sample>:empty</sample>
                 <signature><added>1.0</added> </signature>
                <desc>Select all elements that have no children (including text nodes).</desc>
                <longdesc>
<p>This is the inverse of <code>:parent</code>. </p>
<p>One important thing to note with :empty (and :parent) is that child elements include text nodes.</p>
<p>The W3C recommends that the <code>&lt;p&gt;</code> element have at least one child node, even if that child is merely text (see http://www.w3.org/TR/html401/struct/text.html#edef-P). Some other elements, on the other hand, are empty (i.e. have no children) by definition: &lt;input&gt;, &lt;img&gt;, &lt;br&gt;, and &lt;hr&gt;, for example.</p>
</longdesc>
                <example>
                    <desc>Finds all elements that are empty - they don't have child elements or text.</desc>
                    <code><![CDATA[$("td:empty").text("Was empty!").css('background', 'rgb(255,220,200)');]]></code>
                    <css><![CDATA[

  td { text-align:center; }
  ]]></css>
                    <html><![CDATA[<table border="1">
    <tr><td>TD #0</td><td></td></tr>
    <tr><td>TD #2</td><td></td></tr>

    <tr><td></td><td>TD#5</td></tr>
  </table>]]></html>
                </example>
            <category name="Content Filter"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'   name="contains" return="" >
  <sample>:contains(text)</sample>
  <signature>
      <added>1.1.4</added>
      <argument name="text" type="String">
        <desc>A string of text to look for. It's case sensitive.</desc>
      </argument>
  </signature>
  <desc>Select all elements that contain the specified text.</desc>
  <longdesc><p>The matching text can appear directly within the selected element, in any of that element's descendants, or a combination thereof. As with attribute value selectors, text inside the parentheses of <code>:contains()</code> can be written as bare words or surrounded by quotation marks. The text must have matching case to be selected.</p></longdesc>
  
  <example>
    <desc>Finds all divs containing "John" and underlines them.</desc>
    <code><![CDATA[
$("div:contains('John')").css("text-decoration", "underline");]]>
    </code>
    <html><![CDATA[
<div>John Resig</div>

<div>George Martin</div>
<div>Malcom John Sinclair</div>
<div>J. Ohn</div>
      ]]>
    </html>
  </example>
<category name="Content Filter"/>
<category name="Version 1.1.4"/>
</entry>
            <entry type='selector' name="animated" return="">
                <sample>:animated</sample>
                <signature><added>1.2</added></signature>
                <desc>Select all elements that are in the progress of an animation at the time the selector is run.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>Change the color of any div that is animated.</desc>
                    <code><![CDATA[

    $("#run").click(function(){
      $("div:animated").toggleClass("colored");
    });
    function animateIt() {
      $("#mover").slideToggle("slow", animateIt);
    }
    animateIt();
]]></code>
                    <html><![CDATA[<button id="run">Run</button>

  <div></div>
  <div id="mover"></div>
  <div></div>]]></html>
                    <css><![CDATA[
  div { background:yellow; border:1px solid #AAA; width:80px; height:80px; margin:0 5px; float:left; }
  div.colored { background:green; }
  ]]></css>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.2"/>
</entry>
            <entry type='selector'  name="header" return=""  >
                <sample>:header</sample>
                 <signature><added>1.2</added> </signature>
                <desc>Selects all elements that are headers, like h1, h2, h3 and so on.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>Adds a background and text color to all the headers on the page.</desc>
                    <code><![CDATA[$(":header").css({ background:'#CCC', color:'blue' });]]></code>
                    <html><![CDATA[<h1>Header 1</h1>

  <p>Contents 1</p>
  <h2>Header 2</h2>
  <p>Contents 2</p>]]></html>
                    <css><![CDATA[
  body { font-size: 10px; font-family: Arial; } 
  h1, h2 { margin: 3px 0; }
  ]]></css>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.2"/>
</entry>
<entry type='selector'   name="lt" return="" >
  <sample>:lt(index)</sample>
   <signature>
      <added>1.0</added> 
      <argument name="index" type="Number">
          <desc>Zero-based index.</desc>
      </argument>
    </signature>
    <desc>Select all elements at an index less than <code>index</code> within the matched set.</desc>
    <longdesc><p><strong>index-related selectors</strong></p>
      <p>The index-related selectors (including this "less than" selector) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (<code>.myclass</code>) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.</p>
    <p>Note that since JavaScript arrays use <em>0-based indexing</em>, these selectors reflect that fact. This is why <code>$('.myclass:lt(1)')</code> selects the first element in the document with the class <code>myclass</code>, rather than selecting no elements. In contrast, <code>:nth-child(n)</code> uses <em>1-based indexing</em> to conform to the CSS specification.</p>
    </longdesc>

<example>
    <desc>Finds TDs less than the one with the 4th index (TD#4).</desc>
    <code><![CDATA[$("td:lt(4)").css("color", "red");]]></code>
    <html><![CDATA[<table border="1">

  <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
  <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>

  <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
</table>]]></html>
  </example>
<category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="gt" return="" >
                <sample>:gt(index)</sample>
                 <signature><added>1.0</added>
                <argument name="index" type="Number">
                    <desc>Zero-based index.</desc>
                </argument>
               </signature>
                <desc>Select all elements at an index greater than <code>index</code> within the matched set.</desc>
                <longdesc><p><strong>index-related selectors</strong></p>
                  <p>The index-related selector expressions (including this "greater than" selector) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (<code>.myclass</code>) and four elements are returned, these elements are given indices 0 through 3 for the purposes of these selectors.</p>
                <p>Note that since JavaScript arrays use <em>0-based indexing</em>, these selectors reflect that fact. This is why <code>$('.myclass:gt(1)')</code> selects elements after the second element in the document with the class <code>myclass</code>, rather than after the first. In contrast, <code>:nth-child(n)</code> uses <em>1-based indexing</em> to conform to the CSS specification.</p>
                </longdesc>

                <example>
                    <desc>Finds TD #5 and higher. Reminder: the indexing starts at 0.</desc>
                    <code><![CDATA[$("td:gt(4)").css("text-decoration", "line-through");]]></code>
                    <html><![CDATA[<table border="1">

    <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
    <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>

    <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
  </table>]]></html>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector' name="eq" return="">
                <sample>:eq(index)</sample>
                <signature>
                  <added>1.0</added>
                  <argument name="index" type="Number">
                      <desc>Zero-based index of the element to match.</desc>
                  </argument>
                </signature>
                <desc>Select the element at index <code>n</code> within the matched set.</desc>
                <longdesc><p>The index-related selectors (<code>:eq()</code>, <code>:lt()</code>, <code>:gt()</code>, <code>:even</code>, <code>:odd</code>) filter the set of elements that have matched the expressions that precede them. They narrow the set down based on the order of the elements within this matched set. For example, if elements are first selected with a class selector (<code>.myclass</code>) and four elements are returned, these elements are given indices <code>0</code> through <code>3</code> for the purposes of these selectors.</p>
<p>Note that since JavaScript arrays use <em>0-based indexing</em>, these selectors reflect that fact. This is why <code>$('.myclass:eq(1)')</code> selects the second element in the document with the class myclass, rather than the first. In contrast, <code>:nth-child(n)</code> uses <em>1-based indexing</em> to conform to the CSS specification.</p>
</longdesc>
  <example>
      <desc>Finds the third td.</desc>
      <code><![CDATA[$("td:eq(2)").css("color", "red");]]></code>
      <html><![CDATA[<table border="1">
  <tr><td>TD #0</td><td>TD #1</td><td>TD #2</td></tr>
  <tr><td>TD #3</td><td>TD #4</td><td>TD #5</td></tr>
  <tr><td>TD #6</td><td>TD #7</td><td>TD #8</td></tr>
</table>]]></html>
  </example>
<category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="odd" return="" >
                <sample>:odd</sample>
                 <signature><added>1.0</added> </signature>
                <desc>Selects odd elements, zero-indexed.  See also <a href="/Selectors/even">even</a>.</desc>
                <longdesc><p>In particular, note that the <em>0-based indexing</em> means that, counter-intuitively, <code>:odd</code> selects the second element, fourth element, and so on within the matched set.</p></longdesc>
                <example>
                    <desc>Finds odd table rows, matching the second, fourth and so on (index 1, 3, 5 etc.).</desc>
                    <code><![CDATA[$("tr:odd").css("background-color", "#bbbbff");]]></code>
                    <css><![CDATA[

  table {
    background:#f3f7f5;
  }
  ]]></css>
                    <html><![CDATA[<table border="1">
    <tr><td>Row with Index #0</td></tr>
    <tr><td>Row with Index #1</td></tr>

    <tr><td>Row with Index #2</td></tr>
    <tr><td>Row with Index #3</td></tr>
  </table>]]></html>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="even" return="" >
                <sample>:even</sample>
                 <signature><added>1.0</added> </signature>
                <desc>Selects even elements, zero-indexed.  See also <a href="/Selectors/odd">odd</a>.</desc>
                <longdesc><p>In particular, note that the <em>0-based indexing</em> means that, counter-intuitively, <code>:even</code> selects the first element, third element, and so on within the matched set.</p></longdesc>
                <example>
                    <desc>Finds even table rows, matching the first, third and so on (index 0, 2, 4 etc.).</desc>
                    <code><![CDATA[$("tr:even").css("background-color", "#bbbbff");]]></code>
                    <css><![CDATA[

  table {
    background:#eeeeee;
  }
  ]]></css>
                    <html><![CDATA[<table border="1">
    <tr><td>Row with Index #0</td></tr>
    <tr><td>Row with Index #1</td></tr>

    <tr><td>Row with Index #2</td></tr>
    <tr><td>Row with Index #3</td></tr>
  </table>]]></html>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'  name="not" return=""  >
    <sample>:not(selector)</sample>
    <signature>
      <added>1.0</added> 
      <argument name="selector" type="Selector">
          <desc>A selector with which to filter by.</desc>
      </argument>
    </signature>
    <desc>Selects all elements that do not match the given selector.</desc>
    <longdesc><p>All selectors are accepted inside <code>:not()</code>,  for example: <code>:not(div a)</code> and <code>:not(div,a)</code>.</p> <h3>Additional Notes</h3><p>The <code><a href="/not/">.not()</a></code> method will end up providing you with more readable selections than pushing complex selectors or variables into a <code>:not()</code> selector filter. In most cases, it is a better choice.</p></longdesc>
    <example>
        <desc>Finds all inputs that are not checked and highlights the next sibling span.  Notice there is no change when clicking the checkboxes since no click events have been linked.</desc>
        <code><![CDATA[
  $("input:not(:checked) + span").css("background-color", "yellow");
  $("input").attr("disabled", "disabled");

]]></code>
                  <html><![CDATA[<div>
  <input type="checkbox" name="a" />
  <span>Mary</span>
</div>

<div>
  <input type="checkbox" name="b" />
  <span>lcm</span>

</div>
<div>
  <input type="checkbox" name="c" checked="checked" />

  <span>Peter</span>
</div>]]></html>
    </example>
<category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'   name="last" return=""  >
                <sample>:last</sample>
                 <signature><added>1.0</added> </signature>
                <desc>Selects the last matched element.</desc>
                <longdesc><p>Note that <code>:last</code> selects a single element by filtering  the current jQuery collection and matching the last element within it.</p></longdesc>
                <example>
                    <desc>Finds the last table row.</desc>
                    <code><![CDATA[$("tr:last").css({backgroundColor: 'yellow', fontWeight: 'bolder'});]]></code>
                    <html><![CDATA[<table>

    <tr><td>First Row</td></tr>
    <tr><td>Middle Row</td></tr>
    <tr><td>Last Row</td></tr>

  </table>]]></html>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="first" return="" >
                <sample>:first</sample>
                 <signature><added>1.0</added> </signature>
                <desc>Selects the first matched element.</desc>
                <longdesc><p>The <code>:first</code> pseudo-class is equivalent to <code>:eq(0)</code>. It could also be written as <code>:lt(1)</code>. While this matches only a single element, <a href='first-child-selector'>:first-child</a> can match more than one: One for each parent.</p></longdesc>
                <example>
                    <desc>Finds the first table row.</desc>
                    <code><![CDATA[$("tr:first").css("font-style", "italic");]]></code>
                    <css><![CDATA[

  td { color:blue; font-weight:bold; }
  ]]></css>
                    <html><![CDATA[<table>
    <tr><td>Row 1</td></tr>
    <tr><td>Row 2</td></tr>

    <tr><td>Row 3</td></tr>
  </table>]]></html>
                </example>
            <category name="Basic Filter"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'   name="next siblings" return=""  >
    <sample>prev ~ siblings</sample>
    <signature>
      <added>1.0</added>
      <argument name="prev" type="Selector">
          <desc>Any valid selector.</desc>
      </argument>
      <argument name="siblings" type="Selector">
          <desc>A selector to filter elements that are the following siblings of the first selector.</desc>
      </argument>
    </signature>
    <desc>Selects all sibling elements that follow after the "prev" element, have the same parent, and match the filtering "siblings" selector.</desc>
    <longdesc><p>The notable difference between (<code>prev + next</code>) and (<code>prev ~ siblings</code>) is their respective reach. While the former reaches only to the immediately following sibling element, the latter extends that reach to all following sibling elements.</p></longdesc>
    <example>
        <desc>Finds all divs that are siblings after the element with #prev as its id.  Notice the span isn't selected since it is not a div and the "niece" isn't selected since it is a child of a sibling, not an actual sibling.</desc>
        <code><![CDATA[$("#prev ~ div").css("border", "3px groove blue");]]></code>
        <css><![CDATA[

  div,span {
    display:block;
    width:80px;
    height:80px;
    margin:5px;
    background:#bbffaa;
    float:left;
    font-size:14px;
  }
  div#small {
    width:60px;
    height:25px;
    font-size:12px;
    background:#fab;
  }
  ]]></css>
                    <html><![CDATA[<div>div (doesn't match since before #prev)</div>
  <span id="prev">span#prev</span>
  <div>div sibling</div>

  <div>div sibling <div id="small">div niece</div></div>
  <span>span sibling (not div)</span>
  <div>div sibling</div>]]></html>
                </example>
            <category name="Hierarchy"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="next adjacent" return="" >
                <sample>prev + next</sample>
                 <signature>
                   <added>1.0</added>
                   <argument name="prev" type="Selector">
                       <desc>Any valid selector.</desc>
                   </argument>
                <argument name="next" type="Selector">
                    <desc>A selector to match the element that is next to the first selector.</desc>
                </argument>
                  </signature>
                <desc>Selects all next elements matching "next" that are immediately preceded by a sibling "prev".</desc>
                <longdesc>
<p>One important point to consider with both the next adjacent sibling selector (<code>prev + next</code>) and the general sibling selector (<code>prev ~ siblings</code>) is that the elements on either side of the combinator must share the same parent.</p></longdesc>
                <example>
                    <desc>Finds all inputs that are next to a label.</desc>
                    <code><![CDATA[$("label + input").css("color", "blue").val("Labeled!")]]></code>
                    <html><![CDATA[<form>

    <label>Name:</label>
    <input name="name" />
    <fieldset>
      <label>Newsletter:</label>

      <input name="newsletter" />
    </fieldset>
  </form>
  <input name="none" />]]></html>
                </example>
            <category name="Hierarchy"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'  name="child" return="" >
    <sample>parent &gt; child</sample>
   <signature>
     <added>1.0</added>
     <argument name="parent" type="Selector">
         <desc>Any valid selector.</desc>
     </argument>
     <argument name="child" type="Selector">
         <desc>A selector to filter the child elements.</desc>
     </argument>
    </signature>
    <desc>Selects all direct child elements specified by "child" of elements specified by "parent".</desc>
    <longdesc><p>As a CSS selector, the child combinator is supported by all modern web browsers including Safari, Firefox, Opera, Chrome, and Internet Explorer 7 and above, but notably not by Internet Explorer versions 6 and below. However, in jQuery, this selector (along with all others) works across all supported browsers, including IE6.</p>
    <p>The child combinator (E <strong>&gt;</strong> F) can be thought of as a more specific form of the descendant combinator (E F) in that it selects only first-level descendants.</p></longdesc>
    <example>
        <desc>Places a border around all list items that are children of &lt;ul class="topnav"&gt; .</desc>
        <code><![CDATA[$("ul.topnav > li").css("border", "3px double red");]]></code>
        <css><![CDATA[
body { font-size:14px; }
]]></css>
        <html><![CDATA[
                    
<ul class="topnav">
    <li>Item 1</li>
    <li>Item 2 
        <ul><li>Nested item 1</li><li>Nested item 2</li><li>Nested item 3</li></ul>
       </li>
    <li>Item 3</li>
</ul>
]]></html>
    </example>
<category name="Hierarchy"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'  name="descendant" return=""  >
    <sample>ancestor descendant</sample>
    <signature> 
      <added>1.0</added>
      <argument name="ancestor" type="Selector">
          <desc>Any valid selector.</desc>
      </argument>
      <argument name="descendant" type="Selector">
          <desc>A selector to filter the descendant elements.</desc>
      </argument>
    </signature>
    <desc>Selects all elements that are descendants of a given ancestor.</desc>
    <longdesc><p>A descendant of an element could be a child, grandchild, great-grandchild, and so on, of that element.</p></longdesc>
    <example>
        <desc>Finds all input descendants of forms.</desc>
        <code><![CDATA[$("form input").css("border", "2px dotted blue");]]></code>
        <css><![CDATA[

  body { font-size:14px; }
  form { border:2px green solid; padding:2px; margin:0; 
         background:#efe; }
  div { color:red; }
  fieldset { margin:1px; padding:3px; }
  ]]></css>
                    <html><![CDATA[<form>
    <div>Form is surrounded by the green outline</div>
    <label>Child:</label>
    <input name="name" />

    <fieldset>
      <label>Grandchild:</label>
      <input name="newsletter" />
    </fieldset>

  </form>
  Sibling to form: <input name="none" />]]></html>
    </example>
<category name="Hierarchy"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector' name="multiple" return=""  >
    <sample>selector1, selector2, selectorN</sample>
     <signature>
        <added>1.0</added>
        <argument name="selector1" type="Selector">
          <desc>Any valid selector.</desc>
        </argument>
        <argument name="selector2" type="Selector">
          <desc>Another valid selector.</desc>
        </argument>
        <argument name="selectorN" optional="true" type="Selector">
          <desc>As many more valid selectors as you like.</desc>
        </argument>
      </signature>
    <desc>Selects the combined results of all the specified selectors.</desc>
    <longdesc><p>You can specify any number of selectors to combine into a single result.  This multiple expression combinator is an efficient way to select disparate elements. The order of the DOM elements in the returned jQuery object may not be identical, as they will be in document order. An alternative to this combinator is the .<a href="/add">add()</a> method.</p></longdesc>
    <example>
      <desc>Finds the elements that match any of these three selectors.</desc>
      <code><![CDATA[$("div,span,p.myClass").css("border","3px solid red");]]></code>
      <html><![CDATA[<div>div</div>

  <p class="myClass">p class="myClass"</p>
  <p class="notMyClass">p class="notMyClass"</p>
  <span>span</span>]]></html>
  <css><![CDATA[

  div,span,p {
    width: 126px;
    height: 60px;
    float:left;
    padding: 3px;
    margin: 2px;
    background-color: #EEEEEE;
    font-size:14px;
  }
  ]]></css>
</example>
<example>
<desc>Show the order in the jQuery object.</desc>
<code><![CDATA[
    var list = $("div,p,span").map(function () {
      return this.tagName;
    }).get().join(", ");
    $("b").append(document.createTextNode(list));
]]></code>
                    <css><![CDATA[
  b { color:red; font-size:16px; display:block; clear:left; }
  div,span,p { width: 40px; height: 40px; float:left;
               margin: 10px; background-color: blue; 
               padding:3px; color:white; 
             }
  ]]></css>
  <html><![CDATA[<span>span</span>

  <p>p</p>
  <p>p</p>
  <div>div</div>
  <span>span</span>

  <p>p</p>
  <div>div</div>
  <b></b>]]></html>
    </example>
<category name="Basic"/>
<category name="Version 1.0"/>
</entry>
<entry type='selector'  name="all" return=""  >
    <sample>*</sample>
    <signature>  
      <added>1.0</added> 
    </signature>
    <desc>Selects all elements.</desc>
    <longdesc><p>Caution: The all, or universal, selector is extremely slow, except when used by itself.</p> </longdesc>
    <example>
      <desc>Finds every element (including head, body, etc) in the document.</desc>
      <code><![CDATA[var elementCount = $("*").css("border","3px solid red").length;
$("body").prepend("<h3>" + elementCount + " elements found</h3>");]]></code>
      <html><![CDATA[<div>DIV</div>

  <span>SPAN</span>
  <p>P <button>Button</button></p>]]></html>
                    <css><![CDATA[
  h3 { margin: 0; }
  div,span,p {
    width: 80px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  ]]></css>
    </example>
    <example>
        <desc>A common way to select all elements is to find within document.body so elements like head, script, etc are left out.</desc>
      <code><![CDATA[
var elementCount = $("#test").find("*").css("border","3px solid red").length;
$("body").prepend("<h3>" + elementCount + " elements found</h3>");]]></code>
<html><![CDATA[<div id="test">
  <div>DIV</div>
  <span>SPAN</span>
  <p>P <button>Button</button></p>
</div>]]></html>
<css><![CDATA[
  h3 { margin: 0; }
  div,span,p {
    width: 80px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  #test {
    width: auto; height: auto; background-color: transparent; 
  }
  ]]></css>
        
    </example>
<category name="Basic"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="class" return=""  >
                <sample>.class</sample>
                <signature> <added>1.0</added>
                <argument name="class" type="String">
                    <desc>A class to search for. An element can have multiple classes; only one of them must match.</desc>
                </argument></signature>
                <desc>Selects all elements with the given class. </desc>
                <longdesc><p>For class selectors, jQuery uses JavaScript's native <code>getElementsByClassName()</code> function if the browser supports it.</p>
                
</longdesc>
                <example>
                    <desc>Finds the element with the class "myClass".</desc>
                    <code><![CDATA[$(".myClass").css("border","3px solid red");]]></code>
                    <html><![CDATA[<div class="notMe">div class="notMe"</div>

  <div class="myClass">div class="myClass"</div>
  <span class="myClass">span class="myClass"</span>]]></html>
                    <css><![CDATA[
  div,span {
    width: 100px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  ]]></css>
                </example>
                <example>
                    <desc>Finds the element with both "myclass" and "otherclass" classes.</desc>
                    <code><![CDATA[$(".myclass.otherclass").css("border","13px solid red");]]></code>
                    <html><![CDATA[<div class="myclass">div class="notMe"</div>

  <div class="myclass otherclass">div class="myClass"</div>
  <span class="myclass otherclass">span class="myClass"</span>]]></html>
                    <css><![CDATA[
  div,span {
    width: 100px;
    height: 40px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  ]]></css>
                </example>
            <category name="Basic"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="element" return="" >
                <sample>element</sample>
                 <signature>
                    <added>1.0</added>
                    <argument name="element" type="String">
                    <desc>An element to search for. Refers to the tagName of DOM nodes.</desc>
                </argument>
                </signature>
                <desc>Selects all elements with the given tag name.</desc>
                <longdesc><p>JavaScript's <code>getElementsByTagName()</code> function is called to return the appropriate elements when this expression is used.</p> </longdesc>
                
                <example>
                    <desc>Finds every DIV element.</desc>
                    <code><![CDATA[$("div").css("border","9px solid red");]]></code>
                    <html><![CDATA[<div>DIV1</div>

  <div>DIV2</div>
  <span>SPAN</span>]]></html>
                    <css><![CDATA[
  div,span {
    width: 60px;
    height: 60px;
    float:left;
    padding: 10px;
    margin: 10px;
    background-color: #EEEEEE;
  }
  ]]></css>
                </example>
            <category name="Basic"/>
<category name="Version 1.0"/>
</entry>
            <entry type='selector'  name="id" return="" >
                <sample>#id</sample>
                <signature>
                  <added>1.0</added> 
                   <argument name="id" type="String">
                      <desc>An ID to search for, specified via the id attribute of an element.</desc>
                   </argument>
                </signature>
                <desc>Selects a single element with the given id attribute. </desc>
                <longdesc>
                   <p>For id selectors, jQuery uses the JavaScript function <code>document.getElementById()</code>, which is extremely efficient. When another selector is attached to the id selector, such as <code>h2#pageTitle</code>, jQuery performs an additional check before identifying the element as a match.</p>
                   <blockquote><p>As always, remember that as a developer, your time is typically the most valuable resource. Do not focus on optimization of selector speed unless it is clear that performance needs to be improved.</p></blockquote>
                   <p>Each <code>id</code> value must be used only once within a document. If more than one element has been assigned the same ID, queries that use that ID will only select the first matched element in the DOM. This behavior should not be relied on, however; a document with more than one element using the same ID is invalid.</p>
                <p>If the id contains characters like periods or colons you have to <a href="http://docs.jquery.com/Frequently_Asked_Questions#How_do_I_select_an_element_by_an_ID_that_has_characters_used_in_CSS_notation.3F">escape those characters with backslashes</a>.</p>
                </longdesc>
               
                <example>
                    <desc>Finds the element with the id "myDiv".</desc>
                    <code><![CDATA[$("#myDiv").css("border","3px solid red");]]></code>
                    <html><![CDATA[<div id="notMe"><p>id="notMe"</p></div>

  <div id="myDiv">id="myDiv"</div>]]></html>
                    <css><![CDATA[
  div {
    width: 90px;
    height: 90px;
    float:left;
    padding: 5px;
    margin: 5px;
    background-color: #EEEEEE;
  }
  ]]></css>
                </example>
                <example>
                    <desc>Finds the element with the id "myID.entry[1]".  See how certain characters must be escaped with backslashes.</desc>
                    <code><![CDATA[$("#myID\\.entry\\[1\\]").css("border","3px solid red");]]></code>
                    <html><![CDATA[<div id="myID.entry[0]">id="myID.entry[0]"</div>

  <div id="myID.entry[1]">id="myID.entry[1]"</div>
  <div id="myID.entry[2]">id="myID.entry[2]"</div>]]></html>
                    <css><![CDATA[
  div {
    width: 300px;
    float:left;
    padding: 2px;
    margin: 3px;
    background-color: #EEEEEE;
  }
  ]]></css>
                </example>
            <category name="Basic"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="scroll" return="jQuery">
  <desc>Bind an event handler to the "scroll" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('scroll', handler)</code> in the first variation, and <code>.trigger('scroll')</code> in the second.</p>
<p>The <code>scroll</code> event is sent to an element when the user scrolls to a different place in the element. It applies to <code>window</code> objects, but also to scrollable frames and elements with the <code>overflow </code>CSS property set to <code>scroll</code> (or <code>auto</code> when the element's explicit height is less than the height of its contents).</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="target" style="overflow: scroll; width: 200px; height: 100px;"&gt;
  Lorem ipsum dolor sit amet, consectetur adipisicing elit,
  sed do eiusmod tempor incididunt ut labore et dolore magna
  aliqua. Ut enim ad minim veniam, quis nostrud exercitation
  ullamco laboris nisi ut aliquip ex ea commodo consequat.
  Duis aute irure dolor in reprehenderit in voluptate velit
  esse cillum dolore eu fugiat nulla pariatur. Excepteur
  sint occaecat cupidatat non proident, sunt in culpa qui
  officia deserunt mollit anim id est laborum.
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre>
<p>The style definition is present to make the target element small enough to be scrollable:</p>
 
<p class="image"><img src="/images/0042_05_11.png" alt="" />
</p>
<p>The <code>scroll</code> event handler can be bound to this element:</p>
<pre>$('#target').scroll(function() {
  $('#log').append('&lt;div&gt;Handler for .scroll() called.&lt;/div&gt;');
});</pre>
<p>Now when the user scrolls the text up or down, one or more messages are appended to <code>&lt;div id="log"&gt;&lt;/div&gt;</code>:</p>
<p><span class="output">Handler for .scroll() called.</span></p>
<p>We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').scroll();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also append the message.</p>
<p>A <code>scroll</code> event is sent whenever the element's scroll position changes, regardless of the cause. A mouse click or drag on the scroll bar, dragging inside the element, pressing the arrow keys, or using the mouse's scroll wheel could cause this event.</p>
</longdesc>
                <example>
                    <desc>To do something when your page is scrolled:</desc>
                    <code><![CDATA[
    $("p").clone().appendTo(document.body);
    $("p").clone().appendTo(document.body);
    $("p").clone().appendTo(document.body);
    $(window).scroll(function () { 
      $("span").css("display", "inline").fadeOut("slow"); 
    });

]]></code>
                    <css><![CDATA[
  div { color:blue; }
  p { color:green; }
  span { color:red; display:none; }
  ]]></css>
                    <html><![CDATA[<div>Try scrolling the iframe.</div>
  <p>Paragraph - <span>Scroll happened!</span></p>]]></html>
                </example>

<category name="Browser Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="resize" return="jQuery">
  <desc>Bind an event handler to the "resize" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('resize', handler)</code> in the first variation, and <code>.trigger('resize')</code> in the second.</p>
<p>The <code>resize</code> event is sent to the <code>window</code> element when the size of the browser window changes:</p>
<pre>$(window).resize(function() {
  $('#log').append('&lt;div&gt;Handler for .resize() called.&lt;/div&gt;');
});
</pre>
<p>Now whenever the browser window's size is changed, the message is appended to &lt;div id="log"&gt; one or more times, depending on the browser.</p>
<p>Code in a <code>resize</code> handler should never rely on the number of times the handler is called. Depending on implementation, <code>resize</code> events can be sent continuously as the resizing is in progress (the typical behavior in Internet Explorer and WebKit-based browsers such as Safari and Chrome), or only once at the end of the resize operation (the typical behavior in Firefox).</p>
</longdesc>
<example>
  <desc>To see the window width while (or after) it is resized, try:</desc>
  <code><![CDATA[
$(window).resize(function() {
  $('body').prepend('<div>' + $(window).width() + '</div>');
});]]>
  </code>
</example>
<category name="Browser Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="dequeue" return="jQuery">
  <signature>
    <added>1.2</added>
    <argument name="queueName" optional="true" type="String">
      <desc>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
    </argument>
  </signature>
  <desc>Execute the next function on the queue for the matched elements.</desc>
  <longdesc><p>When <code>.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>.dequeue()</code> to be called, so that the sequence can continue.</p></longdesc>
  <example>
    <desc>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");
    $(this).dequeue();
  });
  $("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="Custom"/>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2"/>
</entry>

    <entry type='method' name="queue" return="Array">
				<signature>
                	<added>1.2</added>
	                <argument name="queueName" optional="true" type="String">
	                    <desc>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
	                </argument>
				</signature>
				<desc>Show the queue of functions to be executed on the matched elements.</desc>
				<longdesc></longdesc>
                <example>
                    <desc>Show the length of the queue.</desc>
                    <code><![CDATA[$("#show").click(function () {
      var n = $("div").queue("fx");
      $("p").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:60px; 
        background:green; display:none; }
  div.newcolor { background:blue; }
  p { color:red; }  ]]></css>
                    <html><![CDATA[<button id="show">Show Length of Queue</button>
  <p></p>
  <div></div>]]></html>
  </example>
<category name="Custom"/>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2"/>
</entry>
<entry type='method' name="queue" return="jQuery">
  <signature>
    <added>1.2</added>
    <argument name="queueName" optional="true" type="String">
      <desc>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>An array of functions to replace the current queue contents.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.2</added>
    <argument name="queueName" optional="true" type="String">
      <desc>A string containing the name of the queue. Defaults to <code>fx</code>, the standard effects queue.</desc>
    </argument>
    <argument name="callback( next )" type="Function">
      <desc>The new function to add to the queue, with a function to call that will dequeue the next item.</desc>
    </argument>
  </signature>
  <desc>Manipulate the queue of functions to be executed on the matched elements.</desc>
  <longdesc><p>Every element can have one to many 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. The typical example of this is calling multiple animation methods on an element. For example:</p>
				<pre>$('#foo').slideUp().fadeIn();</pre>
				<p>When this statement is executed, the element begins its sliding animation immediately, but the fading transition is placed on the <code>fx</code> queue to be called only once the sliding transition is complete.</p>
				<p>The <code>.queue()</code> method allows us to directly manipulate this queue of functions. Calling <code>.queue()</code> with a callback is particularly useful; it allows us to place a new function at the end of the queue.</p>
				<p>This feature is similar to providing a callback function with an animation method, but does not require the callback to be given at the time the animation is performed.</p>
<pre>$('#foo').slideUp();
$('#foo').queue(function() {
  alert('Animation complete.');
  $(this).dequeue();
});</pre>
<p>This is equivalent to:</p>
<pre>$('#foo').slideUp(function() {
  alert('Animation complete.');
});</pre>
<p>Note that when adding a function with <code>.queue()</code>, we should ensure that <code>.dequeue()</code> is eventually called so that the next function in line executes.</p>
<p>In jQuery 1.4 the function that's called is passed in another function, as the first argument, that when called automatically dequeues the next item and keeps the queue moving. You would use it like so:</p>
<pre>$("#test").queue(function(next) {
    // Do some stuff...
    next();
});</pre></longdesc>
  <example>
    <desc>Queue a custom function.</desc>
    <code><![CDATA[$(document.body).click(function () {
      $("div").show("slow");
      $("div").animate({left:'+=200'},2000);
      $("div").queue(function () {
        $(this).addClass("newcolor");
        $(this).dequeue();
      });
      $("div").animate({left:'-=200'},500);
      $("div").queue(function () {
        $(this).removeClass("newcolor");
        $(this).dequeue();
      });
      $("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>Set a queue array to delete 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").queue("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="Custom"/>
<category name="Data"/>
<category name="Utilities"/>
<category name="Version 1.2"/>
</entry>

<entry type='method' name="keyup" return="jQuery">
  <desc>Bind an event handler to the "keyup" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('keyup', handler)</code> in the first variation, and <code>.trigger('keyup')</code> in the second.</p>
<p>The <code>keyup</code> event is sent to an element when the user releases 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').keyup(function() {
  alert('Handler for .keyup() called.');
});
</pre>
<p>Now when the insertion point is inside the field and a key is pressed and released, the alert is displayed:</p>
<p><span class="output">Handler for .keyup() called.</span></p>
<p>We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').keyup();
});</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 attributes to store this information, jQuery normalizes the <code>.which</code> attribute 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>Show the event object for the keyup handler when a key is released in the input.</desc>
    <code><![CDATA[
var xTriggered = 0;
$('#target').keyup(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keyup() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keyup();
});]]></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"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="keypress" return="jQuery">
  <desc>Bind an event handler to the "keypress" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('keypress', handler)</code> in the first variation, and <code>.trigger('keypress')</code> in the second.</p>
<p>The <code>keypress</code> event is sent to an element when the browser registers keyboard input. This is similar to the <code>keydown</code> event, except in the case of key repeats. If the user presses and holds a key, a <code>keydown </code>event is triggered once, but separate <code>keypress</code> events are triggered for each inserted character. In addition, modifier keys (such as Shift) cause <code>keydown</code> events but not <code>keypress</code> events.</p>
<p>A <code>keypress</code> event handler 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;fieldset&gt;
  	&lt;input id="target" type="text" value="Hello there" /&gt;
	&lt;/fieldset&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').keypress(function() {
  alert('Handler for .keypress() 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 .keypress() called.</span></p>
<p>The message repeats if the key is held down. We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').keypress();
});</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 character was entered, we can examine the event object that is passed to the handler function. While browsers use differing attributes to store this information, jQuery normalizes the <code>.which</code> attribute so we can reliably use it to retrieve the character code.</p>
<p>Note that <code>keydown</code> and <code>keyup</code> provide a code indicating which key is pressed, while <code>keypress</code> indicates which character was entered. For example, a lowercase "a" will be reported as 65 by <code>keydown</code> and <code>keyup</code>, but as 97 by <code>keypress</code>. An uppercase "A" is reported as 65 by all events. Because of this distinction, when catching special keystrokes such as arrow keys, <code>.keydown()</code> or <code>.keyup()</code> is a better choice.</p>
</longdesc>
<example>
    <desc>Show the event object for the keypress handler when a key is pressed in the input.</desc>
    <code><![CDATA[
var xTriggered = 0;
$('#target').keypress(function(event) {
  if (event.keyCode == '13') {
     event.preventDefault();
   }
   xTriggered++;
   var msg = 'Handler for .keypress() called ' + xTriggered + ' time(s).';
  $.print(msg, 'html');
  $.print(event);
});

$('#other').click(function() {
  $('#target').keypress();
});]]></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"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="submit" return="jQuery">
  <desc>Bind an event handler to the "submit" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('submit', handler)</code> in the first variation, and <code>.trigger('submit')</code> in the second.</p>
<p>The <code>submit</code> event is sent to an element when the user is attempting to submit a form. It can only be attached to <code>&lt;form&gt;</code> elements. Forms can be submitted either by clicking an explicit <code>&lt;input type="submit"&gt;</code>, <code>&lt;input type="image"&gt;</code>, or <code>&lt;button type="submit"&gt;</code>, or by pressing <kbd>Enter</kbd> when certain form element has focus.</p>
<blockquote><p>Depending on the browser, the Enter key may only cause a form submission if the form has exactly one text field, or only when there is a submit button present. The interface should not rely on a particular behavior for this key unless the issue is forced by observing the keypress event for presses of the Enter key.</p></blockquote>
<p>For example, consider the HTML:</p>
<pre>&lt;form id="target" action="destination.html"&gt;
  &lt;input type="text" value="Hello there" /&gt;
  &lt;input type="submit" value="Go" /&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 form:</p>
<pre>$('#target').submit(function() {
  alert('Handler for .submit() called.');
  return false;
});</pre>
<p>Now when the form is submitted, the message is alerted. This happens prior to the actual submission, so we can cancel the submit action by calling <code>.preventDefault()</code> on the event object or by returning <code>false</code> from our handler. We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').submit();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also display the message. In addition, the default <code>submit</code> action on the form will be fired, so the form will be submitted.</p>
<p>The JavaScript <code>submit</code> event does not bubble in Internet Explorer. However, scripts that rely on event delegation with the <code>submit</code> event will work consistently across browsers as of jQuery 1.4, which has normalized the event's behavior. </p>

</longdesc>
                <example>
                    <desc>If you'd like to prevent forms from being submitted unless a flag variable is set, try:</desc>
                    <code><![CDATA[

    $("form").submit(function() {
      if ($("input:first").val() == "correct") {
        $("span").text("Validated...").show();
        return true;
      }
      $("span").text("Not valid!").show().fadeOut(1000);
      return false;
    });
]]></code>
                    <css><![CDATA[

  p { margin:0; color:blue; }
  div,p { margin-left:10px; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<p>Type 'correct' to validate.</p>
  <form action="javascript:alert('success!');">
    <div>
      <input type="text" />

      <input type="submit" />
    </div>
  </form>
  <span></span>]]></html>
                </example>
                <example>
                    <desc>If you'd like to prevent forms from being submitted unless a flag variable is set, try:</desc>
                    <code><![CDATA[$("form").submit( function () {
  return this.some_flag_variable;
} );]]></code>
                </example>
                <example>
                    <desc>To trigger the submit event on the first form on the page, try:</desc>
                    <code><![CDATA[$("form:first").submit();]]></code>
                </example>
<category name="Form Events"/>
<category name="Forms"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="select" return="jQuery">
  <desc>Bind an event handler to the "select" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('select', handler)</code> in the first variation, and <code>.trigger('select')</code> in the second.</p>
<p>The <code>select</code> event is sent to an element when the user makes a text selection inside it. This event is limited to <code>&lt;input type="text"&gt;</code> fields and <code>&lt;textarea&gt;</code> boxes.</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 text input:</p>
<pre>$('#target').select(function() {
  alert('Handler for .select() called.');
});</pre>
<p>Now when any portion of the text is selected, the alert is displayed. Merely setting the location of the insertion point will not trigger the event. We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').select();
});</pre>
<p>After this code executes, clicks on the Trigger button will also alert the message:</p>
<p><span class="output">Handler for .select() called.</span></p>
<p>In addition, the default <code>select</code> action on the field will be fired, so the entire text field will be selected.</p>
<blockquote><p>The method for retrieving the current selected text differs from one browser to another. A number of jQuery plug-ins offer cross-platform solutions.</p></blockquote>
</longdesc>
                <example>
                    <desc>To do something when text in input boxes is selected:</desc>
                    <code><![CDATA[
    $(":input").select( function () { 
      $("div").text("Something was selected").show().fadeOut(1000); 
    });
]]></code>
                    <css><![CDATA[
  p { color:blue; }
  div { color:red; }
  ]]></css>
                    <html><![CDATA[<p>

    Click and drag the mouse to select text in the inputs.
  </p>
  <input type="text" value="Some text" />
  <input type="text" value="to test on" />

  <div></div>]]></html>
                </example>

<example>
    <desc>To trigger the select event on all input elements, try:</desc>
    <code><![CDATA[$("input").select();]]></code>
</example>

<category name="Form Events"/>
<category name="Forms"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="change" return="jQuery">
  <desc>Bind an event handler to the "change" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('change', handler)</code> in the first variation, and <code>.trigger('change')</code> in the second.</p>
<p>The <code>change</code> event is sent to an element when its value changes. This event is limited to <code>&lt;input&gt;</code> elements, <code>&lt;textarea&gt;</code> boxes and <code>&lt;select&gt;</code> elements. For select boxes, checkboxes, and radio buttons, the event is fired immediately when the user makes a selection with the mouse, but for the other element types the event is deferred until the element loses focus.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;form&gt;
  &lt;input class="target" type="text" value="Field 1" /&gt;
  &lt;select class="target"&gt;
    &lt;option value="option1" selected="selected"&gt;Option 1&lt;/option&gt;
    &lt;option value="option2"&gt;Option 2&lt;/option&gt;
  &lt;/select&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 text input and the select box:</p>
<pre>$('.target').change(function() {
  alert('Handler for .change() called.');
});</pre>
<p>Now when the second option is selected from the dropdown, the alert is displayed. It is also displayed if we change the text in the field and then click away. If the field loses focus without the contents having changed, though, the event is not triggered. We can trigger the event manually when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('.target').change();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message. The message will be displayed twice, because the handler has been bound to the <code>change</code> event on both of the form elements.</p>
<p>As of jQuery 1.4 the <code>change</code> event now bubbles, and works identically to all other browsers, in Internet Explorer.</p>
</longdesc>
                <example>
                    <desc>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);
        })
        .change();
]]></code>
                    <css><![CDATA[

  div { color:red; }
  ]]></css>
                    <html><![CDATA[<select name="sweets" multiple="multiple">
    <option>Chocolate</option>
    <option selected="selected">Candy</option>

    <option>Taffy</option>
    <option selected="selected">Caramel</option>
    <option>Fudge</option>
    <option>Cookie</option>

  </select>
  <div></div>]]></html>
                </example>
                <example>
                    <desc>To add a validity test to all text input elements:</desc>
                    <code><![CDATA[$("input[type='text']").change( function() {
  // check input ($(this).val()) for validity here
});]]></code>
                </example>
<category name="Form Events"/>
<category name="Forms"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="blur" return="jQuery">
  <desc>Bind an event handler to the "blur" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>


<longdesc>
<p>This method is a shortcut for <code>.bind('blur', handler)</code> in the first variation, and <code>.trigger('blur')</code> in the second.</p>
<p>The <code>blur</code> event is sent to an element when it loses focus. Originally, this event was only applicable to form elements, such as <code>&lt;input&gt;</code>. In recent browsers, the domain of the event has been extended to include all element types. An element can lose focus via keyboard commands, such as the Tab key, or by mouse clicks elsewhere on the page.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;form&gt;
  &lt;input id="target" type="text" value="Field 1" /&gt;
  &lt;input type="text" value="Field 2" /&gt;
&lt;/form&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
The event handler can be bound to the first input field:
$('#target').blur(function() {
  alert('Handler for .blur() called.');
});</pre>
<p>Now if the first field has the focus and we click elsewhere, or tab away from it, the alert is displayed:</p>
<p><span class="output">Handler for .blur() called.</span></p>
<p>We can trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').blur();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>The <code>blur</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>blur</code> event will not work consistently across browsers.</p>
</longdesc>
<example>
    <desc>To trigger the blur event on all paragraphs:</desc>
    <code><![CDATA[$("p").blur();]]></code>
</example>

<category name="Form Events"/>
<category name="Forms"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="focus" return="jQuery">
  <desc>Bind an event handler to the "focus" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<ul>
<li>This method is a shortcut for <code>.bind('focus', handler)</code> in the first variation, and <code>.trigger('focus')</code> in the second.</li>
<li>The <code>focus</code> event is sent to an element when it gains focus. This event is implicitly applicable to a limited set of elements, such as  form elements (<code>&lt;input&gt;</code>, <code>&lt;select&gt;</code>, etc.) and links (<code>&lt;a href&gt;</code>). In recent browser versions, the event can be extended to include all element types by explicitly setting the element's <code>tabindex</code> property. An element can gain focus via keyboard commands, such as the Tab key, or by mouse clicks on the element.</li>
<li>Elements with focus are usually highlighted in some way by the browser, for example with a dotted line surrounding the element. The focus is used to determine which element is the first to receive keyboard-related events.</li>
</ul>
<p>For example, consider the HTML:</p>
<pre>&lt;form&gt;
  &lt;input id="target" type="text" value="Field 1" /&gt;
  &lt;input type="text" value="Field 2" /&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 first input field:</p>
<pre>$('#target').focus(function() {
  alert('Handler for .focus() called.');
});</pre>
<p>Now if we click on the first field, or tab to it from another field, the alert is displayed:</p>
<p><span class="output">Handler for .focus() called.</span></p>
<p>We can trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').focus();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>The <code>focus</code> event does not bubble in Internet Explorer. Therefore, scripts that rely on event delegation with the <code>focus</code> event will not work consistently across browsers.</p>
<blockquote><p>Triggering the focus on hidden elements causes an error in Internet Explorer. Take care to only call <code>.focus()</code> without parameters on elements that are visible.</p></blockquote>
</longdesc>
                <example>
                    <desc>Fire focus.</desc>
                    <css><![CDATA[span {display:none;}]]></css>
                    <code><![CDATA[
    $("input").focus(function () {
         $(this).next("span").css('display','inline').fadeOut(1000);
    });
]]></code>
                    <html><![CDATA[<p><input type="text" /> <span>focus fire</span></p>

<p><input type="password" /> <span>focus fire</span></p>]]></html>
                </example>
                <example>
                    <desc>To stop people from writing in text input boxes, try:</desc>
                    <code><![CDATA[$("input[type=text]").focus(function(){
  $(this).blur();
});]]></code>
                </example>
                <example>
                    <desc>To focus on a login input box with id 'login' on page startup, try:</desc>
                    <code><![CDATA[$(document).ready(function(){
  $("#login").focus();
});]]></code>
                </example>

<category name="Form Events"/>
<category name="Forms"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mousemove" return="jQuery">
  <desc>Bind an event handler to the "mousemove" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('mousemove', handler)</code> in the first variation, and <code>.trigger('mousemove')</code> in the second.</p>
<p>The <code>mousemove</code> event is sent to an element when the mouse pointer moves inside the element. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="target"&gt;
  Move here
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_10.png" alt="" />
</p>
<p>The event handler can be bound to the target:</p>
<pre>$('#target').mousemove(function(event) {
  var msg = 'Handler for .mousemove() called at ' + event.pageX + ', ' + event.pageY;
  $('#log').append('&lt;div&gt; + msg + '&lt;/div&gt;');
});</pre>
<p>Now when the mouse pointer moves within the target button, the messages are appended to &lt;div id="log"&gt;:</p>
<p>
<span class="output">Handler for .mousemove() called at (399, 48)</span><br />
<span class="output">Handler for .mousemove() called at (398, 46)</span><br />
<span class="output">Handler for .mousemove() called at (397, 44)</span><br />
<span class="output">Handler for .mousemove() called at (396, 42)</span><br />
</p>
<p>We can also trigger the event when the second button is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').mousemove();
});</pre>
<p>After this code executes, clicks on the Trigger button will also append the message:</p>
<p><span class="output">Handler for .mousemove() called at (undefined, undefined)</span></p>
<p>When tracking mouse movement, we usually need to know the actual position of the mouse pointer. The event object that is passed to the handler contains some information about the mouse coordinates. Properties such as <code>.clientX</code>, <code>.offsetX</code>, and <code>.pageX</code> are available, but support for them differs between browsers. Fortunately, jQuery normalizes the <code>.pageX</code> and <code>.pageY</code> attributes so that they can be used in all browsers. These attributes provide the X and Y coordinates of the mouse pointer relative to the top-left corner of the page, as illustrated in the example output above.</p>
<p>We need to remember that the <code>mousemove</code> event is triggered whenever the mouse pointer moves, even for a pixel. This means that hundreds of events can be generated over a very small amount of time. If the handler has to do any significant processing, or if multiple handlers for the event exist, this can be a serious performance drain on the browser. It is important, therefore, to optimize <code>mousemove </code>handlers as much as possible, and to unbind them as soon as they are no longer needed.</p>
<p>A common pattern is to bind the <code>mousemove</code> handler from within a <code>mousedown</code> hander, and to unbind it from a corresponding <code>mouseup</code> handler. If implementing this sequence of events, remember that the <code>mouseup</code> event might be sent to a different HTML element than the <code>mousemove</code> event was. To account for this, the <code>mouseup</code> handler should typically be bound to an element high up in the DOM tree, such as <code>&lt;body&gt;</code>.</p>
</longdesc>
                <example>
                    <desc>Show the mouse coordinates when the mouse is moved over the yellow div.  Coordinates are relative to the window, which in this case is the iframe.</desc>
                    <code><![CDATA[
    $("div").mousemove(function(e){
      var pageCoords = "( " + e.pageX + ", " + e.pageY + " )";
      var clientCoords = "( " + e.clientX + ", " + e.clientY + " )";
      $("span:first").text("( e.pageX, e.pageY ) - " + pageCoords);
      $("span:last").text("( e.clientX, e.clientY ) - " + clientCoords);
    });

]]></code>
                    <height>300</height>
                    <css><![CDATA[
  div { width:220px; height:170px; margin;10px; margin-right:50px;
        background:yellow; border:2px groove; float:right; }
  p { margin:0; margin-left:10px; color:red; width:220px;
      height:120px; padding-top:70px;
      float:left; font-size:14px; }
  span { display:block; }
  ]]></css>
                    <html><![CDATA[<p>   
    Try scrolling too.
    <span>Move the mouse over the div.</span>
    <span>&nbsp;</span>
  </p>

  <div></div>]]></html>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="hover" return="jQuery">
  <desc>Bind two handlers to the matched elements, to be executed when the mouse pointer enters and leaves the elements.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handlerIn(eventObject)" type="Function">
      <desc>A function to execute when the mouse pointer enters the element.</desc>
    </argument>
    <argument name="handlerOut(eventObject)" type="Function">
      <desc>A function to execute when the mouse pointer leaves the element.</desc>
    </argument>
  </signature>

<longdesc>
<p>The <code>.hover()</code> method binds handlers for both <code>mouseenter</code> and <code>mouseleave</code> events. We can use it to simply apply behavior to an element during the time the mouse is within the element.</p>
<p>Calling <code>$(selector).hover(handlerIn, handlerOut)</code> is shorthand for:</p>
<pre>$(selector).mouseenter(handlerIn).mouseleave(handlerOut);</pre>
<p>See the discussions for <code><a href="/mouseenter">.mouseenter()</a></code> and <code><a href="/mouseleave">.mouseleave()</a></code> for more details.</p>
</longdesc>
<example>
  <desc>To add a special style to list items that are being hovered over, try:</desc>
  <code><![CDATA[
$("li").hover(
  function () {
    $(this).append($("<span> ***</span>"));
  }, 
  function () {
    $(this).find("span:last").remove();
  }
);



//li with fade class
$("li.fade").hover(function(){$(this).fadeOut(100);$(this).fadeIn(500);});

]]></code>
<css><![CDATA[
  ul { margin-left:20px; color:blue; }
  li { cursor:default; }
  span { color:red; }
]]></css>
  <html><![CDATA[<ul>
    <li>Milk</li>
    <li>Bread</li>
    <li class='fade'>Chips</li>

    <li class='fade'>Socks</li>
  </ul>]]></html>
 </example>
                <example>
                    <desc>To add a special style to table cells that are being hovered over, try:</desc>
                    <code><![CDATA[$("td").hover(
  function () {
    $(this).addClass("hover");
  },
  function () {
    $(this).removeClass("hover");
  }
);]]></code>
  </example>
  <example>
    <desc>To unbind the above example use:</desc>
    <code><![CDATA[$("td").unbind('mouseenter mouseleave');]]></code>
  </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
</entry>

<entry type='method' name="hover" return="jQuery">
  <desc>Bind a single handler to the matched elements, to be executed when the mouse pointer enters or leaves the elements.</desc>
  <signature>
    <added>1.4</added>
    <argument name="handlerInOut(eventObject)" type="Function">
      <desc>A function to execute when the mouse pointer enters or leaves the element.</desc>
    </argument>
  </signature>

<longdesc>
<p>The <code>.hover()</code> method, when passed a single function, will execute that handler for both <code>mouseenter</code> and <code>mouseleave</code> events.   This allows the user to use jQuery's various toggle methods within the handler.</p>
<p>Calling <code>$(selector).hover(handlerInOut)</code> is shorthand for:</p>
<pre>$(selector).bind("mouseenter mouseleave",handlerInOut);</pre>
<p>See the discussions for <code><a href="/mouseenter">.mouseenter()</a></code> and <code><a href="/mouseleave">.mouseleave()</a></code> for more details.</p>
</longdesc>
  <example>
    <desc>Slide the next sibling LI up or down on hover, and toggle a class.</desc>
    <code><![CDATA[
$("li")
.filter(":odd")
.hide()
 .end()
.filter(":even")
.hover(
  function () {
    $(this).toggleClass("active")
      .next().stop(true, true).slideToggle();
  }
);


]]></code>
<css><![CDATA[
  ul { margin-left:20px; color:blue; }
  li { cursor:default; }
  li.active { background:black;color:white; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<ul>
    <li>Milk</li>
    <li>White</li>
    <li>Carrots</li>
    <li>Orange</li>
    <li>Broccoli</li>
    <li>Green</li>
  </ul>]]></html>
                </example>
<category name="Mouse Events"/>
<category name="Version 1.0"/>
</entry>

<entry type='method' name="mouseleave" return="jQuery">
  <desc>Bind an event handler to be fired when the mouse leaves an element, or trigger that handler on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>


<longdesc>
<p>This method is a shortcut for <code>.bind('mouseleave', handler)</code> in the first variation, and <code>.trigger('mouseleave')</code> in the second.</p>
<p>The <code>mouseleave</code> JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="outer"&gt;
  Outer
  &lt;div id="inner"&gt;
    Inner
  &lt;/div&gt;
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre> 
<p class="image"><img src="/images/0042_05_09.png" alt="" />
</p>
<p>The event handler can be bound to any element:</p>
<pre>$('#outer').mouseleave(function() {
  $('#log').append('&lt;div&gt;Handler for .mouseleave() called.&lt;/div&gt;');
});</pre>
<p>Now when the mouse pointer moves out of the <span class="output">Outer</span> <code>&lt;div&gt;</code>, the message is appended to <code>&lt;div id="log"&gt;</code>. We can also trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#outer').mouseleave();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also append the message.</p>
<p>The <code>mouseleave</code> event differs from <code>mouseout</code> in the way it handles event bubbling. If <code>mouseout</code> were used in this example, then when the mouse pointer moved out of the <span class="output">Inner</span> element, the handler would be triggered. This is usually undesirable behavior. The <code>mouseleave</code> event, on the other hand, only triggers its handler when the mouse leaves the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse leaves the <span class="output">Outer</span> element, but not the <span class="output">Inner</span> element.</p>
</longdesc>
                <example>
                    <desc>Show number of times mouseout and mouseleave events are triggered.
<code>mouseout</code> fires when the pointer moves out of child element as well, while <code>mouseleave</code> fires only when the pointer moves out of the bound element.</desc>
                    <css><![CDATA[
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
]]></css>
                    <code><![CDATA[
    var i = 0;
    $("div.overout").mouseover(function(){
      $("p:first",this).text("mouse over");
    }).mouseout(function(){
      $("p:first",this).text("mouse out");
      $("p:last",this).text(++i);
    });

    var n = 0;
    $("div.enterleave").mouseenter(function(){
      $("p:first",this).text("mouse enter");
    }).mouseleave(function(){
      $("p:first",this).text("mouse leave");
      $("p:last",this).text(++n);
    });

]]></code>
                    <html><![CDATA[
<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

]]></html>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mouseenter" return="jQuery">
  <desc>Bind an event handler to be fired when the mouse enters an element, or trigger that handler on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>


<longdesc>
<p>This method is a shortcut for <code>.bind('mouseenter', handler)</code> in the first variation, and <code>.trigger('mouseenter')</code> in the second.</p>
<p>The <code>mouseenter</code> JavaScript event is proprietary to Internet Explorer. Because of the event's general utility, jQuery simulates this event so that it can be used regardless of browser. This event sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="outer"&gt;
  Outer
  &lt;div id="inner"&gt;
    Inner
  &lt;/div&gt;
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_08.png" alt="" />
</p>
<p>The event handler can be bound to any element:</p>
<pre>$('#outer').mouseenter(function() {
  $('#log').append('&lt;div&gt;Handler for .mouseenter() called.&lt;/div&gt;');
});</pre>
<p>Now when the mouse pointer moves over the <span class="output">Outer</span> <code>&lt;div&gt;</code>, the message is appended to <code>&lt;div id="log"&gt;</code>. We can also trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#outer').mouseenter();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also append the message.</p>
<p>The <code>mouseenter</code> event differs from <code>mouseover</code> in the way it handles event bubbling. If <code>mouseover</code> were used in this example, then when the mouse pointer moved over the <span class="output">Inner</span> element, the handler would be triggered. This is usually undesirable behavior. The <code>mouseenter</code> event, on the other hand, only triggers its handler when the mouse enters the element it is bound to, not a descendant. So in this example, the handler is triggered when the mouse enters the <span class="output">Outer</span> element, but not the <span class="output">Inner</span> element.</p>
</longdesc>
                <example>
                    <desc>Show texts when mouseenter and mouseout event triggering.
<code>mouseover</code> fires when the pointer moves into the child element as well, while <code>mouseenter</code> fires only when the pointer moves into the bound element.</desc>
                    <css><![CDATA[
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
]]></css>
                    <code><![CDATA[
    var i = 0;
    $("div.overout").mouseover(function(){
      $("p:first",this).text("mouse over");
      $("p:last",this).text(++i);
    }).mouseout(function(){
      $("p:first",this).text("mouse out");
    });

    var n = 0;
    $("div.enterleave").mouseenter(function(){
      $("p:first",this).text("mouse enter");
      $("p:last",this).text(++n);
    }).mouseleave(function(){
      $("p:first",this).text("mouse leave");
    });

]]></code>
                    <html><![CDATA[
<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

]]></html>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mouseout" return="jQuery">
  <desc>Bind an event handler to the "mouseout" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('mouseout', handler)</code> in the first variation, and <code>.trigger('mouseout')</code> in the second.</p>
<p>The <code>mouseout</code> event is sent to an element when the mouse pointer leaves the element. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="outer"&gt;
  Outer
  &lt;div id="inner"&gt;
    Inner
  &lt;/div&gt;
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre> 
<p class="image"><img src="/images/0042_05_07.png" alt="" />
</p>
<p>The event handler can be bound to any element:</p>
<pre>$('#outer').mouseout(function() {
  $('#log').append('Handler for .mouseout() called.');
});</pre>
<p>Now when the mouse pointer moves out of the <span class="output">Outer</span> <code>&lt;div&gt;</code>, the message is appended to <code>&lt;div id="log"&gt;</code>. We can also trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#outer').mouseout();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also append the message.</p>
<p>This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves out of the <span class="output">Inner</span> element in this example, a <code>mouseout</code> event will be sent to that, then trickle up to <span class="output">Outer</span>. This can trigger the bound <code>mouseout</code> handler at inopportune times. See the discussion for <code>.<a href="/mouseleave">mouseleave</a>()</code> for a useful alternative.</p>
</longdesc>
                <example>
                    <desc>Show the number of times mouseout and mouseleave events are triggered.
<code>mouseout</code> fires when the pointer moves out of the child element as well, while <code>mouseleave</code> fires only when the pointer moves out of the bound element.</desc>
                    <css><![CDATA[
div.out {
width:40%;
height:120px;
margin:0 15px;
background-color:#D6EDFC;
float:left;
}
div.in {
width:60%;
height:60%;
background-color:#FFCC00;
margin:10px auto;
}
p {
line-height:1em;
margin:0;
padding:0;
}
]]></css>
                    <code><![CDATA[
    var i = 0;
    $("div.overout").mouseout(function(){
      $("p:first",this).text("mouse out");
      $("p:last",this).text(++i);
    }).mouseover(function(){
      $("p:first",this).text("mouse over");
    });

    var n = 0;
    $("div.enterleave").bind("mouseenter",function(){
      $("p:first",this).text("mouse enter");
    }).bind("mouseleave",function(){
      $("p:first",this).text("mouse leave");
      $("p:last",this).text(++n);
    });

]]></code>
                    <html><![CDATA[
<div class="out overout"><p>move your mouse</p><div class="in overout"><p>move your mouse</p><p>0</p></div><p>0</p></div>

<div class="out enterleave"><p>move your mouse</p><div class="in enterleave"><p>move your mouse</p><p>0</p></div><p>0</p></div>

]]></html>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mouseover" return="jQuery">
  <desc>Bind an event handler to the "mouseover" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>


<longdesc>
<p>This method is a shortcut for <code>.bind('mouseover', handler)</code> in the first variation, and <code>.trigger('mouseover')</code> in the second.</p>
<p>The <code>mouseover</code> event is sent to an element when the mouse pointer enters the element. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="outer"&gt;
  Outer
  &lt;div id="inner"&gt;
    Inner
  &lt;/div&gt;
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
&lt;div id="log"&gt;&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_06.png" alt="" />
</p>
<p>The event handler can be bound to any element:</p>
<pre>$('#outer').mouseover(function() {
  $('#log').append('&lt;div&gt;Handler for .mouseover() called.&lt;/div&gt;');
});</pre>
<p>Now when the mouse pointer moves over the <span class="output">Outer</span> <code>&lt;div&gt;</code>, the message is appended to <code>&lt;div id="log"&gt;</code>. We can also trigger the event when another element is clicked:</p>
<pre>$('#other').click(function() {
  $('#outer').mouseover();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also append the message.</p>
<p>This event type can cause many headaches due to event bubbling. For instance, when the mouse pointer moves over the <span class="output">Inner</span> element in this example, a <code>mouseover</code> event will be sent to that, then trickle up to <span class="output">Outer</span>. This can trigger our bound <code>mouseover</code> handler at inopportune times. See the discussion for <code>.mouseenter()</code> for a useful alternative.</p>
</longdesc>
                <example>
                    <desc>Show the number of times mouseover and mouseenter events are triggered.
<code>mouseover</code> fires when the pointer moves into the child element as well, while <code>mouseenter</code> fires only when the pointer moves into the bound element.</desc>
                    <css><![CDATA[
div.out { width:40%; height:120px; margin:0 15px;
          background-color:#D6EDFC; float:left; }
div.in {  width:60%; height:60%; 
          background-color:#FFCC00; margin:10px auto; }
p { line-height:1em; margin:0; padding:0; }
]]></css>
  <code><![CDATA[
  var i = 0;
  $("div.overout").mouseover(function() {
    i += 1;
    $(this).find("span").text( "mouse over x " + i );
  }).mouseout(function(){
    $(this).find("span").text("mouse out ");
  });

  var n = 0;
  $("div.enterleave").mouseenter(function() {
    n += 1;
    $(this).find("span").text( "mouse enter x " + n );
  }).mouseleave(function() {
    $(this).find("span").text("mouse leave");
  });

]]></code>
  <html><![CDATA[
<div class="out overout">
  <span>move your mouse</span>
  <div class="in">
  </div>
</div>

<div class="out enterleave">
  <span>move your mouse</span>
  <div class="in">
  </div>
</div>
]]></html>
</example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="dblclick" return="jQuery">
  <desc>Bind an event handler to the "dblclick" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
   <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('dblclick', handler)</code> in the first variation, and <code>.trigger('dblclick')</code> in the second.
The <code>dblclick</code> event is sent to an element when the element is double-clicked. Any HTML element can receive this event.
For example, consider the HTML:</p>
<pre>&lt;div id="target"&gt;
  Double-click here
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_04.png" alt="" />
</p>
<p>The event handler can be bound to any <code>&lt;div&gt;</code>:</p>
<pre>$('#target').dblclick(function() {
  alert('Handler for .dblclick() called.');
});</pre>
<p>Now if we double-click on this element, the alert is displayed:</p>
<p><span class="output">Handler for .dblclick() called.</span></p>
<p>We can also trigger the event when a different element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').dblclick();
});</pre>
<p>After this code executes, (single) clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>The <code>dblclick</code> event is only triggered after this exact series of events:</p>
<ul>
<li>The mouse button is depressed while the pointer is inside the element.</li>
<li>The mouse button is released while the pointer is inside the element.</li>
<li>The mouse button is depressed again while the pointer is inside the element, within a time window that is system-dependent.</li>
<li>The mouse button is released while the pointer is inside the element.</li>
</ul>
<p>It is inadvisable to bind handlers to both the <code>click</code> and <code>dblclick</code> events for the same element. The sequence of events triggered varies from browser to browser, with some receiving two <code>click</code> events and others only one. If an interface that reacts differently to single- and double-clicks cannot be avoided, then the <code>dblclick</code> event should be simulated within the <code>click</code> handler. We can achieve this by saving a timestamp in the handler, and then comparing the current time to the saved timestamp on subsequent clicks. If the difference is small enough, we can treat the click as a double-click.
</p>
</longdesc>
                <example>
                    <desc>To bind a "Hello World!" alert box the dblclick event on every paragraph on the page:</desc>
                    <code><![CDATA[$("p").dblclick( function () { alert("Hello World!"); });]]></code>
                </example>
                <example>
                    <desc>Double click to toggle background color.</desc>
                    <code><![CDATA[
    var divdbl = $("div:first");
    divdbl.dblclick(function () { 
      divdbl.toggleClass('dbl'); 
    });

]]></code>
                    <css><![CDATA[

  div { background:blue;
        color:white;
        height:100px;
        width:150px;
 }
  div.dbl { background:yellow;color:black; }
  ]]></css>
                    <html><![CDATA[<div></div><span>Double click the block</span>]]></html>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="click" return="jQuery">
  <desc>Bind an event handler to the "click" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('click', handler)</code> in the first variation, and <code>.trigger('click')</code> in the second.</p>
<p>The <code>click</code> event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed and released. Any HTML element can receive this event.</p>
<pre>For example, consider the HTML:
&lt;div id="target"&gt;
  Click here
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_03.png" alt="" /></p>
<p>The event handler can be bound to any <code>&lt;div&gt;</code>:</p>
<pre>$('#target').click(function() {
  alert('Handler for .click() called.');
});</pre>
<p>Now if we click on this element, the alert is displayed:</p>
<p><span class="output">Handler for .click() called.</span></p>
<p>We can also trigger the event when a different element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').click();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>The <code>click</code> event is only triggered after this exact series of events:</p>
<ul>
  <li>The mouse button is depressed while the pointer is inside the element.</li>
  <li>The mouse button is released while the pointer is inside the element.</li>
</ul>
<p>This is usually the desired sequence before taking an action. If this is not required, the <code>mousedown</code> or <code>mouseup</code> event may be more suitable.</p>
</longdesc>
                <example>
                    <desc>To hide paragraphs on a page when they are clicked:</desc>
                    <code><![CDATA[
    $("p").click(function () { 
      $(this).slideUp(); 
    });
    $("p").hover(function () {
      $(this).addClass("hilite");
    }, function () {
      $(this).removeClass("hilite");
    });
]]></code>
                    <css><![CDATA[
  p { color:red; margin:5px; cursor:pointer; }
  p.hilite { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p>First Paragraph</p>

  <p>Second Paragraph</p>
  <p>Yet one more Paragraph</p>]]></html>
                </example>
                <example>
                    <desc>To trigger the click event on all of the paragraphs on the page:</desc>
                    <code><![CDATA[$("p").click();]]></code>
                </example>

<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mouseup" return="jQuery">
  <desc>Bind an event handler to the "mouseup" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>
<longdesc>
<p>This method is a shortcut for <code>.bind('mouseup', handler)</code> in the first variation, and <code>.trigger('mouseup')</code> in the second.</p>
<p>The <code>mouseup</code> event is sent to an element when the mouse pointer is over the element, and the mouse button is released. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="target"&gt;
  Click here
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;
</pre> 
<p class="image"><img src="/images/0042_05_02.png" alt="" /></p>
<p>The event handler can be bound to any <code>&lt;div&gt;</code>:</p>
<pre>$('#target').mouseup(function() {
  alert('Handler for .mouseup() called.');
});
</pre>
<p>Now if we click on this element, the alert is displayed:</p>
<p><span class="output">Handler for .mouseup() called.</span></p>
<p>We can also trigger the event when a different element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').mouseup();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>If the user clicks outside an element, drags onto it, and releases the button, this is still counted as a <code>mouseup</code> event. This sequence of actions is not treated as a button press in most user interfaces, so it is usually better to use the <code>click</code> event unless we know that the <code>mouseup</code> event is preferable for a particular situation.</p>
</longdesc>
                <example>
                    <desc>Show texts when mouseup and mousedown event triggering.</desc>
                    <code><![CDATA[
    $("p").mouseup(function(){
      $(this).append('<span style="color:#F00;">Mouse up.</span>');
    }).mousedown(function(){
      $(this).append('<span style="color:#00F;">Mouse down.</span>');
    });

]]></code>
                    <html><![CDATA[<p>Press mouse and release here.</p>
]]></html>
                </example>
<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="mousedown" return="jQuery">
  <desc>Bind an event handler to the "mousedown" JavaScript event, or trigger that event on an element.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
  </signature>
<longdesc>
<p>This method is a shortcut for <code>.bind('mousedown', handler)</code> in the first variation, and <code>.trigger('mousedown')</code> in the second.</p>
<p>The <code>mousedown</code> event is sent to an element when the mouse pointer is over the element, and the mouse button is pressed. Any HTML element can receive this event.</p>
<p>For example, consider the HTML:</p>
<pre>&lt;div id="target"&gt;
  Click here
&lt;/div&gt;
&lt;div id="other"&gt;
  Trigger the handler
&lt;/div&gt;</pre>
 
<p class="image"><img src="/images/0042_05_01.png" alt="" /></p>
<p>The event handler can be bound to any <code>&lt;div&gt;</code>:</p>
<pre>$('#target').mousedown(function() {
  alert('Handler for .mousedown() called.');
});</pre>
<p>Now if we click on this element, the alert is displayed:</p>
<p><span class="output">Handler for .mousedown() called.</span></p>
<p>We can also trigger the event when a different element is clicked:</p>
<pre>$('#other').click(function() {
  $('#target').mousedown();
});</pre>
<p>After this code executes, clicks on <span class="output">Trigger the handler</span> will also alert the message.</p>
<p>The <code>mousedown</code> event is sent when any mouse button is clicked. To act only on specific buttons, we can use the event object's <code>which </code>property. Not all browsers support this property (Internet Explorer uses button instead), but jQuery normalizes the property so that it is safe to use in any browser. The value of <code>which</code> will be 1 for the left button, 2 for the middle button, or 3 for the right button.</p>
<p>This event is primarily useful for ensuring that the primary button was used to begin a drag operation; if ignored, strange results can occur when the user attempts to use a context menu. While the middle and right buttons can be detected with these properties, this is not reliable. In Opera and Safari, for example, right mouse button clicks are not detectable by default.</p>
<p>If the user clicks on an element, drags away from it, and releases the button, this is still counted as a <code>mousedown</code> event. This sequence of actions is treated as a "canceling" of the button press in most user interfaces, so it is usually better to use the <code>click</code> event unless we know that the <code>mousedown</code> event is preferable for a particular situation.</p>

</longdesc>
                <example>
                    <desc>Show texts when mouseup and mousedown event triggering.</desc>
                    <code><![CDATA[
    $("p").mouseup(function(){
      $(this).append('<span style="color:#F00;">Mouse up.</span>');
    }).mousedown(function(){
      $(this).append('<span style="color:#00F;">Mouse down.</span>');
    });

]]></code>
                    <html><![CDATA[<p>Press mouse and release here.</p>
]]></html>
                </example>
<category name="Mouse Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="error" return="jQuery">
  <desc>Bind an event handler to the "error" JavaScript event.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute when the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>

<longdesc>
<p>This method is a shortcut for <code>.bind('error', handler)</code>.</p>
<p>The <code>error</code> event is sent to elements, such as images, that are referenced by a document and loaded by the browser. It is called if the element was not loaded correctly.</p>
<p>For example, consider a page with a simple image:</p>
<pre>&lt;img src="missing.png" alt="Book" id="book" /&gt;</pre>
<p>The event handler can be bound to the image:</p>
<pre>$('#book').error(function() {
  alert('Handler for .error() called.')
});
</pre>
<p>If the image cannot be loaded (for example, because it is not present at the supplied URL), the alert  is displayed:</p>
<p><span class="output">Handler for .error() called.</span></p>
<blockquote><p>This event may not be correctly fired when the page is served locally. Since <code>error</code> relies on normal HTTP status codes, it will generally not be triggered if the URL uses the <code>file:</code> protocol.</p>
</blockquote>
<p>Note: A jQuery error event handler should not be attached to the window object. The browser fires the window's error event when a script error occurs. However, the window error event receives different arguments and has different return value requirements than conventional event handlers.
</p>
</longdesc>
                <example>
                    <desc>To hide JavaScript errors from the user, you can try:</desc>
                    <code><![CDATA[$(window).error(function(){
  return true;
});]]></code>
                </example>
                <example>
                    <desc>To hide the "broken image" icons for your IE users, you can try:</desc>
                    <code><![CDATA[$("img").error(function(){
  $(this).hide();
});]]></code>
                </example>

<category name="Browser Events"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="unload" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute when the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
    <desc>Bind an event handler to the "unload" JavaScript event.</desc>
<longdesc>
<p>This method is a shortcut for <code>.bind('unload', handler)</code>.</p>
<p>The <code>unload</code> event is sent to the <code>window</code> element when the user navigates away from the page. This could mean one of many things. The user could have clicked on a link to leave the page, or typed in a new URL in the address bar. The forward and back buttons will trigger the event. Closing the browser window will cause the event to be triggered. Even a page reload will first create an <code>unload</code> event.</p>
<blockquote><p>The exact handling of the <code>unload</code> event has varied from version to version of browsers. For example, some versions of Firefox trigger the event when a link is followed, but not when the window is closed. In practical usage, behavior should be tested on all supported browsers, and contrasted with the proprietary <code>beforeunload</code> event.</p></blockquote>
<p>Any <code>unload</code> event handler should be bound to the <code>window</code> object:</p>
<pre>$(window).unload(function() {
  alert('Handler for .unload() called.');
});
</pre>
<p>After this code executes, the alert will be displayed whenever the browser leaves the current page.
It is not possible to cancel the <code>unload</code> event with <code>.preventDefault()</code>. This event is available so that scripts can perform cleanup when the user leaves the page.
</p>
</longdesc>
<example>
    <desc>To display an alert when a page is unloaded:</desc>
    <code><![CDATA[$(window).unload( function () { alert("Bye now!"); } );]]></code>
</example>

<category name="Document Loading"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="load" return="jQuery">
  <desc>Bind an event handler to the "load" JavaScript event.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute when the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute each time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc>
  <p>This method is a shortcut for <code>.bind('load', handler)</code>.</p>
  <p>The <code>load</code> event is sent to an element when it and all sub-elements have been completely loaded. This event can be sent to any element associated with a URL: images, scripts, frames, iframes, and the <code>window</code> object.</p>
<blockquote><p>It is possible that the load event will not be triggered if the image is loaded from the browser cache. To account for this possibility, we can use a special load event that fires immediately if the image is ready. <code>event.special.load</code> is currently <a href="http://github.com/peol/jquery.imgloaded/raw/master/ahpi.imgload.js">available as a plugin</a>. </p></blockquote>
<p>For example, consider a page with a simple image:</p>
<pre>&lt;img src="book.png" alt="Book" id="book" /&gt;</pre>
<p>The event handler can be bound to the image:</p>
<pre>$('#book').load(function() {
  // Handler for .load() called.
});</pre>
<p>As soon as the image has been loaded, the handler is called.</p>
<p>In general, it is not necessary to wait for all images to be fully loaded. If code can be executed earlier, it is usually best to place it in a handler sent to the <code>.ready()</code> method.
</p>
<blockquote><p>The Ajax module also has a method named <code><a href="/load">.load()</a></code>. Which one is fired depends on the set of arguments passed.</p></blockquote>
</longdesc>
                <example>
                    <desc>Run a function when the page is fully loaded including graphics.</desc>
                    <code><![CDATA[$(window).load(function () {
  // run code
});]]></code>
                </example>
                <example>
                    <desc>Add the class bigImg to all images with height greater then 100 upon each image load.</desc>
                    <code><![CDATA[$('img.userIcon').load(function(){
  if($(this).height() > 100) {
    $(this).addClass('bigImg');
  }
});]]></code>
                </example>

<category name="Document Loading"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="ready" return="jQuery">
  <desc>Specify a function to execute when the DOM is fully loaded.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler" type="Function">
      <desc>A function to execute after the DOM is ready.</desc>
    </argument>
  </signature>

<longdesc>
<p>While JavaScript provides the <code>load</code> event for executing code when a page is rendered, this event does not get triggered until all assets such as images have been completely received. In most cases, the script can be run as soon as the DOM hierarchy has been fully constructed. The handler passed to <code>.ready()</code> is guaranteed to be executed after the DOM is ready, so this is usually the best place to attach all other event handlers and run other jQuery code.  When using scripts that rely on the value of CSS style properties, it's important to reference external stylesheets or embed style elements before referencing the scripts.</p>
<p>In cases where code relies on loaded assets (for example, if the dimensions of an image are required), the code should be placed in a handler for the <code>load</code> event instead.</p>

<blockquote><p>The <code>.ready()</code> method is generally incompatible with the <code>&lt;body onload=""&gt;</code> attribute. If <code>load</code> must be used, either do not use <code>.ready()</code> or use jQuery's <code>.load()</code> method to attach <code>load</code> event handlers to the window or to more specific items, like images.
</p></blockquote>
<p>All three of the following syntaxes are equivalent:</p>
 <ul>
   <li><code>$(document).ready(handler)</code></li>
   <li><code>$().ready(handler)</code> (this is not recommended)</li>
   <li><code>$(handler)</code></li>
 </ul>
<p>There is also <code>$(document).bind("ready", handler)</code>. This behaves similarly to the ready method but with one exception: If the ready event has already fired and you try to <code>.bind("ready")</code> the bound handler will not be executed.</p>
 <p>The <code>.ready()</code> method can only be called on a jQuery object matching the current document, so the selector can be omitted.</p>
<p>The <code>.ready()</code> method is typically used with an anonymous function:</p>
<pre>$(document).ready(function() {
  // Handler for .ready() called.
});</pre>
<p>If <code>.ready()</code> is called after the DOM has been initialized, the new handler passed in will be executed immediately.</p>
<h4>Aliasing the jQuery Namespace</h4>
<p>When using another JavaScript library, we may wish to call <code><a href="/jQuery.noConflict">$.noConflict()</a></code> to avoid namespace difficulties. When this function is called, the <code>$</code> shortcut is no longer available, forcing us to write <code>jQuery</code> each time we would normally write <code>$</code>. However, the handler passed to the <code>.ready()</code> method can take an argument, which is passed the global <code>jQuery</code> object. This means we can rename the object within the context of our <code>.ready()</code> handler without affecting other code:</p>
<pre>jQuery(document).ready(function($) {
  // Code using $ as usual goes here.
});</pre>
</longdesc>
  <example>
      <desc>Display a message when the DOM is loaded.</desc>
      <code location="head"><![CDATA[$(document).ready(function () {
  $("p").text("The DOM is now loaded and can be manipulated.");
});]]></code>
  <css><![CDATA[p { color:red; }]]></css>
  <html><![CDATA[<p>Not loaded yet.</p>]]></html>
  </example>
<category name="Document Loading"/>
<category name="Version 1.0"/>
</entry>

<entry type='method' name="die" return="jQuery">
  <desc>Remove all event handlers previously attached using <code>.live()</code> from the elements.</desc>
  <signature>
    <added>1.4.1</added>
  </signature>
<longdesc>
<p>Any handler that has been attached with <code>.live()</code> can be removed with <code>.die()</code>. This method is analogous to calling <code>.unbind()</code> with no arguments, which is used to remove all handlers attached with <code>.bind()</code>.
See the discussions of <code>.live()</code> and <code>.unbind()</code> for further details.</p>
</longdesc>
<category name="Event Handler Attachment"/>
<category name="Version 1.3"/>
<category name="Version 1.4.1"/>
</entry>
<entry type='method' name="die" return="jQuery">
  <desc>Remove an event handler previously attached using <code>.live()</code> from the elements.</desc>
  <signature>
    <added>1.3</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as <code>click</code> or <code>keydown</code>.</desc>
    </argument>
    <argument name="handler" optional="true" type="String">
      <desc>The function that is to be no longer executed.</desc>
    </argument>
  </signature>
<longdesc>
<p>Any handler that has been attached with <code>.live()</code> can be removed with <code>.die()</code>. This method is analogous to <code>.unbind()</code>, which is used to remove handlers attached with <code>.bind()</code>.
See the discussions of <code>.live()</code> and <code>.unbind()</code> for further details.</p>
</longdesc>
            <example>
                <desc>Can bind and unbind events to the colored button.</desc>
                <code><![CDATA[

function aClick() {
  $("div").show().fadeOut("slow");
}
$("#bind").click(function () {
  $("#theone").live("click", aClick)
              .text("Can Click!");
});
$("#unbind").click(function () {
  $("#theone").die("click", aClick)
              .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>To unbind all live events from all paragraphs, write:</desc>
                <code><![CDATA[$("p").die()]]></code>
            </example>
            <example>
                <desc>To unbind all live click events from all paragraphs, write:</desc>
                <code><![CDATA[$("p").die( "click" )]]></code>
            </example>
            <example>
                <desc>To unbind just one previously bound handler, pass the function in as the second argument:</desc>
                <code><![CDATA[var foo = function () {
// code to handle some kind of event
};

$("p").live("click", foo); // ... now foo will be called when paragraphs are clicked ...

$("p").die("click", foo); // ... foo will no longer be called.]]></code>
            </example>
<category name="Event Handler Attachment"/>
<category name="Version 1.3"/>
<category name="Version 1.4.1"/>
</entry>


<entry type='property' name="jQuery.browser" return="Map">
  <signature><added>1.0</added></signature>
  <desc><strong>We recommend against using this property, please try to use feature detection instead (see jQuery.support).</strong> Contains flags for the useragent, read from navigator.userAgent. While jQuery.browser will not be removed from future versions of jQuery, every effort to use jQuery.support and proper feature detection should be made.</desc>
                <longdesc>
                   <p>The <code>$.browser</code> property allows us to detect which web browser is accessing the page, as reported by the browser itself. It contains flags for each of the four most prevalent browser classes (Internet Explorer, Mozilla, Webkit, and Opera) as well as version information.</p>
                   
<p>Available flags are:</p>
<ul>
  <li>webkit (as of jQuery 1.4)</li>
  <li>safari (deprecated)</li>
  <li>opera</li>
  <li>msie</li>
  <li>mozilla</li>
</ul>

<p>This property is available immediately. It is therefore safe to use it to determine whether or not to call <code>$(document).ready()</code>.
The <code>$.browser</code> property is deprecated in jQuery 1.3, but there are no immediate plans to remove it.</p>

<p>Because <code>$.browser</code> uses <code>navigator.userAgent</code> to determine the platform, it is vulnerable to spoofing by the user or misrepresentation by the browser itself. It is always best to avoid browser-specific code entirely where possible. The <code>$.support</code> property is available for detection of support for particular features rather than relying on <code>$.browser</code>.</p></longdesc>
                <example>
                    <desc>Show the browser info.</desc>
                    <code><![CDATA[
    jQuery.each(jQuery.browser, function(i, val) {
      $("<div>" + i + " : <span>" + val + "</span>")
                .appendTo(document.body);
    });]]></code>
                    <css><![CDATA[
  p { color:green; font-weight:bolder; margin:3px 0 0 10px; }
  div { color:blue; margin-left:20px; font-size:14px; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<p>Browser info:</p>]]></html>
                </example>
                <example>
                    <desc>Returns true if the current useragent is some version of Microsoft's Internet Explorer.</desc>
                    <code><![CDATA[$.browser.msie]]></code>
                </example>
                <example>
                    <desc>Alerts "this is webkit!" only for webkit browsers</desc>
                    <code><![CDATA[if ($.browser.webkit) {
    alert("this is webkit!");
 }]]></code>
                </example>
                <example>
                    <desc>Alerts "Do stuff for firefox 3" only for firefox 3 browsers.</desc>
                    <code><![CDATA[jQuery.each(jQuery.browser, function(i, val) {
   if(i=="mozilla" && jQuery.browser.version.substr(0,3)=="1.9")
      alert("Do stuff for firefox 3")
 });]]></code>
                </example>
                <example>
                    <desc>Set a CSS property to specific browser.</desc>
                    <code><![CDATA[jQuery.each(jQuery.browser, function(i) {
   if($.browser.msie){
      $("#div ul li").css("display","inline");
   }else{
      $("#div ul li").css("display","inline-table");
   }
 });]]></code>
                </example>
<category name="Properties of the Global jQuery Object"/>
<category name="Utilities"/>
<category name="Version 1.0"/>
<category name="Version 1.1.3"/>
</entry>
<entry type='property' name="jQuery.browser.version" return="String">
  <signature><added>1.1.3</added></signature>
  <desc>The version number of the rendering engine for the user's browser.</desc>
  <longdesc>
    <p>Here are some typical results:</p>
    <ul>
      <li>Internet Explorer: 6.0, 7.0</li>
      <li>Mozilla/Firefox/Flock/Camino: 1.7.12, 1.8.1.3, 1.9</li>
      <li>Opera: 9.20</li>
      <li>Safari/Webkit: 312.8, 418.9</li>
    </ul>
    <p>Note that IE8 claims to be 7 in Compatibility View.</p>
  </longdesc>
  <example>
    <desc>Returns the browser version.</desc>
    <code><![CDATA[

    $("p").html("The browser version is: <span>" +
                jQuery.browser.version + "</span>");
]]></code>
    <css><![CDATA[
  p { color:blue; margin:20px; }
  span { color:red; }
  ]]></css>
    <html><![CDATA[<p>
  </p>]]></html>
  </example>
  <example>
      <desc>Alerts the version of IE that is being used</desc>
      <code><![CDATA[if ( $.browser.msie ) {
  alert( $.browser.version );
}]]></code>
  </example>
  <example>
    <desc>Often you only care about the "major number," the whole number. This can be accomplished with JavaScript's built-in parseInt() function:</desc>
    <code><![CDATA[
if (jQuery.browser.msie) {
  alert(parseInt(jQuery.browser.version));
}
]]></code>
  </example>
<category name="Properties of the Global jQuery Object"/>
<category name="Utilities"/>
<category name="Version 1.0"/>
<category name="Version 1.1.3"/>
</entry>

<entry type='method' name="live" return="jQuery">
  <desc>Attach a handler to the event for all elements which match the current selector, now and in the future.</desc>
  <signature>
    <added>1.3</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as "click" or "keydown." As of jQuery 1.4 the string can contain multiple, space-separated event types or custom event names, as well.</desc>
    </argument>
    <argument name="handler" type="Function">
      <desc>A function to execute at the time the event is triggered.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as "click" or "keydown." As of jQuery 1.4 the string can contain multiple, space-separated event types or custom event names, as well.</desc>
    </argument>
    <argument name="eventData" type="Object">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler" type="Function">
      <desc>A function to execute at the time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc>
  <p>This method is a variation on the basic <code>.bind()</code> method for attaching event handlers to elements. When <code>.bind()</code> is called, the elements that the jQuery object refers to get the handler attached; elements that get introduced later do not, so they would require another <code>.bind()</code> call. For instance, consider the HTML:</p>
<pre>&lt;body&gt;
  &lt;div class="clickme"&gt;
    Click here
  &lt;/div&gt;
&lt;/body&gt;
</pre>
  <p>We can bind a simple click handler to this element:</p>
<pre>$('.clickme').bind('click', function() {
  // Bound handler called.
});
</pre>
  <p>When the element is clicked, the handler is called. However, suppose that after this, another element is added:
  </p>
  <pre>$('body').append('&lt;div class="clickme"&gt;Another target&lt;/div&gt;');</pre>
  <p>This new element also matches the selector <code>.clickme</code>, but since it was added after the call to <code>.bind()</code>, clicks on it will do nothing.</p>
  <p>The <code>.live()</code> method provides an alternative to this behavior. If we bind a click handler to the target element using this method:</p>
<pre>$('.clickme').live('click', function() {
  // Live handler called.
});</pre>
  <p>And then later add a new element:</p>
  <pre>$('body').append('&lt;div class="clickme"&gt;Another target&lt;/div&gt;');</pre>
  <p>Then clicks on the new element will also trigger the handler.</p>
  <p>If we later wish to <em>unbind</em> the click handlers from all <code>&lt;div class="clickme"&gt;</code> that were bound using <code>.live()</code>, we can use the <code><a href="http://api.jquery.com/die/">.die()</a></code> method:</p>
<pre>$('.clickme').die('click');</pre>
  <h4 id="event-delegation">Event Delegation</h4>
  <p>The <code>.live()</code> method is able to affect elements that have not yet been added to the DOM through the use of event delegation: a handler bound to an ancestor element is responsible for events that are triggered on its descendants. The handler passed to <code>.live()</code> is never bound to an element; instead, <code>.live()</code> binds a special handler to the root of the DOM tree. In our example, when the new element is clicked, the following steps occur:</p>
  <ol>
    <li>A click event is generated and passed to the <code>&lt;div&gt;</code> for handling.</li>
    <li>No handler is directly bound to the <code>&lt;div&gt;</code>, so the event bubbles up the DOM tree.</li>
    <li>The event bubbles up until it reaches the root of the tree, which is where <code>.live()</code> binds its special handlers by default. <br /><em>* As of jQuery 1.4, event bubbling can optionally stop at a DOM element "context".</em></li>
    <li>The special <code>click</code> handler bound by <code>.live()</code> executes.</li>
    <li>This handler tests the <code>target</code> of the event object to see whether it should continue. This test is performed by checking if <code>$(event.target).closest('.clickme')</code> is able to locate a matching element.</li>
    <li>If a matching element is found, the original handler is called on it.</li>
  </ol>
  <p>Because the test in step 5 is not performed until the event occurs, elements can be added at any time and still respond to events.</p>
  <p>See the discussion for <code><a href="/bind">.bind()</a></code> for more information on event binding.</p>
  <h4 id="multiple-events">Multiple Events</h4>
  <p>As of jQuery 1.4.1 <code>.live()</code> can accept multiple, space-separated events, similar to the functionality provided in <a href="/bind">.bind()</a>. For example, we can "live bind" the <code>mouseover</code> and <code>mouseout</code> events at the same time like so: </p>
<pre>$('.hoverme').live('mouseover mouseout', function(event) {
  if (event.type == 'mouseover') {
    // do something on mouseover
  } else {
    // do something on mouseout
  }
});</pre>
  <h4 id="event-data">Event Data</h4>
  <p>As of jQuery 1.4, the optional <code>eventData</code> parameter allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. See the <code>.bind()</code> method's "<a href="/bind/#passing-event-data">Passing Event Data</a>" discussion for more information.</p>
  <h4 id="event-context">Event Context</h4>
  <p>As of jQuery 1.4, live events can be bound to a DOM element "context" rather than to the default document root. To set this context, we use the <a href="http://api.jquery.com/jquery/#selector-context"><code>jQuery()</code> function's second argument</a>, passing in a single DOM element (as opposed to a jQuery collection or a selector).</p>
<pre>$('div.clickme', $('#container')[0]).live('click', function() {
  // Live handler called.
});</pre>
  <p>The live handler in this example is called only when <code>&lt;div class="clickme"&gt;</code> is a descendant of an element with an ID of "container."</p>
  <h4 id="caveats">Caveats</h4>
  <p>The <code>.live()</code> technique is useful, but due to its special approach cannot be simply substituted for <code>.bind()</code> in all cases. Specific differences include:</p>
  <ul>
    <li>DOM traversal methods, or a context argument to the <code>jQuery()</code> method, are not supported for finding elements to send to <code>.live()</code>. Rather, the <code>.live()</code> method should always be called directly after a selector, as in the example above.</li>
    <li>To stop further handlers from executing after one bound using <code>.live()</code>, the handler must return <code>false</code>. Calling <code>.stopPropagation()</code> will not accomplish this.</li>
    <li>In <b>jQuery 1.3.x</b> only the following JavaScript events (in addition to custom events) could be bound with <code>.live()</code>: <code>click</code>, <code>dblclick</code>, <code>keydown</code>, <code>keypress</code>, <code>keyup</code>, <code>mousedown</code>, <code>mousemove</code>, <code>mouseout</code>, <code>mouseover</code>, and <code>mouseup</code>.</li>
  </ul>
  <blockquote>
    <ul>
      <li>As of <b>jQuery 1.4</b> the <code>.live()</code> method supports custom events as well as all JavaScript events. As of <b>jQuery 1.4.1</b> even <code>focus</code> and <code>blur</code> work with live (mapping to the more appropriate, bubbling, events <code>focusin</code> and <code>focusout</code>).</li>
      <li>As of <b>jQuery 1.4.1</b> the <code>hover</code> event can be specified (mapping to <code>mouseenter</code> and  <code>mouseleave</code>, which, in turn, are mapped to <code>mouseover</code> and <code>mouseout</code>).</li>
    </ul>
  </blockquote>
</longdesc>
  <example>
    <desc>Click a paragraph to add another. Note that .live() binds the click event to all paragraphs - even new ones.</desc>
    <code><![CDATA[
    $("p").live("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>To display each paragraph's text in an alert box whenever it is clicked:</desc>
    <code><![CDATA[$("p").live("click", function(){
  alert( $(this).text() );
});]]></code>
  </example>
  <example>
    <desc>To cancel a default action and prevent it from bubbling up, return false:</desc>
    <code><![CDATA[$("a").live("click", function() { return false; })]]></code>
  </example>
  <example>
    <desc>To cancel only the default action by using the preventDefault method.</desc>
    <code><![CDATA[$("a").live("click", function(event){
  event.preventDefault();
});]]></code>
  </example>
  <example>
    <desc>Can bind custom events too.</desc>
    <code><![CDATA[

    $("p").live("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.3"/>
</entry>
<entry type='method' name="triggerHandler" return="Object">
  <desc>Execute all handlers attached to an element for an event.</desc>
  <signature>
    <added>1.2</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</desc>
    </argument>
    <argument name="extraParameters" type="Array">
      <desc>An array of additional parameters to pass along to the event handler.</desc>
    </argument>
  </signature>
  <longdesc>
    <p>The <code>.triggerHandler()</code> method behaves similarly to <code>.trigger()</code>, with the following exceptions:</p>
    <ul>
    <li>The <code>.triggerHandler()</code> method does not cause the default behavior of an event to occur (such as a form submission).</li>
    <li>While <code>.trigger()</code> will operate on all elements matched by the jQuery object, <code>.triggerHandler()</code> only affects the first matched element.</li>
    <li>Events created with <code>.triggerHandler()</code> do not bubble up the DOM hierarchy; if they are not handled by the target element directly, they do nothing.</li>
    <li>Instead of returning the jQuery object (to allow chaining), <code>.triggerHandler()</code> returns whatever value was returned by the last handler it caused to be executed. If no handlers are triggered, it returns <code>undefined</code></li>
    </ul>
    <p>For more information on this method, see the discussion for <code><a href="/trigger">.trigger()</a></code>.</p>
  </longdesc>
  <example>
      <desc>If you called .triggerHandler() on a focus event - the browser's default focus action would not be triggered, only the event handlers bound to the focus event.</desc>
      <code><![CDATA[

$("#old").click(function(){
$("input").trigger("focus");
});
$("#new").click(function(){
$("input").triggerHandler("focus");
});
$("input").focus(function(){
$("<span>Focused!</span>").appendTo("body").fadeOut(1000);
});

]]></code>
      <html><![CDATA[<button id="old">.trigger("focus")</button>
<button id="new">.triggerHandler("focus")</button><br/><br/>

<input type="text" value="To Be Focused"/>]]></html>
  </example>
<category name="Event Handler Attachment"/>
<category name="Version 1.2"/>
</entry>

<entry type='method' name="trigger" return="jQuery">
  <desc>Execute all handlers and behaviors attached to the matched elements for the given event type.</desc>  
  <signature>
    <added>1.0</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</desc>
    </argument>
    <argument name="extraParameters" type="Array">
      <desc>An array of additional parameters to pass along to the event handler.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.3</added>
    <argument name="event" type="Event">
      <desc>A <a href="http://api.jquery.com/category/events/event-object/"><code>jQuery.Event</code></a> object.</desc>
    </argument>
  </signature>
  <longdesc>
    <p>Any event handlers attached with <code>.bind()</code> or one of its shortcut methods are triggered when the corresponding event occurs. They can be fired manually, however, with the <code>.trigger()</code> method. A call to <code>.trigger()</code> executes the handlers in the same order they would be if the event were triggered naturally by the user:</p>
    <pre>$('#foo').bind('click', function() {
      alert($(this).text());
    });
    $('#foo').trigger('click');</pre>
    <p>As of jQuery 1.3, <code>.trigger()</code>ed events bubble up the DOM tree; an event handler can stop the bubbling by returning <code>false</code> from the handler or calling the <a href="http://api.jquery.com/event.stopPropagation/"><code>.stopPropagation()</code></a> method on the event object passed into the event. Although <code>.trigger()</code> simulates an event activation, complete with a synthesized event object, it does not perfectly replicate a naturally-occurring event.</p>
    <p>To trigger handlers bound via jQuery without also triggering the native event, use <a href="http://api.jquery.com/triggerHandler/"><code>.triggerHandler()</code></a> instead. </p>
    <p>When we define a custom event type using the <code>.bind()</code> method, the second argument to <code>.trigger()</code> can become useful. For example, suppose we have bound a handler for the <code>custom</code> event to our element instead of the built-in <code>click</code> event as we did above:</p>
<pre>$('#foo').bind('custom', function(event, param1, param2) {
  alert(param1 + "\n" + param2);
});
$('#foo').trigger('custom', ['Custom', 'Event']);
</pre>
    <p>The event object is always passed as the first parameter to an event handler, but if additional parameters are specified during a <code>.trigger()</code> call as they are here, these parameters will be passed along to the handler as well.</p>
    <p>Note the difference between the extra parameters we're passing here and the <code>eventData</code> parameter to the <a href="/bind/">.bind()</a> method. Both are mechanisms for passing information to an event handler, but the <code>extraParameters</code> argument to <code>.trigger()</code> allows information to be determined at the time the event is triggered, while the <code>eventData</code> argument to <code>.bind()</code> requires the information to be already computed at the time the handler is bound.</p>    
  </longdesc>
   <example>
        <desc>Clicks to button #2 also trigger a click for button #1.</desc>
        <code><![CDATA[
$("button:first").click(function () {
update($("span:first"));
});
$("button:last").click(function () {
$("button:first").trigger('click');

update($("span:last"));
});

function update(j) {
var n = parseInt(j.text(), 10);
j.text(n + 1);
}
]]></code>
        <css><![CDATA[

button { margin:10px; }
div { color:blue; font-weight:bold; }
span { color:red; }
]]></css>
        <html><![CDATA[<button>Button #1</button>
<button>Button #2</button>
<div><span>0</span> button #1 clicks.</div>

<div><span>0</span> button #2 clicks.</div>]]></html>
    </example>
    <example>
        <desc>To submit the first form without using the submit() function, try:</desc>
        <code><![CDATA[$("form:first").trigger("submit")]]></code>
    </example>
    <example>
        <desc>To submit the first form without using the submit() function, try:</desc>
        <code><![CDATA[var event = jQuery.Event("submit");
$("form:first").trigger(event);
if ( event.isDefaultPrevented() ) {
// Perform an action...
}]]></code>
    </example>
    <example>
        <desc>To pass arbitrary data to an event:</desc>
        <code><![CDATA[$("p").click( function (event, a, b) {
// when a normal click fires, a and b are undefined
// for a trigger like below a refers to "foo" and b refers to "bar"

} ).trigger("click", ["foo", "bar"]);]]></code>
    </example>
    <example>
        <desc>To pass arbitrary data through an event object:</desc>
        <code><![CDATA[var event = jQuery.Event("logged");
event.user = "foo";
event.pass = "bar";
$("body").trigger(event);]]></code>
    </example>
    <example>
        <desc>Alternative way to pass data through an event object:</desc>
        <code><![CDATA[$("body").trigger({
type:"logged",
user:"foo",
pass:"bar"

});]]></code>
    </example>
<category name="Event Handler Attachment"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="ajaxComplete" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="handler(event, XMLHttpRequest, ajaxOptions)" type="Function">
	                    <desc>The function to be invoked.</desc>
	                </argument>
				</signature>
                <desc>Register a handler to be called when Ajax requests complete. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
                <longdesc><p>Whenever an Ajax request completes, jQuery triggers the <code>ajaxComplete</code> event. Any and all handlers that have been registered with the <code>.ajaxComplete()</code> method are executed at this time.</p>
				<p>To observe this method in action, we can set up a basic Ajax load request:</p>
				<pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;
</pre>
				<p>We can attach our event handler to any element:</p>
				<pre>$('.log').ajaxComplete(function() {
  $(this).text('Triggered ajaxComplete handler.');
});
</pre>
				<p>Now, we can make an Ajax request using any jQuery method:</p>
				<pre>$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});</pre>
				<p>When the user clicks the button and the Ajax request completes, the log message is displayed.</p>

				<p><strong>Note:</strong> Because <code>.ajaxComplete()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>

				<p>All <code>ajaxComplete</code> handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxComplete</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
				<pre>$('.log').ajaxComplete(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxComplete handler.');
  }
});</pre></longdesc>
                <example>
                    <desc>Show a message when an Ajax request completes.</desc>
                    <code><![CDATA[$("#msg").ajaxComplete(function(event,request, settings){
   $(this).append("<li>Request Complete.</li>");
 });]]></code>
                </example>
            <category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="one" return="jQuery">
  <desc>Attach a handler to an event for the elements. The handler is executed at most once per element.</desc>
  <signature>
    <added>1.1</added>
    <argument name="eventType" type="String">
      <desc>A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.</desc>
    </argument>
    <argument name="eventData" type="Object" optional="true">
      <desc>A map of data that will be passed to the event handler.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function">
      <desc>A function to execute at the time the event is triggered.</desc>
    </argument>
  </signature>
<longdesc>
<p>This method is identical to <code>.bind()</code>, except that the handler is unbound after its first invocation. For example:</p>
<pre>$('#foo').one('click', function() {
  alert('This will be displayed only once.');
});
</pre>
<p>After the code is executed, a click on the element with ID <code>foo</code> will display the alert. Subsequent clicks will do nothing. This code is equivalent to:</p>
<pre>$('#foo').bind('click', function(event) {
  alert('This will be displayed only once.');
  $(this).unbind(event);
});
</pre>
<p>In other words, explicitly calling <code>.unbind()</code> from within a regularly-bound handler has exactly the same effect.</p>
</longdesc>

<example>
    <desc>Tie a one-time click to each div.</desc>
    <code><![CDATA[
var n = 0;
$("div").one("click", function(){
var index = $("div").index(this);
$(this).css({ borderStyle:"inset",
    cursor:"auto" });
$("p").text("Div at index #" + index + " clicked." +
  "  That's " + ++n + " total clicks.");
});

]]></code>
    <css><![CDATA[
div { width:60px; height:60px; margin:5px; float:left;
background:green; border:10px outset; 
cursor:pointer; }
p { color:red; margin:0; clear:left; }
]]></css>
    <html><![CDATA[<div></div>
<div></div>
<div></div>
<div></div>

<div></div>
<p>Click a green square...</p>]]></html>
</example>
<example>
    <desc>To display the text of all paragraphs in an alert box the first time each of them is clicked:</desc>
    <code><![CDATA[$("p").one("click", function(){
alert( $(this).text() );
});]]></code>
</example>

<category name="Event Handler Attachment"/>
<category name="Version 1.1"/>
</entry>
           <entry type='method' name="serializeArray" return="Array">
				<signature>
                	<added>1.2</added>
				</signature>
                <desc>Encode a set of form elements as an array of names and values.</desc>
                <longdesc><p>The <code>.serializeArray()</code> method creates a JavaScript array of objects, ready to be encoded as a JSON string. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:</p>
				<pre>&lt;form&gt;
  &lt;div&gt;&lt;input type="text" name="a" value="1" id="a" /&gt;&lt;/div&gt;
  &lt;div&gt;&lt;input type="text" name="b" value="2" id="b" /&gt;&lt;/div&gt;
  &lt;div&gt;&lt;input type="hidden" name="c" value="3" id="c" /&gt;&lt;/div&gt;
  &lt;div&gt;
    &lt;textarea name="d" rows="8" cols="40"&gt;4&lt;/textarea&gt;
  &lt;/div&gt;
  &lt;div&gt;&lt;select name="e"&gt;
    &lt;option value="5" selected="selected"&gt;5&lt;/option&gt;
    &lt;option value="6"&gt;6&lt;/option&gt;
    &lt;option value="7"&gt;7&lt;/option&gt;
  &lt;/select&gt;&lt;/div&gt;
  &lt;div&gt;
    &lt;input type="checkbox" name="f" value="8" id="f" /&gt;
  &lt;/div&gt;
  &lt;div&gt;
    &lt;input type="submit" name="g" value="Submit" id="g" /&gt;
  &lt;/div&gt;
&lt;/form&gt;</pre>
				<p>The <code>.serializeArray()</code> method uses the standard W3C rules for <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.13.2">successful controls</a> to determine which elements it should include; in particular the element cannot be disabled and must contain a <code>name</code> attribute. No submit button value is serialized since the form was not submitted using a button. Data from file select elements is not serialized.</p>
<p>This method can act on a jQuery object that has selected individual form elements, such as <code>&lt;input&gt;</code>, <code>&lt;textarea&gt;</code>, and <code>&lt;select&gt;</code>. However, it is typically easier to select the <code>&lt;form&gt;</code> tag itself for serialization:</p>
				<pre>$('form').submit(function() {
  alert($(this).serializeArray());
  return false;
});</pre>
				<p>This produces the following data structure:</p>
				<pre>[
  {
    name: a
    value: 1
  },
  {
    name: b
    value: 2
  },
  {
    name: c
    value: 3
  },
  {
    name: d
    value: 4
  },
  {
    name: e
    value: 5
  }
]</pre></longdesc>
                <example>
                    <desc>Get the values from a form, iterate through them, and append them to a results display.</desc>
                    <code><![CDATA[

    function showValues() {
      var fields = $(":input").serializeArray();
      $("#results").empty();
      jQuery.each(fields, function(i, field){
        $("#results").append(field.value + " ");
      });
    }

    $(":checkbox, :radio").click(showValues);
    $("select").change(showValues);
    showValues();
]]></code>
                    <css><![CDATA[
  body, select { font-size:14px; }
  form { margin:5px; }
  p { color:red; margin:5px; }
  b { color:blue; }
  ]]></css>
                    <html><![CDATA[<p><b>Results:</b> <span id="results"></span></p>

  <form>
    <select name="single">
      <option>Single</option>
      <option>Single2</option>

    </select>
    <select name="multiple" multiple="multiple">
      <option selected="selected">Multiple</option>
      <option>Multiple2</option>

      <option selected="selected">Multiple3</option>
    </select><br/>
    <input type="checkbox" name="check" value="check1" id="ch1"/>

    <label for="ch1">check1</label>
    <input type="checkbox" name="check" value="check2" checked="checked" id="ch2"/>

    <label for="ch2">check2</label>
    <input type="radio" name="radio" value="radio1" checked="checked" id="r1"/>

    <label for="r1">radio1</label>
    <input type="radio" name="radio" value="radio2" id="r2"/>

    <label for="r2">radio2</label>
  </form>]]></html>
                </example>
            <category name="Forms"/>
<category name="Helper Functions"/>
<category name="Version 1.2"/>
</entry>
            <entry type='method' name="serialize" return="String">
				<signature>
                	<added>1.0</added>
				</signature>
                <desc>Encode a set of form elements as a string for submission.</desc>
                <longdesc><p>The <code>.serialize()</code> method creates a text string in standard URL-encoded notation. It operates on a jQuery object representing a set of form elements. The form elements can be of several types:</p>
				<pre>&lt;form&gt;
  &lt;div&gt;&lt;input type="text" name="a" value="1" id="a" /&gt;&lt;/div&gt;
  &lt;div&gt;&lt;input type="text" name="b" value="2" id="b" /&gt;&lt;/div&gt;
  &lt;div&gt;&lt;input type="hidden" name="c" value="3" id="c" /&gt;&lt;/div&gt;
  &lt;div&gt;
    &lt;textarea name="d" rows="8" cols="40"&gt;4&lt;/textarea&gt;
  &lt;/div&gt;
  &lt;div&gt;&lt;select name="e"&gt;
    &lt;option value="5" selected="selected"&gt;5&lt;/option&gt;
    &lt;option value="6"&gt;6&lt;/option&gt;
    &lt;option value="7"&gt;7&lt;/option&gt;
  &lt;/select&gt;&lt;/div&gt;
  &lt;div&gt;
    &lt;input type="checkbox" name="f" value="8" id="f" /&gt;
  &lt;/div&gt;
  &lt;div&gt;
    &lt;input type="submit" name="g" value="Submit" id="g" /&gt;
  &lt;/div&gt;
&lt;/form&gt;</pre>
				<p>The <code>.serialize()</code> method can act on a jQuery object that has selected individual form elements, such as <code>&lt;input&gt;</code>, <code>&lt;textarea&gt;</code>, and <code>&lt;select&gt;</code>. However, it is typically easier to select the <code>&lt;form&gt;</code> tag itself for serialization:</p>
				<pre>$('form').submit(function() {
  alert($(this).serialize());
  return false;
});</pre>
				<p>This produces a standard-looking query string:</p>
				<pre>a=1&amp;b=2&amp;c=3&amp;d=4&amp;e=5</pre>
<p>Note: Only <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.13.2">"successful controls"</a> are serialized to the string. No submit button value is serialized since the form was not submitted using a button. For a form element's value to be included in the serialized string, the element must have a <code>name</code> attribute. Data from file select elements is not serialized.</p>
</longdesc>
                <example>
                    <desc>Serialize a form to a query string, that could be sent to a server in an Ajax request.</desc>
                    <code><![CDATA[
    function showValues() {
      var str = $("form").serialize();
      $("#results").text(str);
    }
    $(":checkbox, :radio").click(showValues);
    $("select").change(showValues);
    showValues();
]]></code>
                    <css><![CDATA[
  body, select { font-size:12px; }
  form { margin:5px; }
  p { color:red; margin:5px; font-size:14px; }
  b { color:blue; }
  ]]></css>
    <height>200</height>
                    <html><![CDATA[

<form>
    <select name="single">
      <option>Single</option>
      <option>Single2</option>
    </select>

<br />
    <select name="multiple" multiple="multiple">
      <option selected="selected">Multiple</option>
      <option>Multiple2</option>

      <option selected="selected">Multiple3</option>
    </select>
<br/>
    <input type="checkbox" name="check" value="check1" id="ch1"/>

    <label for="ch1">check1</label>

    <input type="checkbox" name="check" value="check2" checked="checked" id="ch2"/>

    <label for="ch2">check2</label>
<br />
    <input type="radio" name="radio" value="radio1" checked="checked" id="r1"/>

    <label for="r1">radio1</label>
    <input type="radio" name="radio" value="radio2" id="r2"/>

    <label for="r2">radio2</label>
  </form>
  <p><tt id="results"></tt></p>]]></html>
                </example>
            <category name="Forms"/>
<category name="Helper Functions"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="jQuery.ajaxSetup" return="">
				<signature>
                	<added>1.1</added>
	                <argument name="options" type="Options">
	                    <desc>A set of key/value pairs that configure the default Ajax request. All options are optional. </desc>
	                </argument>
				</signature>
                <desc>Set default values for future Ajax requests.</desc>
                <longdesc><p>For details on the settings available for <code>$.ajaxSetup()</code>, see <code><a href='/jQuery.ajax'>$.ajax()</a></code>. </p>
				<p>All subsequent Ajax calls using any function will use the new settings, unless overridden by the individual calls, until the next invocation of <code>$.ajaxSetup()</code>.</p>
				<p>For example, we could set a default for the URL parameter before pinging the server repeatedly:</p>
				<pre>$.ajaxSetup({
  url: 'ping.php',
});</pre>
				<p>Now each time an Ajax request is made, this URL will be used automatically:</p>
				<pre>
$.ajax({
  data: {'name': 'Tim'},
});</pre>

				<blockquote><p>Note: Global callback functions should be set with their respective global Ajax event handler methods-<code><a href='/ajaxStart'>.ajaxStart()</a></code>, <code><a href='/ajaxStop'>.ajaxStop()</a></code>, <code><a href='/ajaxComplete'>.ajaxComplete()</a></code>, <code><a href='/ajaxError'>.ajaxError()</a></code>, <code><a href='/ajaxSuccess'>.ajaxSuccess()</a></code>, <code><a href='/ajaxSend'>.ajaxSend()</a></code>-rather than within the <code>settings</code> object for <code>$.ajaxSetup()</code>.</p></blockquote></longdesc>
                <example>
                    <desc>Sets the defaults for Ajax requests to the url "/xmlhttp/", disables global handlers and uses POST instead of GET. The following Ajax requests then sends some data without having to set anything else.</desc>
                    <code><![CDATA[$.ajaxSetup({
   url: "/xmlhttp/",
   global: false,
   type: "POST"

 });
 $.ajax({ data: myData });]]></code>
                </example>
            <category name="Low-Level Interface"/>
<category name="Version 1.1"/>
</entry>
<entry type='method' name="ajaxSuccess" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="handler(event, XMLHttpRequest, ajaxOptions)" type="Function">
      <desc>The function to be invoked.</desc>
    </argument>
  </signature>
<desc>Attach a function to be executed whenever an Ajax request completes successfully. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
  <longdesc>
    <p>Whenever an Ajax request completes successfully, jQuery triggers the <code>ajaxSuccess</code> event. Any and all handlers that have been registered with the <code>.ajaxSuccess()</code> method are executed at this time.</p>
    <p>To observe this method in action, we can set up a basic Ajax load request:</p>
		<pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;</pre>
    <p>We can attach our event handler to any element:</p>
    <pre>$('.log').ajaxSuccess(function() {
  $(this).text('Triggered ajaxSuccess handler.');
});</pre>
    <p>Now, we can make an Ajax request using any jQuery method:</p>
    <pre>$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});</pre>
		<p>When the user clicks the button and the Ajax request completes successfully, the log message is displayed.</p>


    <p><strong>Note:</strong> Because <code>.ajaxSuccess()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>

		<p>All <code>ajaxSuccess</code> handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxSuccess</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the settings object that was used in the creation of the request. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
	  <pre>$('.log').ajaxSuccess(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSuccess handler.');
  }
});</pre>
  </longdesc>
  <example>
    <desc>Show a message when an Ajax request completes successfully.</desc>
    <code><![CDATA[$("#msg").ajaxSuccess(function(evt, request, settings){
      $(this).append("<li>Successful Request!</li>");
      });]]></code>
  </example>
<category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="ajaxStop" return="jQuery">
  <desc>Register a handler to be called when all Ajax requests have completed. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
  <signature>
    <added>1.0</added>
    <argument name="handler()" type="Function">
      <desc>The function to be invoked.</desc>
    </argument>
  </signature>
  <longdesc>
    <p>Whenever an Ajax request completes, jQuery checks whether there are any other outstanding Ajax requests. If none remain, jQuery triggers the <code>ajaxStop</code> event. Any and all handlers that have been registered with the <code>.ajaxStop()</code> method are executed at this time.</p>
    <p>To observe this method in action, we can set up a basic Ajax load request:</p>
    <pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;</pre>
    <p>We can attach our event handler to any element:</p>
    <pre>$('.log').ajaxStop(function() {
  $(this).text('Triggered ajaxStop handler.');
});</pre>
    <p>Now, we can make an Ajax request using any jQuery method:</p>
    <pre>$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});</pre>
    <p>When the user clicks the button and the Ajax request completes, the log message is displayed.</p>
  	<p>Because <code>.ajaxStop()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
  </longdesc>
  <example>
    <desc>Hide a loading message after all the Ajax requests have stopped.</desc>
    <code><![CDATA[$("#loading").ajaxStop(function(){
      $(this).hide();
      });]]></code>
  </example>
<category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="ajaxStart" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="handler()" type="Function">
	                    <desc>The function to be invoked.</desc>
	                </argument>
				</signature>
                <desc>Register a handler to be called when the first Ajax request begins. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
                <longdesc><p>Whenever an Ajax request is about to be sent, jQuery checks whether there are any other outstanding Ajax requests. If none are in progress, jQuery triggers the <code>ajaxStart</code> event. Any and all handlers that have been registered with the <code>.ajaxStart()</code> method are executed at this time.</p>
				<p>To observe this method in action, we can set up a basic Ajax load request:</p>
				<pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;</pre>
				<p>We can attach our event handler to any element:</p>
				<pre>$('.log').ajaxStart(function() {
  $(this).text('Triggered ajaxStart handler.');
});</pre>
				<p>Now, we can make an Ajax request using any jQuery method:</p>
				<pre>$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});</pre>
				<p>When the user clicks the button and the Ajax request is sent, the log message is displayed.</p>

				<p><strong>Note:</strong> Because <code>.ajaxStart()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>
</longdesc>
                <example>
                    <desc>Show a loading message whenever an Ajax request starts (and none is already active).</desc>
                    <code><![CDATA[$("#loading").ajaxStart(function(){
   $(this).show();
 });]]></code>
                </example>
<category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="ajaxSend" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="handler(event, XMLHttpRequest, ajaxOptions)" type="Function">
      <desc>The function to be invoked.</desc>
    </argument>
  </signature>
<desc>Attach a function to be executed before an Ajax request is sent. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
  <longdesc>
    <p>Whenever an Ajax request is about to be sent, jQuery triggers the <code>ajaxSend</code> event. Any and all handlers that have been registered with the <code>.ajaxSend()</code> method are executed at this time.</p>
    <p>To observe this method in action, we can set up a basic Ajax load request:</p>
<pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;</pre>
    <p>We can attach our event handler to any element:</p>
<pre>$('.log').ajaxSend(function() {
  $(this).text('Triggered ajaxSend handler.');
});</pre>
    <p>Now, we can make an Ajax request using any jQuery method:</p>
    <pre>$('.trigger').click(function() {
  $('.result').load('ajax/test.html');
});</pre>
    <p>When the user clicks the button and the Ajax request is about to begin, the log message is displayed.</p>

    <p><strong>Note:</strong> Because <code>.ajaxSend()</code> is implemented as a method of jQuery instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>

    <p>All <code>ajaxSend</code> handlers are invoked, regardless of what Ajax request is to be sent. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxSend</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the <a href='http://api.jquery.com/jQuery.ajax/'>settings object</a> that was used in the creation of the Ajax request. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
    <pre>$('.log').ajaxSend(function(e, xhr, settings) {
  if (settings.url == 'ajax/test.html') {
    $(this).text('Triggered ajaxSend handler.');
  }
});</pre>
    </longdesc>
    <example>
      <desc>Show a message before an Ajax request is sent.</desc>
      <code><![CDATA[$("#msg").ajaxSend(function(evt, request, settings){
        $(this).append("<li>Starting request at " + settings.url + "</li>");
      });]]></code>
    </example>
<category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="ajaxError" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="handler(event, XMLHttpRequest, ajaxOptions, thrownError)" type="Function">
	                    <desc>The function to be invoked.</desc>
	                </argument>
				</signature>
                <desc>Register a handler to be called when Ajax requests complete with an error. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
                <longdesc><p>Whenever an Ajax request completes with an error, jQuery triggers the <code>ajaxError</code> event. Any and all handlers that have been registered with the <code>.ajaxError()</code> method are executed at this time.</p>
				<p>To observe this method in action, we can set up a basic Ajax load request:</p>
				<pre>&lt;div class="trigger"&gt;Trigger&lt;/div&gt;
&lt;div class="result"&gt;&lt;/div&gt;
&lt;div class="log"&gt;&lt;/div&gt;</pre>
				<p>We can attach our event handler to any element:</p>
				<pre>$('.log').ajaxError(function() {
  $(this).text('Triggered ajaxError handler.');
});</pre>
				<p>Now, we can make an Ajax request using any jQuery method:</p>
				<pre>$('.trigger').click(function() {
  $('.result').load('ajax/missing.html');
});</pre>
				<p>When the user clicks the button and the Ajax request fails, because the requested file is missing, the log message is displayed.</p>

				<p><strong>Note:</strong> Because <code>.ajaxError()</code> is implemented as a method of jQuery object instances, we can use the <code>this</code> keyword as we do here to refer to the selected elements within the callback function.</p>

				<p>All <code>ajaxError</code> handlers are invoked, regardless of what Ajax request was completed. If we must differentiate between the requests, we can use the parameters passed to the handler. Each time an <code>ajaxError</code> handler is executed, it is passed the event object, the <code>XMLHttpRequest</code> object, and the settings object that was used in the creation of the request. If the request failed because JavaScript raised an exception, the exception object is passed to the handler as a fourth parameter. For example, we can restrict our callback to only handling events dealing with a particular URL:</p>
				<pre>$('.log').ajaxError(function(e, xhr, settings, exception) {
  if (settings.url == 'ajax/missing.html') {
    $(this).text('Triggered ajaxError handler.');
  }
});</pre></longdesc>
                <example>
                    <desc>Show a message when an Ajax request fails.</desc>
                    <code><![CDATA[$("#msg").ajaxError(function(event, request, settings){
   $(this).append("<li>Error requesting page " + settings.url + "</li>");
 });]]></code>
                </example>
            <category name="Global Ajax Event Handlers"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="unbind" return="jQuery">
  <desc>Remove a previously-attached event handler from the elements.</desc>
  <signature>
    <added>1.0</added>
    <argument name="eventType" type="String" optional="true">
      <desc>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</desc>
    </argument>
    <argument name="handler(eventObject)" type="Function" optional="true">
      <desc>The function that is to be no longer executed.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="eventType" type="String">
      <desc>A string containing a JavaScript event type, such as <code>click</code> or <code>submit</code>.</desc>
    </argument>
    <argument name="false" type="Boolean">
      <desc>Unbinds the corresponding 'return false' function that was bound using <code>.bind( eventType, false )</code>.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
    <argument name="event" type="Object">
      <desc>A JavaScript event object as passed to an event handler.</desc>
    </argument>
  </signature>
<longdesc>
    <p>Any handler that has been attached with <code>.bind()</code> can be removed with <code>.unbind()</code>. In the simplest case, with no arguments, <code>.unbind()</code> removes all handlers attached to the elements:</p>
<pre>$('#foo').unbind();</pre>
<p>This version removes the handlers regardless of type. To be more precise, we can pass an event type:</p>
<pre>$('#foo').unbind('click');</pre>
<p>By specifying the <code>click</code> event type, only handlers for that event type will be unbound. This approach can still have negative ramifications if other scripts might be attaching behaviors to the same element, however. Robust and extensible applications typically demand the two-argument version for this reason:</p>
<pre>var handler = function() {
  alert('The quick brown fox jumps over the lazy dog.');
};
$('#foo').bind('click', handler);
$('#foo').unbind('click', handler);
</pre>
<p>By naming the handler, we can be assured that no other functions are caught in the crossfire. Note that the following will <em>not</em> work:</p>
<pre>$('#foo').bind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});

// will NOT work
$('#foo').unbind('click', function() {
  alert('The quick brown fox jumps over the lazy dog.');
});</pre>
<p>Even though the two functions are identical in content, they are created separately and so JavaScript is free to keep them as distinct function objects. To unbind a particular handler, we need a reference to that function and not a different one that happens to do the same thing.</p>
<h4>Using Namespaces</h4>
<p>Instead of maintaining references to handlers in order to unbind them, we can namespace the events and use this capability to narrow the scope of our unbinding actions. As shown in the discussion for the <code>.bind()</code> method, namespaces are defined by using a period (<code>.</code>) character when binding a handler:</p>
<pre>$('#foo').bind('click.myEvents', handler);</pre>
<p>When a handler is bound in this fashion, we can still unbind it the normal way:</p>
<pre>$('#foo').unbind('click');</pre>
<p>However, if we want to avoid affecting other handlers, we can be more specific:</p>
<pre>$('#foo').unbind('click.myEvents');</pre>
<p>If multiple namespaced handlers are bound, we can unbind them at once:</p>
<pre>$('#foo').unbind('click.myEvents.yourEvents');</pre>
<p>This syntax is similar to that used for CSS class selectors; they are not hierarchical. This method call is thus the same as:</p>
<pre>$('#foo').unbind('click.yourEvents.myEvents');</pre>
<p>We can also unbind all of the handlers in a namespace, regardless of event type:</p>
<pre>$('#foo').unbind('.myEvents');</pre>
<p>It is particularly useful to attach namespaces to event bindings when we are developing plug-ins or otherwise writing code that may interact with other event-handling code in the future.</p>
<h4>Using the Event Object</h4>
<p>The third form of the <code>.unbind()</code> method is used when we wish to unbind a handler from within itself. For example, suppose we wish to trigger an event handler only three times:</p>
<pre>var timesClicked = 0;
$('#foo').bind('click', function(event) {
  alert('The quick brown fox jumps over the lazy dog.');
  timesClicked++;
  if (timesClicked &gt;= 3) {
    $(this).unbind(event);
  }
});
</pre>
<p>The handler in this case must take a parameter, so that we can capture the event object and use it to unbind the handler after the third click. The event object contains the context necessary for <code>.unbind()</code> to know which handler to remove.
This example is also an illustration of a closure. Since the handler refers to the <code>timesClicked</code> variable, which is defined outside the function, incrementing the variable has an effect even between invocations of the handler.</p>
</longdesc>
<example>
    <desc>Can bind and unbind events to the colored button.</desc>
    <code><![CDATA[

function aClick() {
$("div").show().fadeOut("slow");
}
$("#bind").click(function () {
// could use .bind('click', aClick) instead but for variety...
$("#theone").click(aClick)
  .text("Can Click!");
});
$("#unbind").click(function () {
$("#theone").unbind('click', aClick)
  .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>To unbind all events from all paragraphs, write:</desc>
    <code><![CDATA[$("p").unbind()]]></code>
</example>
<example>
    <desc>To unbind all click events from all paragraphs, write:</desc>
    <code><![CDATA[$("p").unbind( "click" )]]></code>
</example>
<example>
    <desc>To unbind just one previously bound handler, pass the function in as the second argument:</desc>
    <code><![CDATA[var foo = function () {
// code to handle some kind of event
};

$("p").bind("click", foo); // ... now foo will be called when paragraphs are clicked ...

$("p").unbind("click", foo); // ... foo will no longer be called.]]></code>
</example>
<category name="Event Handler Attachment"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="bind" return="jQuery">
<signature>
  <added>1.0</added>
  <argument name="eventType" type="String">
    <desc>A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.</desc>
  </argument>
  <argument name="eventData" type="Object" optional="true">
    <desc>A map of data that will be passed to the event handler.</desc>
  </argument>
  <argument name="handler(eventObject)" type="Function">
    <desc>A function to execute each time the event is triggered.</desc>
  </argument>
</signature>
<signature>
  <added>1.4.3</added>
  <argument name="eventType" type="String">
    <desc>A string containing one or more JavaScript event types, such as "click" or "submit," or custom event names.</desc>
  </argument>
  <argument name="eventData" type="Object" optional="true">
    <desc>A map of data that will be passed to the event handler.</desc>
  </argument>
  <argument name="false" type="Boolean">
    <desc>Setting the third argument to false will attach a function that prevents the default action from occurring and stops the event from bubbling.</desc>
  </argument>
</signature>
<signature>
  <added>1.4</added>
  <argument name="events" type="Object">
    <desc>A map of one or more JavaScript event types and functions to execute for them.</desc>
  </argument>
</signature>
<desc>Attach a handler to an event for the elements.</desc>
<longdesc><p>The <code>.bind()</code> method is the primary means of attaching behavior to a document. All JavaScript event types, such as <code>focus</code>, <code>mouseover</code>, and <code>resize</code>, are allowed for <code>eventType.</code> (The <code>beforeunload</code> and <code>error</code> events on the <code>window</code> object use nonstandard conventions and are not supported by jQuery; attach a handler directly to the <code>window</code> object instead.) </p>
<p>The jQuery library provides shortcut methods for binding the standard event types, such as <code>.click()</code> for <code>.bind('click')</code>. A description of each can be found in the discussion of its shortcut method: <a href="/blur">blur</a>, <a href="/focus">focus</a>, <a href="/focusin">focusin</a>, <a href="/focusout">focusout</a>, <a href="/load-event">load</a>, <a href="/resize">resize</a>, <a href="/scroll">scroll</a>, <a href="/unload">unload</a>, <a href="/click">click</a>, <a href="/dblclick">dblclick</a>, <a href="/mousedown">mousedown</a>, <a href="/mouseup">mouseup</a>, <a href="/mousemove">mousemove</a>, <a href="/mouseover">mouseover</a>, <a href="/mouseout">mouseout</a>, <a href="/mouseenter">mouseenter</a>, <a href="/mouseleave">mouseleave</a>, <a href="/change">change</a>, <a href="/select">select</a>, <a href="/submit">submit</a>, <a href="/keydown">keydown</a>, <a href="/keypress">keypress</a>, <a href="/keyup">keyup</a>,  <a href="/error">error</a></p>

<p>Any string is legal for <code>eventType</code>; if the string is not the name of a native JavaScript event, then the handler is bound to a custom event. These events are never called by the browser, but may be triggered manually from other JavaScript code using <code>.trigger()</code> or <code>.triggerHandler()</code>.</p>
<p>If the <code>eventType</code> string contains a period (<code>.</code>) character, then the event is namespaced. The period character separates the event from its namespace. For example, in the call <code>.bind('click.name', handler)</code>, the string <code>click</code> is the event type, and the string <code>name</code> is the namespace. Namespacing allows us to unbind or trigger some events of a type without affecting others. See the discussion of <code>.unbind()</code> for more information.</p>
<p>When an event reaches an element, all handlers bound to that event type for the element are fired. If there are multiple handlers registered, they will always execute in the order in which they were bound. After all handlers have executed, the event continues along the normal event propagation path.</p>
<p>A basic usage of <code>.bind()</code> is:</p>
<pre>
$('#foo').bind('click', function() {
  alert('User clicked on "foo."');
});
</pre>
<p>This code will cause the element with an ID of <code>foo</code> to respond to the <code>click</code> event. When a user clicks inside this element thereafter, the alert will be shown.</p>
<h4 id="multiple-events">Multiple Events</h4>
<p>Multiple event types can be bound at once by including each one separated by a space:</p>
<pre>
$('#foo').bind('mouseenter mouseleave', function() {
  $(this).toggleClass('entered');
});
</pre>
<p>The effect of this on <code>&lt;div id="foo"&gt;</code> (when it does not initially have the "entered" class) is to add the "entered" class when the mouse enters the <code>&lt;div&gt;</code> and remove the class when the mouse leaves. </p>
<p>As of jQuery 1.4 we can bind multiple event handlers simultaneously by passing a map of event type/handler pairs:</p>
<pre>
$('#foo').bind({
  click: function() {
    // do something on click
  },
  mouseenter: function() {
    // do something on mouseenter
  }
});
</pre>
<h4 id="event-handlers">Event Handlers</h4>
<p>The <code>handler</code> parameter takes a callback function, as shown above. Within the handler, the keyword <code>this</code> refers to the DOM element to which the handler is bound. To make use of the element in jQuery, it can be passed to the normal <code>$()</code> function. For example:</p>
<pre>$('#foo').bind('click', function() {
  alert($(this).text());
});
</pre>
<p>After this code is executed, when the user clicks inside the element with an ID of <code>foo</code>, its text contents will be shown as an alert.
</p>
<p>As of jQuery 1.4.2 duplicate event handlers can be bound to an element instead of being discarded. For example:</p>
<pre>function test(){ alert("Hello"); }
$("button").click( test );
$("button").click( test );</pre>
<p>The above will generate two alerts when the button is clicked.</p>

<p>In jQuery 1.4.3 you can now pass in 'false' in place of an event handler. This will bind an event handler that's equivalent to: <code>function(){ return false; }</code>. This function can be removed at a later time by calling: <code>.unbind( eventName, false )</code>.</p>

<h4 id="event-object"><a href="/category/events/event-object/">The Event object</a></h4>
<p>The <code>handler</code> callback function can also take parameters. When the function is called, the JavaScript event object will be passed to the first parameter.</p>
<p>The event object is often unnecessary and the parameter omitted, as sufficient context is usually available when the handler is bound to know exactly what needs to be done when the handler is triggered. However, at times it becomes necessary to gather more information about the user's environment at the time the event was initiated. <a href="/category/events/event-object/">View the full Event Object</a>.</p>

<p>Returning <code>false</code> from a handler is equivalent to calling both <code>.preventDefault()</code> and <code>.stopPropagation()</code> on the event object.</p>
<p>Using the event object in a handler looks like this:</p>
<pre>$(document).ready(function() {
  $('#foo').bind('click', function(event) {
    alert('The mouse cursor is at ('
      + event.pageX + ', ' + event.pageY + ')');
  });
});
</pre>
<p>Note the parameter added to the anonymous function. This code will cause a click on the element with ID <code>foo</code> to report the page coordinates of the mouse cursor at the time of the click.</p>

<h4 id="passing-event-data">Passing Event Data</h4>
<p>The optional <code>eventData</code> parameter is not commonly used. When provided, this argument allows us to pass additional information to the handler. One handy use of this parameter is to work around issues caused by closures. For example, suppose we have two event handlers that both refer to the same external variable:</p>
<pre>var message = 'Spoon!';
$('#foo').bind('click', function() {
  alert(message);
});
message = 'Not in the face!';
$('#bar').bind('click', function() {
  alert(message);
});
</pre>
<p>Because the handlers are closures that both have <code>message</code> in their environment, both will display the message <span class="output">Not in the face!</span> when triggered. The variable's value has changed. To sidestep this, we can pass the message in using <code>eventData</code>:
</p>
<pre>var message = 'Spoon!';
$('#foo').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});
message = 'Not in the face!';
$('#bar').bind('click', {msg: message}, function(event) {
  alert(event.data.msg);
});
</pre>
<p>This time the variable is not referred to directly within the handlers; instead, the variable is passed in <em>by value</em> through <code>eventData</code>, which fixes the value at the time the event is bound. The first handler will now display <span class="output">Spoon!</span> while the second will alert <span class="output">Not in the face!</span>
</p>
<blockquote>
  <p>Note that objects are passed to functions <em>by reference</em>, which further complicates this scenario.</p>
</blockquote>
<p>If <code>eventData</code> is present, it is the second argument to the <code>.bind()</code> method; if no additional data needs to be sent to the handler, then the callback is passed as the second and final argument.</p>
<blockquote><p>See the <code>.trigger()</code> method reference for a way to pass data to a handler at the time the event happens rather than when the handler is bound.</p></blockquote>

<p>As of jQuery 1.4 we can no longer attach data (and thus, events) to object, embed, or applet elements because critical errors occur when attaching data to Java applets.</p>
</longdesc>
<example>
    <desc>Handle click and double-click for the paragraph.  Note: the coordinates are window relative, so in this case relative to the demo iframe.</desc>
    <code><![CDATA[
$("p").bind("click", function(event){
var str = "( " + event.pageX + ", " + event.pageY + " )";
$("span").text("Click happened! " + str);
});
$("p").bind("dblclick", function(){
$("span").text("Double-click happened in " + this.nodeName);
});
$("p").bind("mouseenter mouseleave", function(event){
$(this).toggleClass("over");
});

]]></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 or double click here.</p>
<span></span>]]></html>
</example>
<example>
    <desc>To display each paragraph's text in an alert box whenever it is clicked:</desc>
    <code><![CDATA[$("p").bind("click", function(){
alert( $(this).text() );
});]]></code>
</example>
<example>
    <desc>You can pass some extra data before the event handler:</desc>
    <code><![CDATA[function handler(event) {
alert(event.data.foo);
}
$("p").bind("click", {foo: "bar"}, handler)]]></code>
</example>
<example>
    <desc>Cancel a default action and prevent it from bubbling up by returning <code>false</code>:</desc>
    <code><![CDATA[$("form").bind("submit", function() { return false; })]]></code>
</example>
<example>
    <desc>Cancel only the default action by using the .preventDefault() method.</desc>
    <code><![CDATA[$("form").bind("submit", function(event) {
event.preventDefault();
});]]></code>
</example>
<example>
    <desc>Stop an event from bubbling without preventing the default action by using the .stopPropagation() method.</desc>
    <code><![CDATA[$("form").bind("submit", function(event) {
  event.stopPropagation();
});]]></code>
</example>
<example>
    <desc>Bind custom events.</desc>
    <code><![CDATA[

$("p").bind("myCustomEvent", function(e, myName, myValue){
$(this).text(myName + ", hi there!");
$("span").stop().css("opacity", 1)
.text("myName = " + myName)
.fadeIn(30).fadeOut(1000);
});
$("button").click(function () {
$("p").trigger("myCustomEvent", [ "John" ]);
});

]]></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>
<example>
<desc>Bind multiple events simultaneously.</desc>
<code><![CDATA[$("div.test").bind({
  click: function(){
    $(this).addClass("active");
  },
  mouseenter: function(){
    $(this).addClass("inside");
  },
  mouseleave: function(){
    $(this).removeClass("inside");
  }
});]]></code>
</example>
<category name="Event Handler Attachment"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
<category name="Version 1.4.3"/>
</entry>
            <entry type='method' name="first" return="jQuery">
              <signature>
                <added>1.4</added>
              </signature>
              <desc>Reduce the set of matched elements to the first in the set.</desc>
              <longdesc>[<p>Given a jQuery object that represents a set of DOM elements, the <code>.first()</code> method constructs a new jQuery object from the first matching element.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can apply this method to the set of list items:</p>
<pre>$('li').first().css('background-color', 'red');</pre>
<p>The result of this call is a red background for the first item.</p></longdesc>
                <example>
                    <desc>Highlight the first span in a paragraph.</desc>
                    <css><![CDATA[.highlight{background-color: yellow}]]></css>
                    <code><![CDATA[$("p span").first().addClass('highlight');]]></code>
                    <html><![CDATA[<p><span>Look:</span> <span>This is some text in a paragraph.</span> <span>This is a note about it.</span></p>]]></html>
                </example>
            <category name="Filtering"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="last" return="jQuery">
              <signature>
                <added>1.4</added>
              </signature>
              <desc>Reduce the set of matched elements to the final one in the set.</desc>
              <longdesc>[<p>Given a jQuery object that represents a set of DOM elements, the <code>.last()</code> method constructs a new jQuery object from the last matching element.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can apply this method to the set of list items:</p>
<pre>$('li').last().css('background-color', 'red');</pre>
<p>The result of this call is a red background for the final item.</p></longdesc>
                <example>
                    <desc>Highlight the last span in a paragraph.</desc>
                    <css><![CDATA[.highlight{background-color: yellow}]]></css>
                    <code><![CDATA[$("p span").last().addClass('highlight');]]></code>
                    <html><![CDATA[<p><span>Look:</span> <span>This is some text in a paragraph.</span> <span>This is a note about it.</span></p>]]></html>
                </example>
            <category name="Filtering"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="slice" return="jQuery">
              <signature>
                <added>1.1.4</added>
                <argument name="start" type="Integer">
                    <desc>An integer indicating the 0-based position at which the elements begin to be selected. If negative, it indicates an offset from the end of the set.</desc>
                </argument>
                <argument name="end" optional="true" type="Integer">
                    <desc>An integer indicating the 0-based position at which the elements stop being selected. If negative, it indicates an offset from the end of the set. If omitted, the range continues until the end of the set.</desc>
                </argument>
              </signature>
              <desc>Reduce the set of matched elements to a subset specified by a range of indices.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.slice()</code> method constructs a new jQuery object from a subset of the matching elements. The supplied <code>start</code> index identifies the position of one of the elements in the set; if <code>end</code> is omitted, all elements after this one will be included in the result.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can apply this method to the set of list items:</p>
<pre>$('li').slice(2).css('background-color', 'red');</pre>
<p>The result of this call is a red background for items 3, 4, and 5. Note that the supplied index is zero-based, and refers to the position of elements within the jQuery object, not within the DOM tree.</p>
<p>The end parameter allows us to limit the selected range even further. For example:</p>
<pre>$('li').slice(2, 4).css('background-color', 'red');</pre>
<p>Now only items 3 and 4 are selected. The index is once again zero-based; the range extends up to but not including the specified index.</p>
<h4>Negative Indices</h4>
<p>The jQuery <code>.slice()</code> method is patterned after the JavaScript .slice() method for arrays. One of the features that it mimics is the ability for negative numbers to be passed as either the <code>start</code> or <code>end</code> parameter. If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:</p>
<pre>$('li').slice(-2, -1).css('background-color', 'red');</pre>
<p>This time only list item 4 is turned red, since it is the only item in the range between two from the end (<code>-2</code>) and one from the end (<code>-1</code>).</p></longdesc>
                <example>
                    <desc>Turns divs yellow based on a random slice.</desc>
                    <code><![CDATA[

    function colorEm() {
      var $div = $("div");
      var start = Math.floor(Math.random() *
                             $div.length);
      var end = Math.floor(Math.random() *
                           ($div.length - start)) +
                           start + 1;
      if (end == $div.length) end = undefined;
      $div.css("background", "");
      if (end) 
        $div.slice(start, end).css("background", "yellow");   
       else
        $div.slice(start).css("background", "yellow");
      
      $("span").text('$("div").slice(' + start +
                     (end ? ', ' + end : '') +
                     ').css("background", "yellow");');
    }

    $("button").click(colorEm);

]]></code>
                    <css><![CDATA[
  div { width:40px; height:40px; margin:10px; float:left;
        border:2px solid blue; }
  span { color:red; font-weight:bold; }
  button { margin:5px; }
  ]]></css>
  <height>240</height>
                    <html><![CDATA[<p><button>Turn slice yellow</button>
  <span>Click the button!</span></p>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <div></div>
  <div></div>]]></html>
                </example>
                <example>
                    <desc>Selects all paragraphs, then slices the selection to include only the first element.</desc>
                    <code><![CDATA[$("p").slice(0, 1).wrapInner("<b></b>");]]></code>
                </example>
                <example>
                    <desc>Selects all paragraphs, then slices the selection to include only the first and second element.</desc>
                    <code><![CDATA[$("p").slice(0, 2).wrapInner("<b></b>");]]></code>
                </example>
                <example>
                    <desc>Selects all paragraphs, then slices the selection to include only the second element.</desc>
                    <code><![CDATA[$("p").slice(1, 2).wrapInner("<b></b>");]]></code>
                </example>
                <example>
                    <desc>Selects all paragraphs, then slices the selection to include only the second and third element.</desc>
                    <code><![CDATA[$("p").slice(1).wrapInner("<b></b>");]]></code>
                </example>
                <example>
                    <desc>Selects all paragraphs, then slices the selection to include only the third element.</desc>
                    <code><![CDATA[$("p").slice(-1).wrapInner("<b></b>");]]></code>
                </example>
            <category name="Filtering"/>
<category name="Version 1.1.4"/>
</entry>

  <entry type='method' name="jQuery" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="selector" type='selector'>
        <desc>A string containing a selector expression</desc>
      </argument>
      <argument name="context" optional="true" type="Element, jQuery">
          <desc>A DOM Element, Document, or jQuery to use as context</desc>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="element" type="Element">
        <desc>A DOM element to wrap in a jQuery object.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="elementArray" type="Array">
        <desc>An array containing a set of DOM elements to wrap in a jQuery object.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="jQuery object" type="Object">
        <desc>An existing jQuery object to clone.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.4</added>
    </signature>
    <desc>Accepts a string containing a CSS selector which is then used to match a set of elements.</desc>
    <longdesc>
      <p>In the first formulation listed above,  <code>jQuery()</code> &#8212; which can also be written as <code>$()</code> &#8212; searches through the DOM for any elements that match the provided selector and creates a new jQuery object that references these elements:</p>
<pre>$('div.foo');</pre>
<h4 id="selector-context">Selector Context</h4>
<p>By default, selectors perform their searches within the DOM starting at the document root. However, an alternate context can be given for the search by using the optional second parameter to the  <code>$()</code> function. For example, if within a callback function we wish to do a search for an element, we can restrict that search:</p>
<pre>
$('div.foo').click(function() {
  $('span', this).addClass('bar');
});
</pre>
<p>Since we've restricted the span selector to the context of <code>this</code>, only spans within the clicked element will get the additional class.</p>
<p>Internally, selector context is implemented with the <code>.find()</code> method, so  <code>$('span', this)</code> is equivalent to  <code>$(this).find('span')</code>.</p>
<h4 id="using-dom-elements">Using DOM elements</h4>
<p>The second and third formulations of this function allow us to create a jQuery object using a DOM element or elements that we have already found in some other way. A common use of this facility is to call jQuery methods on an element that has been passed to a callback function through the keyword <code>this</code>:</p>
<pre>
$('div.foo').click(function() {
  $(this).slideUp();
});
</pre>
<p>This example causes elements to be hidden with a sliding animation when clicked. Because the handler receives the clicked item in the <code>this</code> keyword as a bare DOM element, the element must be wrapped in a jQuery object before we can call jQuery methods on it.</p>
<p>When XML data is returned from an Ajax call, we can use the  <code>$()</code> function to wrap it in a jQuery object that we can easily work with. Once this is done, we can retrieve individual elements of the XML structure using <code>.find()</code> and other DOM traversal methods.</p>
<h4 id="cloning-jquery-objects">Cloning jQuery Objects</h4>
<p>When a jQuery object is passed as a parameter to the  <code>$()</code> function, a clone of the object is created. This new jQuery object references the same DOM elements as the initial one.</p>
<h4 id="returning-empty-set">Returning an Empty Set</h4>
<p>As of jQuery 1.4,  calling the <code>jQuery()</code> method with <em>no arguments</em> returns an empty jQuery set (with a <code><a href="http://api.jquery.com/length/">.length</a></code> property of 0). In previous versions of jQuery, this would return a set containing the document node.</p>
</longdesc>
    <example>
        <desc>Finds all p elements that are children of a div element.</desc>
        <code><![CDATA[$("div > p").css("border", "1px solid gray");]]></code>
        <html><![CDATA[<p>one</p> <div><p>two</p></div> <p>three</p>]]></html>
        <results><![CDATA[[ <p>two</p> ] ]]></results>
    </example>
    <example>
        <desc>Finds all inputs of type radio within the first form in the document.</desc>
        <code><![CDATA[$("input:radio", document.forms[0]);]]></code>
    </example>
    <example>
        <desc>Finds all div elements within an XML document from an Ajax response.</desc>
        <code><![CDATA[$("div", xml.responseXML);]]></code>
    </example>
    <example>
        <desc>Sets the background color of the page to black.</desc>
        <code><![CDATA[$(document.body).css( "background", "black" );]]></code>
    </example>
    <example>
        <desc>Hides all the input elements within a form.</desc>
        <code><![CDATA[$(myForm.elements).hide()]]></code>
    </example>
  <category name="Core"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
  <entry type='method' name="jQuery" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="html" type="String">
          <desc>A string of HTML to create on the fly. Note that this parses HTML, <strong>not</strong> XML.</desc>
      </argument>
      <argument name="ownerDocument" optional="true" type="document">
          <desc>A document in which the new elements will be created</desc>
      </argument>
    </signature>
    <signature>
      <added>1.4</added>
      <argument name="html" type="String">
          <desc>A string defining a single, standalone, HTML element (e.g. &lt;div/&gt; or &lt;div&gt;&lt;/div&gt;).</desc>
      </argument>
      <argument name="props" type="Object">
          <desc>An map of attributes, events, and methods to call on the newly-created element.</desc>
      </argument>
    </signature>
    <desc>Creates DOM elements on the fly from the provided string of raw HTML.</desc>
    <longdesc>
      <h4 id="creating-new-elements">Creating New Elements</h4>
      <p>If a string is passed as the parameter to  <code>$()</code>, jQuery examines the string to see if it looks like HTML (i.e., it has <code>&lt;tag ... &gt;</code> somewhere within the string). If not, the string is interpreted as a selector expression, as explained above. But if the string appears to be an HTML snippet, jQuery attempts to create new DOM elements as described by the HTML. Then a jQuery object is created and returned that refers to these elements. We can perform any of the usual jQuery methods on this object:</p>
      <pre>$('&lt;p id=&quot;test&quot;&gt;My &lt;em&gt;new&lt;/em&gt; text&lt;/p&gt;').appendTo('body');</pre>
      <p>When the HTML is more complex than a single tag without attributes, as it is in the above example, the actual creation of the elements is handled by the browser's <code>innerHTML</code> mechanism. Specifically, jQuery creates a new &lt;div&gt; element and sets the innerHTML property of the element to the HTML snippet that was passed in. When the parameter has a single tag, such as  <code>$('&lt;img&#160;/&gt;')</code> or  <code>$('&lt;a&gt;&lt;/a&gt;')</code>, jQuery creates the element using the native JavaScript <code>createElement()</code> function.</p>

      <p>When passing in complex HTML, some browsers may not generate a DOM that exactly replicates the HTML source provided. For example, Internet Explorer prior to version 8 will convert all <code>href</code> properties on links to absolute URLs, and Internet Explorer prior to version 9 will not correctly handle HTML5 elements without the addition of a separate <a href="http://code.google.com/p/html5shiv/">compatibility layer</a>.</p>

      <p>To ensure cross-platform compatibility, the snippet must be well-formed. Tags that can contain other elements should be paired with a closing tag:</p>
      <pre>$('&lt;a href=&quot;http://jquery.com&quot;&gt;&lt;/a&gt;');</pre>
      <p>Alternatively, jQuery allows XML-like tag syntax (with or without a space before the slash):</p>
      <pre>$('&lt;a/&gt;');</pre>
      <p>Tags that cannot contain elements may be quick-closed or not:</p>
      <pre>$('&lt;img /&gt;');
$('&lt;input&gt;');
</pre>

<p>As of jQuery 1.4, we can pass a map of properties to the second argument. This argument accepts a superset of properties that can be passed to the <a href="/attr">.attr()</a> method. Furthermore, any <a href="/category/events/">event type</a> can be passed in, and the following jQuery methods can be called: <a href="/val">val</a>, <a href="/css">css</a>, <a href="/html">html</a>, <a href="/text">text</a>, <a href="/data">data</a>, <a href="/width">width</a>, <a href="/height">height</a>, or <a href="/offset">offset</a>. Note that Internet Explorer will not allow you to create an <code>input</code> element and change its type; you must specify the type using <code>'&lt;input type="checkbox" /&gt;'</code> for example.</p>
    </longdesc>
    <example>
        <desc>Creates a div element (and all of its contents) dynamically, and appends it to the body element. Internally, an element is created and its innerHTML property set to the given markup. It is therefore both quite flexible and limited.</desc>
        <code><![CDATA[$("<div><p>Hello</p></div>").appendTo("body")]]></code>
    </example>
    <example>
      <desc>Create some DOM elements.</desc>
      <code><![CDATA[$("<div/>", {
  "class": "test",
  text: "Click me!",
  click: function(){
    $(this).toggleClass("test");
  }
}).appendTo("body");

$("<input>", {
  type: "text",
  val: "Test",
  focusin: function() {
    $(this).addClass("active");
  },
  focusout: function() {
    $(this).removeClass("active");
  }
}).appendTo("form");]]></code>
    </example>
  <category name="Core"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
  <entry type='method' name="jQuery" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="callback" type="Function">
          <desc>The function to execute when the DOM is ready.</desc>
      </argument>
    </signature>
    <desc>Binds a function to be executed when the DOM has finished loading.</desc>
    <longdesc>
      <p>This function behaves just like <code>$(document).ready()</code>, in that it should be used to wrap other <code>$()</code> operations on your page that depend on the DOM being ready. While this function is, technically, chainable, there really isn't much use for chaining against it.</p> 
    </longdesc>
    <example>
      <desc>Executes the function when the DOM is ready to be used.</desc>
      <code><![CDATA[$(function(){
  // Document is ready
});]]></code>
    </example>
    <example>
      <desc>Uses both the shortcut for $(document).ready() and the argument to write failsafe jQuery code using the $ alias, without relying on the global alias.</desc>
      <code><![CDATA[jQuery(function($) {
  // Your code using failsafe $ alias here...
});]]></code>
    </example>
    
  <category name="Core"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>

<entry type='method' name="stop" return="jQuery">
  <desc>Stop the currently-running animation on the matched elements.</desc>
  <signature>
    <added>1.2</added>
    <argument name="clearQueue" type="Boolean" optional="true">
      <desc>A Boolean indicating whether to remove queued animation as well. Defaults to <code>false</code>.</desc>
    </argument>
    <argument name="jumpToEnd" type="Boolean" optional="true">
      <desc>A Boolean indicating whether to complete the current animation immediately. Defaults to <code>false</code>.</desc>
    </argument>
  </signature>
  <longdesc>
  <p>When <code>.stop()</code> is called on an element, the currently-running animation (if any) is immediately stopped. If, for instance, an element is being hidden with <code>.slideUp()</code> when <code>.stop()</code> is called, the element will now still be displayed, but will be a fraction of its previous height. Callback functions are not called.</p>
<p>If more than one animation method is called on the same element, the later animations are placed in the effects queue for the element. These animations will not begin until the first one completes. When <code>.stop()</code> is called, the next animation in the queue begins immediately. If the <code>clearQueue</code> parameter is provided with a value of <code>true</code>, then the rest of the animations in the queue are removed and never run.</p>
<p>If the <code>jumpToEnd</code> property is provided with a value of <code>true</code>, the current animation stops, but the element is immediately given its target values for each CSS property. In our above <code>.slideUp()</code> example, the element would be immediately hidden. The callback function is then immediately called, if provided.</p>
<p>The usefulness of the <code>.stop()</code> method is evident when we need to animate an element on <code>mouseenter</code> and <code>mouseleave</code>:</p>
<pre>&lt;div id="hoverme"&gt;
  Hover me
  &lt;img id="hoverme" src="book.png" alt="" width="100" height="123" /&gt;
&lt;/div&gt;</pre>
<p>We can create a nice fade effect without the common problem of multiple queued animations by adding <code>.stop(true, true)</code> to the chain:</p>
<pre>$('#hoverme-stop-2').hover(function() {
  $(this).find('img').stop(true, true).fadeOut();
}, function() {
  $(this).find('img').stop(true, true).fadeIn();
});</pre>
<blockquote><p>Animations may be stopped globally by setting the property <code>$.fx.off</code> to <code>true</code>. When this is done, all animation methods will immediately set elements to their final state when called, rather than displaying an effect.</p></blockquote>
  </longdesc>
  <example>
      <desc>Click the Go button once to start the animation, then click the STOP button to stop it where it's currently positioned.  Another option is to click several buttons to queue them up and see that stop just kills the currently playing one.</desc>
      <code><![CDATA[
// Start animation
$("#go").click(function(){
$(".block").animate({left: '+=100px'}, 2000);
});

// Stop animation when button is clicked
$("#stop").click(function(){
$(".block").stop();
});

// Start animation in the opposite direction
$("#back").click(function(){
$(".block").animate({left: '-=100px'}, 2000);
});

]]></code>
      <html><![CDATA[<button id="go">Go</button> 
<button id="stop">STOP!</button>
<button id="back">Back</button>
<div class="block"></div>]]></html>
      <css><![CDATA[div { 
position: absolute; 
background-color: #abc;
left: 0px;
top:30px;
width: 60px; 
height: 60px;
margin: 5px; 
}
]]></css>
  </example>
<category name="Custom"/>
<category name="Version 1.2"/>
</entry>

            <entry type='method' name="end" return="jQuery">
              <signature>
                <added>1.0</added>
              </signature>
              <desc>End the most recent filtering operation in the current chain and return the set of matched elements to its previous state.</desc>
              <longdesc><p>Most of jQuery's <a href="http://api.jquery.com/category/traversing">DOM traversal</a> methods operate on a jQuery object instance and produce a new one, matching a different set of DOM elements. When this happens, it is as if the new set of elements is pushed onto a stack that is maintained inside the object. Each successive filtering method pushes a new element set onto the stack. If we need an older element set, we can use <code>end()</code> to pop the sets back off of the stack.</p>
<p>Suppose we have a couple short lists on a page:</p>
<pre>
&lt;ul class="first"&gt;
   &lt;li class="foo"&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="bar"&gt;list item 3&lt;/li&gt;
&lt;/ul&gt;
&lt;ul class="second"&gt;
   &lt;li class="foo"&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="bar"&gt;list item 3&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>The <code>end()</code> method is useful primarily when exploiting jQuery's chaining properties. When not using chaining, we can usually just call up a previous object by variable name, so we don't need to manipulate the stack. With <code>end()</code>, though, we can string all the method calls together:</p>
<pre>
$('ul.first').find('.foo').css('background-color', 'red')
  <code>.end()</code>.find('.bar').css('background-color', 'green');
</pre>
<p>This chain searches for items with the class <code>foo</code> within the first list only and turns their backgrounds red. Then <code>end()</code> returns the object to its state before the call to <code>find()</code>, so the second <code>find()</code> looks for '.bar' inside <code>&lt;ul class="first"&gt;</code>, not just inside that list's <code>&lt;li class="foo"&gt;</code>, and turns the matching elements' backgrounds green. The net result is that items 1 and 3 of the first list have a colored background, and none of the items from the second list do.</p>
<p>A long jQuery chain can be visualized as a structured code block, with filtering methods providing the openings of nested blocks and <code>end()</code> methods closing them:</p>
<pre>
$('ul.first').find('.foo')
  .css('background-color', 'red')
.end().find('.bar')
  .css('background-color', 'green')
.end();
</pre>
<p>The last <code>end()</code> is unnecessary, as we are discarding the jQuery object immediately thereafter. However, when the code is written in this form, the <code>end()</code> provides visual symmetry and closure—making the program, at least to the eyes of some developers, more readable.</p></longdesc>
                <example>
                    <desc>Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.</desc>
                    <code><![CDATA[

    jQuery.fn.showTags = function (n) {
      var tags = this.map(function () { 
                              return this.tagName; 
                            })
                        .get().join(", ");
      $("b:eq(" + n + ")").text(tags);
      return this;
    };

    $("p").showTags(0)
          .find("span")
          .showTags(1)
          .css("background", "yellow")
          .end()
          .showTags(2)
          .css("font-style", "italic");

]]></code>
                    <css><![CDATA[
  p, div { margin:1px; padding:1px; font-weight:bold; 
           font-size:16px; }
  div { color:blue; }
  b { color:red; }
  ]]></css>
                    <html><![CDATA[<p>
    Hi there <span>how</span> are you <span>doing</span>?
  </p>

  <p>
    This <span>span</span> is one of 
    several <span>spans</span> in this
    <span>sentence</span>.
  </p>

  <div>
    Tags in jQuery object initially: <b></b>
  </div>
  <div>
    Tags in jQuery object after find: <b></b>

  </div>
  <div>
    Tags in jQuery object after end: <b></b>
  </div>]]></html>
                </example>
                <example>
                    <desc>Selects all paragraphs, finds span elements inside these, and reverts the selection back to the paragraphs.</desc>
                    <code><![CDATA[$("p").find("span").end().css("border", "2px red solid");]]></code>
                    <css><![CDATA[p { margin:10px; padding:10px; }]]></css>
                    <html><![CDATA[<p><span>Hello</span>, how are you?</p>]]></html>
                </example>
            <category name="Miscellaneous Traversing"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="andSelf" return="jQuery">
              <signature>
                <added>1.2</added>
              </signature>
              <desc>Add the previous set of elements on the stack to the current set.</desc>
              <longdesc><p>As described in the discussion for <code>.end()</code> above, jQuery objects maintain an internal stack that keeps track of changes to the matched set of elements. When one of the DOM traversal methods is called, the new set of elements is pushed onto the stack. If the previous set of elements is desired as well, <code>.andSelf()</code> can help.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find the elements which come after it:</p>
<pre>$('li.third-item').nextAll().andSelf()
  .css('background-color', 'red');
</pre>
<p>The result of this call is a red background behind items 3, 4 and 5. First, the initial selector locates item 3, initializing the stack with the set containing just this item. The call to <code>.nextAll()</code> then pushes the set of items 4 and 5 onto the stack. Finally, the <code>.andSelf()</code> invocation merges these two sets together, creating a jQuery object that points to all three items in document order: <code>{[&lt;li.third-item&gt;,&lt;li&gt;,&lt;li&gt; ]}</code>.</p></longdesc>
                <example>
                    <desc>Find all divs, and all the paragraphs inside of them, and give them both classnames.  Notice the div doesn't have the yellow background color since it didn't use andSelf.</desc>
                    <code><![CDATA[
    $("div").find("p").andSelf().addClass("border");
    $("div").find("p").addClass("background");

]]></code>
                    <css><![CDATA[
  p, div { margin:5px; padding:5px; }
  .border { border: 2px solid red; }
  .background { background:yellow; }
  ]]></css>
                    <html><![CDATA[<div>
    <p>First Paragraph</p>
    <p>Second Paragraph</p>
  </div>]]></html>
                </example>
            <category name="Miscellaneous Traversing"/>
<category name="Version 1.2"/>
</entry>
            <entry type='method' name="siblings" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the siblings of each element in the set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.siblings()</code> method allows us to search through the siblings of these elements in the DOM tree and construct a new jQuery object from the matching elements.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find its siblings:</p>
<pre>$('li.third-item').siblings().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind items 1, 2, 4, and 5. Since we do not supply a selector expression, all of the siblings are part of the object. If we had supplied one, only the matching items among these four would be included.</p>
<p>The original element is not included among the siblings, which is important to remember when we wish to find all elements at a particular level of the DOM tree.</p></longdesc>
                <example>
                    <desc>Find the unique siblings of all yellow li elements in the 3 lists (including other yellow li elements if appropriate).</desc>
                    <code><![CDATA[

    var len = $(".hilite").siblings()
                          .css("color", "red")
                          .length;
    $("b").text(len);
]]></code>
                    <css><![CDATA[
  ul { float:left; margin:5px; font-size:16px; font-weight:bold; }
  p { color:blue; margin:10px 20px; font-size:16px; padding:5px; 
      font-weight:bolder; }
  .hilite { background:yellow; }
]]></css>
                    <html><![CDATA[<ul>
    <li>One</li>

    <li>Two</li>
    <li class="hilite">Three</li>
    <li>Four</li>
  </ul>

  <ul>
    <li>Five</li>
    <li>Six</li>
    <li>Seven</li>

  </ul>
  <ul>
    <li>Eight</li>
    <li class="hilite">Nine</li>

    <li>Ten</li>
    <li class="hilite">Eleven</li>
  </ul>
  <p>Unique siblings: <b></b></p>]]></html>
                </example>
                <example>
                    <desc>Find all siblings with a class "selected" of each div.</desc>
                    <code><![CDATA[$("p").siblings(".selected").css("background", "yellow");]]></code>
                    <html><![CDATA[<div><span>Hello</span></div>

  <p class="selected">Hello Again</p>
  <p>And Again</p>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="animate" return="jQuery">
  <desc>Perform a custom animation of a set of CSS properties.</desc>
  <signature>
    <added>1.0</added>
    <argument name="properties" type="Map">
      <desc>A map of CSS properties that the animation will move toward.</desc>
    </argument>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Function" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.0</added>
    <argument name="properties" type="Map">
      <desc>A map of CSS properties that the animation will move toward.</desc>
    </argument>
    <argument name="options" type="Map">
      <desc>A map of additional options to pass to the method. Supported keys:
        <ul>
        <li><code>duration</code>: A string or number determining how long the animation will run.</li>
        <li><code>easing</code>: A string indicating which easing function to use for the transition.</li>
        <li><code>complete</code>: A function to call once the animation is complete.</li>
        <li><code>step</code>: A function to be called after each step of the animation.</li>
        <li><code>queue</code>: A Boolean indicating whether to place the animation in the effects queue. If <code>false</code>, the animation will begin immediately.</li>
        <li><code>specialEasing</code>: A map of one or more of the CSS properties defined by the properties argument and their corresponding easing functions (added 1.4).</li>
        </ul>
        </desc>
    </argument>
  </signature>
  
  <longdesc>
  <p>The <code>.animate()</code> method allows us to create animation effects on any numeric CSS property. The only required parameter is a map of CSS properties. This map is similar to the one that can be sent to the <code>.css()</code> method, except that the range of properties is more restrictive.</p>
<p>All animated properties should be a <em>single numeric value</em> (except as noted below); properties that are non-numeric cannot be animated using basic jQuery functionality. (For example, <code>width</code>, <code>height</code>, or <code>left</code> can be animated but <code>background-color</code> cannot be.) Property values are treated as a number of pixels unless otherwise specified. The units <code>em</code> and <code>%</code> can be specified where applicable.</p>
<p>Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: <code>$(elem).css('marginTop')</code> and <code>$(elem).css('marginRight')</code>, and so on.</p>
<p>In addition to numeric values, each property can take the strings <code>'show'</code>, <code>'hide'</code>, and <code>'toggle'</code>. These shortcuts allow for custom hiding and showing animations that take into account the display type of the element.</p>
<p>Animated properties can also be relative. If a value is supplied with a leading <code>+=</code> or <code>-=</code> sequence of characters, then the target value is computed by adding or subtracting the given number from the current value of the property.</p>
<h4 id="duration">Duration</h4>
<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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
<h4 id="callback">Callback Function</h4>
<p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
<p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" 
  style="position: relative; left: 10px;" /&gt;</pre>
<p>We can animate the opacity, left offset, and height of the image simultaneously:</p>
<pre>$('#clickme').click(function() {
  $('#book').animate({
    opacity: 0.25,
    left: '+=50',
    height: 'toggle'
  }, 5000, function() {
    // Animation complete.
  });
});
</pre>
<p class="image">
  <img src="/images/animate-1.jpg" alt="" />
</p>
<p>Note that we have specified <code>toggle</code> as the target value of the <code>height</code> property. Since the image was visible before, the animation shrinks the height to 0 to hide it. A second click then reverses this transition:
</p>
<p class="image"> 
<img src="/images/animate-2.jpg" alt="" /> 
</p>

<p>The <code>opacity</code> of the image is already at its target value, so this property is not animated by the second click. Since we specified the target value for <code>left</code> as a relative value, the image moves even farther to the right during this second animation.</p>
<p>The <code>position</code> attribute of the element must not be <code>static</code> if we wish to animate the <code>left</code> property as we do in the example.</p>
<blockquote><p>The <a href="http://jqueryui.com">jQuery UI</a> project extends the <code>.animate()</code> method by allowing some non-numeric styles such as colors to be animated. The project also includes mechanisms for specifying animations through CSS classes rather than individual attributes.</p></blockquote>
<h4 id="easing">Easing</h4>
<p>The remaining parameter of <code>.animate()</code> is a string naming an easing function to use. An easing function specifies the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com/">jQuery UI suite</a>.</p>
<h4 id="per-property-easing">Per-property Easing</h4>
<p>As of jQuery version 1.4, we can set per-property easing functions within a single <code>.animate()</code> call. In the first version of <code>.animate()</code>, each property can take an array as its value: The first member of the array is the CSS property and the second member is an easing function.  If a per-property easing function is not defined for a particular property, it uses the value of the <code>.animate()</code> method's optional easing argument. If the easing argument is not defined, the default <code>swing</code> function is used.</p>
<p>We can, for example, simultaneously animate the width and height with the <code>swing</code> easing function and the opacity with the <code>linear</code> easing function:</p>
<pre>$('#clickme').click(function() {
  $('#book').animate({
    width: ['toggle', 'swing'],
    height: ['toggle', 'swing'],
    opacity: 'toggle'
  }, 5000, 'linear', function() {
      $(this).after('&lt;div&gt;Animation complete.&lt;/div&gt;');
  });
});</pre>
<p>In the second version of <code>.animate()</code>, the options map can include the <code>specialEasing</code> property, which is itself a map of CSS properties and their corresponding easing functions.  We can simultaneously animate the width using the <code>linear</code> easing function and the height using the <code>easeOutBounce</code> easing function.</p>
<pre>$('#clickme').click(function() {
  $('#book').animate({
    width: 'toggle',
    height: 'toggle'
  }, {
    duration: 5000, 
    specialEasing: {
      width: 'linear',
      height: 'easeOutBounce'
    }, 
    complete: function() {
      $(this).after('&lt;div&gt;Animation complete.&lt;/div&gt;');
    }
  });
});</pre>
<p>As previously noted, a plug-in is required for the <code>easeOutBounce</code> function.</p>

</longdesc>

<example>
    <desc>Click the button to animate the div with a number of different properties.</desc>
    <code><![CDATA[

/* Using multiple unit types within one animation. */

$("#go").click(function(){
  $("#block").animate({ 
    width: "70%",
    opacity: 0.4,
    marginLeft: "0.6in",
    fontSize: "3em", 
    borderWidth: "10px"
  }, 1500 );
});
]]></code>
                <html><![CDATA[<button id="go">&raquo; Run</button>

<div id="block">Hello!</div>]]></html>
                <css><![CDATA[
div { 
background-color:#bca; 
width:100px; 
border:1px solid green;
}
]]></css>
            </example>
            <example>
                <desc>Shows a div animate with a relative move.  Click several times on the buttons to see the relative animations queued up.</desc>
                <code><![CDATA[
$("#right").click(function(){
  $(".block").animate({"left": "+=50px"}, "slow");
});

$("#left").click(function(){
  $(".block").animate({"left": "-=50px"}, "slow");
});

]]></code>
                <html><![CDATA[<button id="left">&laquo;</button> <button id="right">&raquo;</button>
<div class="block"></div>
]]></html>
                <css><![CDATA[
div { 
position:absolute; 
background-color:#abc; 
left:50px;
width:90px; 
height:90px;
margin:5px; 
}
]]></css>
</example>
            <example>
                <desc>Animates all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.</desc>
                <code><![CDATA[$("p").animate({
  "height": "toggle", "opacity": "toggle"

}, "slow");]]></code>
            </example>
            <example>
                <desc>Animates all paragraph to a left style of 50 and opacity of 1 (opaque, visible), completing the animation within 500 milliseconds.</desc>
                <code><![CDATA[$("p").animate({
  "left": "50", "opacity": 1
}, 500);
]]></code>
            </example>
            <example>
                <desc>An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that provides this easing function.  Note, this code will do nothing unless the paragraph element is hidden.</desc>
                <code><![CDATA[$("p").animate({
  "opacity": "show"

}, "slow", "easein");]]></code>
            </example>
            <example>
                <desc>The first button shows how an unqueued animation works.  It expands the div out to 90% width <strong>while</strong> the font-size is increasing. Once the font-size change is complete, the border animation will begin.

The second button starts a traditional chained animation, where each animation will start once the previous animation on the element has completed.</desc>
                <code><![CDATA[

$("#go1").click(function(){
  $("#block1").animate( { width:"90%" }, { queue:false, duration:3000 } )
     .animate( { fontSize:"24px" }, 1500 )
     .animate( { borderRightWidth:"15px" }, 1500);
});

$("#go2").click(function(){
  $("#block2").animate( { width:"90%"}, 1000 )
     .animate( { fontSize:"24px" } , 1000 )
     .animate( { borderLeftWidth:"15px" }, 1000);
});

$("#go3").click(function(){
  $("#go1").add("#go2").click();
});

$("#go4").click(function(){
  $("div").css({width:"", fontSize:"", borderWidth:""});
});

]]></code>
                  <html><![CDATA[<button id="go1">&raquo; Animate Block1</button>
<button id="go2">&raquo; Animate Block2</button>
<button id="go3">&raquo; Animate Both</button>

<button id="go4">&raquo; Reset</button>
<div id="block1">Block1</div>
<div id="block2">Block2</div>]]></html>
                  <css><![CDATA[div { 
  background-color:#bca; 
  width:200px;
  height:1.1em;
  text-align:center;
  border:2px solid green;
  margin:3px;
  font-size:14px;
}
button {
  font-size:14px;
}
]]></css>
  </example>
  <example>
      <desc>Animates all paragraphs to toggle both height and opacity, completing the animation within 600 milliseconds.</desc>
      <code><![CDATA[$("p").animate({
"height": "toggle", "opacity": "toggle"

}, { duration: "slow" });]]></code>
  </example>
  <example>
      <desc>Animates all paragraph to a left style of 50 and opacity of 1 (opaque, visible), completing the animation within 500 milliseconds.  It also will do it <em>outside</em> the queue, meaning it will automatically start without waiting for its turn.</desc>
      <code><![CDATA[$("p").animate({
left: "50px", opacity: 1
}, { duration: 500, queue: false });]]></code>
  </example>
  <example>
      <desc>An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that provides this easing function.</desc>
      <code><![CDATA[$("p").animate({
"opacity": "show"

}, { "duration": "slow", "easing": "easein" });]]></code>
  </example>
  <example>
      <desc>An example of using a callback function.  The first argument is an array of CSS properties, the second specifies that the animation should take 1000 milliseconds to complete, the third states the easing type, and the fourth argument is an anonymous callback function. </desc>
      <code><![CDATA[$("p").animate({
height:200, width:400, opacity: .5
}, 1000, "linear", function(){alert("all done");} );

]]></code>
  </example>
<category name="Custom"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="prevAll" return="jQuery">
              <signature>
                <added>1.2</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get all preceding siblings of each element in the set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.prevAll()</code> method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find the elements which come before it:</p>
<pre>$('li.third-item').prevAll().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind items 1 and 2. Since we do not supply a selector expression, these preceding elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.</p></longdesc>
                <example>
                    <desc>Locate all the divs preceding the last div and give them a class.</desc>
                    <code><![CDATA[$("div:last").prevAll().addClass("before");]]></code>
                    <css><![CDATA[

  div { width:70px; height:70px; background:#abc; 
        border:2px solid black; margin:10px; float:left; }
  div.before { border-color: red; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div></div>
  <div></div>
  <div></div>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.2"/>
</entry>
            <entry type='method' name="prev" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the immediately preceding sibling of each element in the set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.prev()</code> method allows us to search through the predecessors of these elements in the DOM tree and construct a new jQuery object from the matching elements.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find the element which comes just before it:</p>
<pre>$('li.third-item').prev().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind item 2. Since we do not supply a selector expression, this preceding element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.</p></longdesc>
                <example>
                    <desc>Find the very previous sibling of each div.</desc>
                    <code><![CDATA[
    var $curr = $("#start");
    $curr.css("background", "#f99");
    $("button").click(function () {
      $curr = $curr.prev();
      $("div").css("background", "");
      $curr.css("background", "#f99");
    });

]]></code>
                    <css><![CDATA[
  div { width:40px; height:40px; margin:10px;
        float:left; border:2px blue solid; 
        padding:2px; }
  span { font-size:14px; }
  p { clear:left; margin:10px; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div></div>
  <div><span>has child</span></div>

  <div></div>
  <div></div>
  <div></div>
  <div id="start"></div>

  <div></div>
  <p><button>Go to Prev</button></p>]]></html>
                </example>
                <example>
                    <desc>For each paragraph, find the very previous sibling that has a class "selected".</desc>
                    <code><![CDATA[$("p").prev(".selected").css("background", "yellow");]]></code>
                    <html><![CDATA[<div><span>Hello</span></div>

  <p class="selected">Hello Again</p>
  <p>And Again</p>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="fadeTo" return="jQuery">
  <desc>Adjust the opacity of the matched elements.</desc>
  <signature>
    <added>1.0</added>
    <argument name="duration" type="String,Number">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="opacity" type="Number">
      <desc>A number between 0 and 1 denoting the target opacity.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="opacity" type="Number">
      <desc>A number between 0 and 1 denoting the target opacity.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
<longdesc>
  <p>The <code>.fadeTo()</code> method animates the opacity of the matched elements.</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 <code>200</code> and <code>600</code> milliseconds, respectively. If any other string is supplied, the default duration of  <code>400</code> milliseconds is used. Unlike the other effect methods, <code>.fadeTo()</code> requires that <code>duration</code> be explicitly specified.</p>
  <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
  <p>We can animate any element, such as a simple image:</p>
  <pre>&lt;div id="clickme"&gt;
    Click here
  &lt;/div&gt;
  &lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;
  With the element initially shown, we can dim it slowly:
  $('#clickme').click(function() {
    $('#book').fadeTo('slow', 0.5, function() {
      // Animation complete.
    });
  });
  </pre>
  <p class="image four-across"> 
    <img src="/images/0042_06_41.png" alt="" />
    <img src="/images/0042_06_42.png" alt="" />
    <img src="/images/0042_06_43.png" alt="" />
    <img src="/images/0042_06_44.png" alt="" />
  </p>
  <p>With <code>duration</code> set to <code>0</code>, this method just changes the <code>opacity</code> CSS property, so <code>.fadeTo(0, opacity)</code> is the same as <code>.css('opacity', opacity)</code>.</p>
</longdesc>
   <example>
        <desc>Animates first paragraph to fade to an opacity of 0.33 (33%, about one third visible), completing the animation within 600 milliseconds.</desc>
        <code><![CDATA[
$("p:first").click(function () {
$(this).fadeTo("slow", 0.33);
});
]]></code>
        <html><![CDATA[<p>
Click this paragraph to see it fade.
</p>

<p>
Compare to this one that won't fade.
</p>]]></html>
    </example>
    <example>
        <desc>Fade div to a random opacity on each click, completing the animation within 200 milliseconds.</desc>
        <code><![CDATA[
$("div").click(function () {
$(this).fadeTo("fast", Math.random());
});
]]></code>
        <css><![CDATA[
p { width:80px; margin:0; padding:5px; }
div { width:40px; height:40px; position:absolute; }
div#one { top:0; left:0; background:#f00; }
div#two { top:20px; left:20px; background:#0f0; }
div#three { top:40px; left:40px; background:#00f; }
]]></css>
        <html><![CDATA[<p>And this is the library that John built...</p>

<div id="one"></div>
<div id="two"></div>
<div id="three"></div>]]></html>
    </example>
    <example>
        <desc>Find the right answer!  The fade will take 250 milliseconds and change various styles when it completes.</desc>
        <code><![CDATA[
var getPos = function (n) {
return (Math.floor(n) * 90) + "px";
};
$("p").each(function (n) {
var r = Math.floor(Math.random() * 3);
var tmp = $(this).text();
$(this).text($("p:eq(" + r + ")").text());
$("p:eq(" + r + ")").text(tmp);
$(this).css("left", getPos(n));
});
$("div").each(function (n) {
      $(this).css("left", getPos(n));
    })
.css("cursor", "pointer")
.click(function () {
      $(this).fadeTo(250, 0.25, function () {
            $(this).css("cursor", "")
                   .prev().css({"font-weight": "bolder",
                                "font-style": "italic"});
          });
    });

]]></code>
        <css><![CDATA[
div, p { width:80px; height:40px; top:0; margin:0; 
position:absolute; padding-top:8px; }
p { background:#fcc; text-align:center; }
div { background:blue; }
]]></css>
        <html><![CDATA[<p>Wrong</p>
<div></div>
<p>Wrong</p>
<div></div>

<p>Right!</p>
<div></div>]]></html>
    </example>
<category name="Fading"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="fadeOut" return="jQuery">
  <desc>Hide the matched elements by fading them to transparent.</desc>
  <signature>
    <added>1.0</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <longdesc>
    <p>The <code>.fadeOut()</code> method animates the opacity of the matched elements. Once the opacity reaches 0, the <code>display</code> style property is set to <code>none</code>, so the element no longer affects the layout of the page.</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 <code>200</code> and <code>600</code> milliseconds, respectively. If any other string is supplied, or if the <code>duration</code> parameter is omitted, the default duration of  <code>400</code> milliseconds is used.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
    <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
    <p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;</pre>
<p>With the element initially shown, we can hide it slowly:</p>
<pre>$('#clickme').click(function() {
  $('#book').fadeOut('slow', function() {
    // Animation complete.
  });
});</pre>
    <p class="image four-across">
      <img src="/images/0042_06_37.png" alt="" />
      <img src="/images/0042_06_38.png" alt="" />
      <img src="/images/0042_06_39.png" alt="" />
      <img src="/images/0042_06_40.png" alt="" />
    </p>
  </longdesc>
      <example>
          <desc>Animates all paragraphs to fade out, completing the animation within 600 milliseconds.</desc>
          <code><![CDATA[
  $("p").click(function () {
  $("p").fadeOut("slow");
  });
  ]]></code>
          <css><![CDATA[
  p { font-size:150%; cursor:pointer; }
  ]]></css>
          <html><![CDATA[<p>
  If you click on this paragraph
  you'll see it just fade away.
  </p>]]></html>
      </example>
      <example>
          <desc>Fades out spans in one section that you click on.</desc>
          <code><![CDATA[

  $("span").click(function () {
  $(this).fadeOut(1000, function () {
  $("div").text("'" + $(this).text() + "' has faded!");
  $(this).remove();
  });
  });
  $("span").hover(function () {
  $(this).addClass("hilite");
  }, function () {
  $(this).removeClass("hilite");
  });

  ]]></code>
          <css><![CDATA[
  span { cursor:pointer; }
  span.hilite { background:yellow; }
  div { display:inline; color:red; }
  ]]></css>
          <html><![CDATA[<h3>Find the modifiers - <div></div></h3>
  <p>
  If you <span>really</span> want to go outside
  <span>in the cold</span> then make sure to wear
  your <span>warm</span> jacket given to you by
  your <span>favorite</span> teacher.
  </p>]]></html>
      </example>
<example>
<desc>Fades out two divs, one with a "linear" easing and one with the default, "swing," easing.</desc>
<code><![CDATA[
$("#btn1").click(function() {
  function complete() {
    $("<div/>").text(this.id).appendTo("#log");
  }
  
  $("#box1").fadeOut(1600, "linear", complete);
  $("#box2").fadeOut(1600, complete);
});

$("#btn2").click(function() {
  $("div").show();
  $("#log").empty();
});

]]></code>
 <css><![CDATA[
.box,
button { float:left; margin:5px 10px 5px 0; }
.box { height:80px; width:80px; background:#090; }
#log { clear:left; }

]]></css>
 <html><![CDATA[
<button id="btn1">fade out</button>
<button id="btn2">show</button>

<div id="log"></div>

<div id="box1" class="box">linear</div>
<div id="box2" class="box">swing</div>
]]></html>
</example>
<category name="Fading"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="parents" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="selector" optional="true" type="Selector">
        <desc>A string containing a selector expression to match elements against.</desc>
    </argument>
  </signature>
  <desc>Get the ancestors of each element in the current set of matched elements, optionally filtered by a selector.</desc>
  <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.parents()</code> method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object from the matching elements ordered from immediate parent on up; the elements are returned in order from the closest parent to the outer ones. The <code>.parents()</code> and <code><a href="http://api.jquery.com/parent/">.parent()</a></code> methods are similar, except that the latter only travels a single level up the DOM tree.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a basic nested list on it:</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:</p>
<pre>$('li.item-a').parents().css('background-color', 'red');</pre>
<p>The result of this call is a red background for the level-2 list, item II, and the level-1 list (and on up the DOM tree all the way to the <code>&lt;html&gt;</code> element). Since we do not supply a selector expression, all of the ancestors are part of the returned jQuery object. If we had supplied one, only the matching items among these would be included.</p></longdesc>
  <example>
      <desc>Find all parent elements of each b.</desc>
      <code><![CDATA[
var parentEls = $("b").parents()
            .map(function () { 
                  return this.tagName; 
                })
            .get().join(", ");
$("b").append("<strong>" + parentEls + "</strong>");

]]></code>
  <css><![CDATA[
  b, span, p, html body {
    padding: .5em;
    border: 1px solid;
  }
  b { color:blue; }
  strong { color:red; }
  ]]></css>
  <html><![CDATA[<div>
    <p>
      <span>
        <b>My parents are: </b>
      </span>

    </p>
  </div>]]></html>
</example>
<example>
    <desc>Click to find all unique div parent elements of each span.</desc>
    <code><![CDATA[
function showParents() {
  $("div").css("border-color", "white");
  var len = $("span.selected")
                   .parents("div")
                   .css("border", "2px red solid")
                   .length;
  $("b").text("Unique div parents: " + len);
}
$("span").click(function () {
  $(this).toggleClass("selected");
  showParents();
});]]></code>
<css><![CDATA[

  p, div, span {margin:2px; padding:1px; }
  div { border:2px white solid; }
  span { cursor:pointer; font-size:12px; }
  .selected { color:blue; }
  b { color:red; display:block; font-size:14px; }
  ]]></css>
  <html><![CDATA[<p>
    <div>
      <div><span>Hello</span></div>
      <span>Hello Again</span>

    </div>
    <div>
      <span>And Hello Again</span>
    </div>
  </p>

  <b>Click Hellos to toggle their parents.</b>]]></html>
    </example>
<category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="fadeIn" return="jQuery">
  <desc>Display the matched elements by fading them to opaque.</desc>
  <signature>
    <added>1.0</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <longdesc>
    <p>The <code>.fadeIn()</code> method animates the opacity of the matched elements.</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 <code>200</code> and <code>600</code> milliseconds, respectively. If any other string is supplied, or if the <code>duration</code> parameter is omitted, the default duration of  <code>400</code> milliseconds is used.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
    <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
    <p>We can animate any element, such as a simple image:</p>
    <pre>&lt;div id="clickme"&gt;
      Click here
    &lt;/div&gt;
    &lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;
    With the element initially hidden, we can show it slowly:
    $('#clickme').click(function() {
      $('#book').fadeIn('slow', function() {
        // Animation complete
      });
    });</pre>
    <p class="image four-across">
      <img src="/images/0042_06_33.png" alt="" />
      <img src="/images/0042_06_34.png" alt="" />
      <img src="/images/0042_06_35.png" alt="" />
      <img src="/images/0042_06_36.png" alt="" />
    </p>
  </longdesc>
  <example>
    <desc>Animates hidden divs to fade in one by one, completing each animation within 600 milliseconds.</desc>
    <code><![CDATA[
      $(document.body).click(function () {
        $("div:hidden:first").fadeIn("slow");
      });
    ]]></code>
    <css><![CDATA[
    span { color:red; cursor:pointer; }
    div { margin:3px; width:80px; display:none;
      height:80px; float:left; }
      div#one { background:#f00; }
      div#two { background:#0f0; }
      div#three { background:#00f; }
    ]]></css>
    <html><![CDATA[<span>Click here...</span>

    <div id="one"></div>
    <div id="two"></div>
    <div id="three"></div>]]></html>
    </example>
    <example>
      <desc>Fades a red block in over the text. Once the animation is done, it quickly fades in more text on top.</desc>
      <code><![CDATA[
        $("a").click(function () {
          $("div").fadeIn(3000, function () {
            $("span").fadeIn(100);
          });
          return false;
        }); 

      ]]></code>
      <css><![CDATA[
      p { position:relative; width:400px; height:90px; }
      div { position:absolute; width:400px; height:65px; 
        font-size:36px; text-align:center; 
        color:yellow; background:red;
        padding-top:25px; 
        top:0; left:0; display:none; }
        span { display:none; }
      ]]></css>
      <html><![CDATA[<p>
        Let it be known that the party of the first part
        and the party of the second part are henceforth
        and hereto directed to assess the allegations
        for factual correctness... (<a href="#">click!</a>)
        <div><span>CENSORED!</span></div>

      </p>]]></html>
      </example>
<category name="Fading"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
            <entry type='method' name="parent" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the parent of each element in the current set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.parent()</code> method allows us to search through the parents of these elements in the DOM tree and construct a new jQuery object from the matching elements. The <code>.parents()</code> and <code>.parent()</code> methods are similar, except that the latter only travels a single level up the DOM tree.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a basic nested list on it:</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 parents:</p>
<pre>$('li.item-a').parent().css('background-color', 'red');</pre>
<p>The result of this call is a red background for the level-2 list. Since we do not supply a selector expression, the parent element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.</p></longdesc>
                <example>
                    <desc>Shows the parent of each element as (parent > child).  Check the View Source to see the raw html.</desc>
                    <code><![CDATA[

    $("*", document.body).each(function () {
      var parentTag = $(this).parent().get(0).tagName;
      $(this).prepend(document.createTextNode(parentTag + " > "));
    });
]]></code>
                    <css><![CDATA[
  div,p { margin:10px; }
  ]]></css>
                    <html><![CDATA[<div>div, 
    <span>span, </span>
    <b>b </b>

  </div>
  <p>p, 
    <span>span, 
      <em>em </em>
    </span>
  </p>

  <div>div, 
    <strong>strong, 
      <span>span, </span>
      <em>em, 
        <b>b, </b>
      </em>

    </strong>
    <b>b </b>
  </div>]]></html>
                </example>
                <example>
                    <desc>Find the parent element of each paragraph with a class "selected".</desc>
                    <code><![CDATA[$("p").parent(".selected").css("background", "yellow");]]></code>
                    <html><![CDATA[<div><p>Hello</p></div>

  <div class="selected"><p>Hello Again</p></div>
]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="offsetParent" return="jQuery">
              <signature>
                <added>1.2.6</added>
              </signature>
              <desc>Get the closest ancestor element that is positioned.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.offsetParent()</code> method allows us to search through the ancestors of these elements in the DOM tree and construct a new jQuery object wrapped around the closest positioned ancestor. An element is said to be positioned if it has a CSS position attribute of <code>relative</code>, <code>absolute</code>, or <code>fixed</code>. This information is useful for calculating offsets for performing animations and placing objects on the page.</p>
<p>Consider a page with a basic nested list on it, with a positioned element:</p>
<pre>
&lt;ul class="level-1"&gt;
  &lt;li class="item-i"&gt;I&lt;/li&gt;
  &lt;li class="item-ii" style="position: relative;"&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 positioned ancestor:</p>
<pre>$('li.item-a').offsetParent().css('background-color', 'red');</pre>
<p>This will change the color of list item II, which is positioned.</p>
</longdesc>
<example>
  <desc>Find the offsetParent of item "A."</desc>
  <height>250</height>
  <code>$('li.item-a').offsetParent().css('background-color', 'red');</code>
  <html><![CDATA[
    <ul class="level-1">
      <li class="item-i">I</li>
      <li class="item-ii" style="position: relative;">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="Offset"/>
<category name="Tree Traversal"/>
</entry>
<entry type='method' name="slideToggle" return="jQuery">
  <desc>Display or hide the matched elements with a sliding motion.</desc>
  <signature>
    <added>1.0</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <longdesc>
  <p>The <code>.slideToggle()</code> method animates the height of the matched elements. This causes lower parts of the page to slide up or down, appearing to reveal or conceal the items. If the element is initially displayed, it will be hidden; if hidden, it will be shown. The <code>display</code> property is saved and restored as needed. If an element has a <code>display</code> value of <code>inline</code>, then is hidden and shown, it will once again be displayed <code>inline</code>. When the height reaches 0 after a hiding animation, the <code>display</code> style property is set to <code>none</code> to ensure that the element no longer affects the layout of the page.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
  <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
  <p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;</pre>
  <p>We will cause <code>.slideToggle()</code> to be called when another element is clicked:</p>
<pre>$('#clickme').click(function() {
  $('#book').slideToggle('slow', function() {
    // Animation complete.
  });
});
</pre>
  <p>With the element initially shown, we can hide it slowly with the first click:</p>
  <p class="image four-across"> 
    <img src="/images/0042_06_25.png" alt="" />
    <img src="/images/0042_06_26.png" alt="" />
    <img src="/images/0042_06_27.png" alt="" />
    <img src="/images/0042_06_28.png" alt="" />
  </p>
  <p>A second click will show the element once again:</p>

  <p class="image four-across"> 
    <img src="/images/0042_06_29.png" alt="" />
    <img src="/images/0042_06_30.png" alt="" />
    <img src="/images/0042_06_31.png" alt="" />
    <img src="/images/0042_06_32.png" alt="" />
  </p>
  </longdesc>
  <example>
    <desc>Animates all paragraphs to slide up or down, completing the animation within 600 milliseconds.</desc>
    <code><![CDATA[
    $("button").click(function () {
      $("p").slideToggle("slow");
    });
]]></code>
  <css><![CDATA[
  p { width:400px; }
  ]]></css>
  <html><![CDATA[<button>Toggle</button>

  <p>
    This is the paragraph to end all paragraphs.  You
    should feel <em>lucky</em> to have seen such a paragraph in
    your life.  Congratulations!
  </p>]]></html>
  </example>
  <example>
  <desc>Animates divs between dividers with a toggle that makes some appear and some disappear.</desc>
  <code><![CDATA[
  $("#aa").click(function () {
    $("div:not(.still)").slideToggle("slow", function () {
      var n = parseInt($("span").text(), 10);
      $("span").text(n + 1);
    });
  });

]]></code>
  <css><![CDATA[
  div { background:#b977d1; margin:3px; width:60px; 
        height:60px; float:left; }
  div.still { background:#345; width:5px; }
  div.hider { display:none; }
  span { color:red; }
  p { clear: left; }]]></css>
  <html><![CDATA[<div></div>
<div class="still"></div>
<div style="display:none;">
</div><div class="still"></div>
<div></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div class="hider"></div>
<div class="still"></div>
<div></div>
<p><button id="aa">Toggle</button> There have been <span>0</span> toggled divs.</p>]]></html>
  </example>
<category name="Sliding"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
<entry type='method' name="jQuery.post" return="XMLHttpRequest">
  <signature>
    <added>1.0</added>
    <argument name="url" type="String">
      <desc>A string containing the URL to which the request is sent.</desc>
    </argument>
    <argument name="data" optional="true" type="Map, String">
      <desc>A map or string that is sent to the server with the request.</desc>
    </argument>
    <argument name="success(data, textStatus, XMLHttpRequest)" optional="true" type="Function">
      <desc>A callback function that is executed if the request succeeds.</desc>
    </argument>
    <argument name="dataType" optional="true" type="String">
      <desc>The type of data expected from the server.</desc>
    </argument>
  </signature>
  <desc>Load data from the server using a HTTP POST request.</desc>
  <longdesc><p>This is a shorthand Ajax function, which is equivalent to:</p>
    <pre>$.ajax({
  type: 'POST',
  url: <em>url</em>,
  data: <em>data</em>,
  success: <em>success</em>
  dataType: <em>dataType</em>
});
</pre>
		<p>The <code>success</code> callback function is passed the returned data, which will be an XML root element or a text string depending on the MIME type of the response. It is also passed the text status of the response.</p>
		<p>As of jQuery 1.4, the <code>success</code> callback function is also passed the XMLHttpRequest object.</p>
		<p>Most implementations will specify a success handler:</p>
		<pre>$.post('ajax/test.html', function(data) {
  $('.result').html(data);
});
</pre>
		<p>This example fetches the requested HTML snippet and inserts it on the page.</p>
		<p>Pages fetched with <code>POST</code> are never cached, so the <code>cache</code> and <code>ifModified</code> options in <code><a href="/jQuery.ajaxSetup">jQuery.ajaxSetup()</a></code> have no effect on these requests.</p></longdesc>
                <example>
                    <desc>Request the test.php page, but ignore the return results.</desc>
                    <code><![CDATA[$.post("test.php");]]></code>
                </example>
                <example>
                    <desc>Request the test.php page and send some additional data along (while still ignoring the return results).</desc>
                    <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" } );]]></code>
                </example>
                <example>
                    <desc>pass arrays of data to the server (while still ignoring the return results).</desc>
                    <code><![CDATA[$.post("test.php", { 'choices[]': ["Jon", "Susan"] });]]></code>
                </example>
                <example>
                    <desc>send form data using ajax requests</desc>
                    <code><![CDATA[$.post("test.php", $("#testform").serialize());]]></code>
                </example>
                <example>
                    <desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
                    <code><![CDATA[$.post("test.php", function(data){
   alert("Data Loaded: " + data);
 });]]></code>
                </example>
                <example>
                    <desc>Alert out the results from requesting test.php with an additional payload of data (HTML or XML, depending on what was returned).</desc>
                    <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   });]]></code>
                </example>
                <example>
                    <desc>Gets the test.php page content, store it in a XMLHttpResponse object and applies the process() JavaScript function.</desc>
                    <code><![CDATA[$.post("test.php", { name: "John", time: "2pm" },
   function(data){
     process(data);
   }, "xml");]]></code>
                </example>
                <example>
                    <desc>Gets the test.php page contents which has been returned in json format (<?php echo json_encode(array("name"=>"John","time"=>"2pm")); ?>)

</desc>
                    <code><![CDATA[$.post("test.php", { "func": "getNameAndTime" },
   function(data){
     alert(data.name); // John
     console.log(data.time); //  2pm
   }, "json");]]></code>
                </example>
            <category name="Shorthand Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="slideUp" return="jQuery">
  <desc>Hide the matched elements with a sliding motion.</desc>
  <signature>
    <added>1.0</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
  <longdesc>
<p>The <code>.slideUp()</code> method animates the height of the matched elements. This causes lower parts of the page to slide up, appearing to conceal the items. Once the height reaches 0, the <code>display</code> style property is set to <code>none</code> to ensure that the element no longer affects the layout of the page.</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 <code>200</code> and <code>600</code> milliseconds, respectively. If any other string is supplied, or if the <code>duration</code> parameter is omitted, the default duration of  <code>400</code> milliseconds is used.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
  <p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
  <p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;</pre>
  <p>With the element initially shown, we can hide it slowly:</p>
<pre>$('#clickme').click(function() {
  $('#book').slideUp('slow', function() {
    // Animation complete.
  });
});
  </pre>
  <p class="image four-across"> 
  <img src="/images/0042_06_21.png" alt="" />
  <img src="/images/0042_06_22.png" alt="" />
  <img src="/images/0042_06_23.png" alt="" /> 
  <img src="/images/0042_06_24.png" alt="" />
  </p>
  </longdesc>
  <example>
    <desc>Animates all divs to slide up, completing the animation within 400 milliseconds.</desc>
<code><![CDATA[
  $(document.body).click(function () {
    if ($("div:first").is(":hidden")) {
      $("div").show("slow");
    } else {
      $("div").slideUp();
    }
  });

  ]]></code>
  <css><![CDATA[
  div { background:#3d9a44; margin:3px; width:80px; 
    height:40px; float:left; }
  ]]></css>
  <html><![CDATA[Click me!
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <div></div>]]></html>
      </example>
    <example>
<desc>Animates the parent paragraph to slide up, completing the animation within 200 milliseconds. Once the animation is done, it displays an alert.</desc>
<code><![CDATA[
  $("button").click(function () {
    $(this).parent().slideUp("slow", function () {
      $("#msg").text($("button", this).text() + " has completed.");
    });
  });

]]></code>
<css><![CDATA[
 div { margin:2px; }
]]></css>
<html><![CDATA[<div>
  <button>Hide One</button>
  <input type="text" value="One" />

</div>
<div>
  <button>Hide Two</button>
  <input type="text" value="Two" />

</div>
<div>
  <button>Hide Three</button>
  <input type="text" value="Three" />

</div>
<div id="msg"></div>]]></html>
        </example>
<category name="Sliding"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
            <entry type='method' name="nextAll" return="jQuery">
              <signature>
                <added>1.2</added>
                <argument name="selector" optional="true" type="String">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get all following siblings of each element in the set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.nextAll()</code> method allows us to search through the successors of these elements in the DOM tree and construct a new jQuery object from the matching elements.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find the elements which come after it:</p>
<pre>$('li.third-item').nextAll().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind items 4 and 5. Since we do not supply a selector expression, these following elements are unequivocally included as part of the object. If we had supplied one, the elements would be tested for a match before they were included.</p></longdesc>
                <example>
                    <desc>Locate all the divs after the first and give them a class.</desc>
                    <code><![CDATA[$("div:first").nextAll().addClass("after");]]></code>
                    <css><![CDATA[

  div { width: 80px; height: 80px; background: #abc; 
        border: 2px solid black; margin: 10px; float: left; }
  div.after { border-color: red; }
  ]]></css>
                    <height>150</height>
                    <html><![CDATA[<div>first</div>
  <div>sibling<div>child</div></div>
  <div>sibling</div>

  <div>sibling</div>]]></html>
                </example>
                <example>
                    <desc>Locate all the paragraphs after the second child in the body and give them a class.</desc>
                    <code><![CDATA[
    $(":nth-child(1)").nextAll("p").addClass("after");
]]></code>
                    <css><![CDATA[
  div, p { width: 60px; height: 60px; background: #abc;
           border: 2px solid black; margin: 10px; float: left; }
  .after { border-color: red; }
  ]]></css>
                    <height>200</height>
                    <html><![CDATA[<p>p</p>

  <div>div</div>
  <p>p</p>
  <p>p</p>
  <div>div</div>

  <p>p</p>
  <div>div</div>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.2"/>
</entry>
            <entry type='method' name="next" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the immediately following sibling of each element in the set of matched elements. If a selector is provided, it retrieves the next sibling only if it matches that selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.next()</code> method allows us to search through the immediately following sibling of these elements in the DOM tree and construct a new jQuery object from the matching elements.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the immediately following sibling matches the selector, it remains in the newly constructed jQuery object; otherwise, it is excluded.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
   &lt;li&gt;list item 1&lt;/li&gt;
   &lt;li&gt;list item 2&lt;/li&gt;
   &lt;li class="third-item"&gt;list item 3&lt;/li&gt;
   &lt;li&gt;list item 4&lt;/li&gt;
   &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>If we begin at the third item, we can find the element which comes just after it:</p>
<pre>$('li.third-item').next().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind item 4. Since we do not supply a selector expression, this following element is unequivocally included as part of the object. If we had supplied one, the element would be tested for a match before it was included.</p></longdesc>
                <example>
                    <desc>Find the very next sibling of each disabled button and change its text "this button is disabled".</desc>
                    <code><![CDATA[$("button[disabled]").next().text("this button is disabled");]]></code>
                    <css><![CDATA[

  span { color:blue; font-weight:bold; }
  button { width:100px; }
  ]]></css>
                    <html><![CDATA[<div><button disabled="disabled">First</button> - <span></span></div>
  <div><button>Second</button> - <span></span></div>

  <div><button disabled="disabled">Third</button> - <span></span></div>]]></html>
                </example>
                <example>
                    <desc>Find the very next sibling of each paragraph. Keep only the ones with a class "selected".</desc>
                    <code><![CDATA[$("p").next(".selected").css("background", "yellow");]]></code>
                    <html><![CDATA[<p>Hello</p>

  <p class="selected">Hello Again</p>
  <div><span>And Again</span></div>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="slideDown" return="jQuery">
<desc>Display the matched elements with a sliding motion.</desc>
<signature>
  <added>1.0</added>
  <argument name="duration" type="String,Number" optional="true">
    <desc>A string or number determining how long the animation will run.</desc>
  </argument>
  <argument name="callback" type="Callback" optional="true">
    <desc>A function to call once the animation is complete.</desc>
  </argument>  
</signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
<longdesc>
<p>The <code>.slideDown()</code> method animates the height of the matched elements. This causes lower parts of the page to slide down, making way for the revealed items.</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 <code>200</code> and <code>600</code> milliseconds, respectively. If any other string is supplied, or if the <code>duration</code> parameter is omitted, the default duration of  <code>400</code> milliseconds is used.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
<p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
<p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;</pre>
<p>With the element initially hidden, we can show it slowly:</p>
<pre>$('#clickme').click(function() {
  $('#book').slideDown('slow', function() {
    // Animation complete.
  });
});</pre>
<p class="image four-across"> 
<img src="/images/0042_06_17.png" alt="" />
<img src="/images/0042_06_18.png" alt="" />
<img src="/images/0042_06_19.png" alt="" />
<img src="/images/0042_06_20.png" alt="" />
</p>
</longdesc>
<example>
    <desc>Animates all divs to slide down and show themselves over 600 milliseconds.</desc>
    <code><![CDATA[
$(document.body).click(function () {
if ($("div:first").is(":hidden")) {
$("div").slideDown("slow");
} else {
$("div").hide();
}
});

]]></code>
    <css><![CDATA[
div { background:#de9a44; margin:3px; width:80px; 
height:40px; display:none; float:left; }
]]></css>
    <html><![CDATA[Click me!
<div></div>
<div></div>
<div></div>]]></html>
</example>
<example>
    <desc>Animates all inputs to slide down, completing the animation within 1000 milliseconds. Once the animation is done, the input look is changed especially if it is the middle input which gets the focus.</desc>
    <code><![CDATA[
$("div").click(function () {
$(this).css({ borderStyle:"inset", cursor:"wait" });
$("input").slideDown(1000,function(){
$(this).css("border", "2px red inset")
.filter(".middle")
 .css("background", "yellow")
 .focus();
$("div").css("visibility", "hidden");
});
});

]]></code>
    <css><![CDATA[
div { background:#cfd; margin:3px; width:50px; 
text-align:center; float:left; cursor:pointer;
border:2px outset black; font-weight:bolder; }
input { display:none; width:120px; float:left; 
margin:10px; }
]]></css>
    <html><![CDATA[<div>Push!</div>
<input type="text" />
<input type="text" class="middle" />

<input type="text" />]]></html>
</example>
<category name="Sliding"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>
            <entry type='method' name="find" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the descendants of each element in the current set of matched elements, filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.find()</code> method allows us to search through the descendants of these elements in the DOM tree and construct a new jQuery object from the matching elements. The <code>.find()</code> and <code>.children()</code> methods are similar, except that the latter only travels a single level down the DOM tree.</p>
<p>The method accepts a selector expression of the same type that we can pass to the <code>$()</code> function. The elements will be filtered by testing whether they match this selector.</p>
<p>Consider a page with a basic nested list on it:</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 II, we can find list items within it:</p>
<pre>$('li.item-ii').find('li').css('background-color', 'red');</pre>
<p>The result of this call is a red background on items A, B, 1, 2, 3, and C. Even though item II matches the selector expression, it is not included in the results; only descendants are considered candidates for the match.</p>
<blockquote><p>Unlike in the rest of the tree traversal methods, the selector expression is required in a call to <code>.find()</code>. If we need to retrieve all of the descendant elements, we can pass in the universal selector <code>'*'</code> to accomplish this.</p></blockquote>
<p><a href="http://api.jquery.com/jquery/#selector-context">Selector context</a> is implemented with the <code>.find()</code> <code>method;</code> therefore, <code>$('li.item-ii').find('li')</code> is equivalent to <code>$('li', 'li.item-ii')</code>.</p>
</longdesc>
<example>
  <desc>Starts with all paragraphs and searches for descendant span elements, same as $("p span")</desc>
  <code><![CDATA[
  $("p").find("span").css('color','red');
]]></code>
  <html><![CDATA[<p><span>Hello</span>, how are you?</p>
<p>Me? I'm <span>good</span>.</p>]]></html>
</example>
<example>
  <desc>Add spans around each word then add a hover and italicize words with the letter <strong>t</strong>.</desc>
  <code><![CDATA[
  var newText = $("p").text().split(" ").join("</span> <span>");
  newText = "<span>" + newText + "</span>";

  $("p").html(newText)
    .find('span')
    .hover(function() { 
      $(this).addClass("hilite"); 
    },
      function() { $(this).removeClass("hilite"); 
    })
  .end()
    .find(":contains('t')")
    .css({"font-style":"italic", "font-weight":"bolder"});

]]></code>
  <css><![CDATA[
  p { font-size:20px; width:200px; cursor:default; 
      color:blue; font-weight:bold; margin:0 10px; }
  .hilite { background:yellow; }
  ]]></css>
<html><![CDATA[<p>
  When the day is short
  find that which matters to you
  or stop believing
  </p>]]></html>
    </example>
<category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="jQuery.getScript" return="XMLHttpRequest">
				<signature>
                	<added>1.0</added>
	                <argument name="url" type="String">
	                    <desc>A string containing the URL to which the request is sent.</desc>
	                </argument>
	                <argument name="success(data, textStatus)" optional="true" type="Function">
	                    <desc>A callback function that is executed if the request succeeds.</desc>
	                </argument>
				</signature>
                <desc>Load a JavaScript file from the server using a GET HTTP request, then execute it.</desc>
                <longdesc><p>This is a shorthand Ajax function, which is equivalent to:</p>
				<pre>$.ajax({
  url: <em>url</em>,
  dataType: 'script',
  success: <em>success</em>
});
</pre>
				<p>The callback is passed the returned JavaScript file. This is generally not useful as the script will already have run at this point.</p>
				<p>The script is executed in the global context, so it can refer to other variables and use jQuery functions. Included scripts should have some impact on the current page:</p>
				<pre>$('.result').html('&lt;p&gt;Lorem ipsum dolor sit amet.&lt;/p&gt;');</pre>
				<p>The script can then be included and run by referencing the file name:</p>
				<pre>$.getScript('ajax/test.js', function() {
  alert('Load was performed.');
});</pre></longdesc>
                <example>
                    <desc>Load the <a href="http://github.com/jquery/jquery-color">official jQuery Color Animation plugin</a> dynamically and bind some color animations to occur once the new functionality is loaded.</desc>
                    <code><![CDATA[$.getScript("http://dev.jquery.com/view/trunk/plugins/color/jquery.color.js", function(){
  $("#go").click(function(){
    $(".block").animate( { backgroundColor: 'pink' }, 1000)
      .animate( { backgroundColor: 'blue' }, 1000);
  });
});]]></code>
                    <html><![CDATA[<button id="go">&raquo; Run</button>

<div class="block"></div>
]]></html>
                    <css><![CDATA[.block { 
   background-color: blue; 
   width: 150px; 
   height: 70px;
   margin: 10px; 
}]]></css>
                </example>
                <example>
                    <desc>Load the test.js JavaScript file and execute it.</desc>
                    <code><![CDATA[$.getScript("test.js");]]></code>
                </example>
                <example>
                    <desc>Load the test.js JavaScript file and execute it, displaying an alert message when the execution is complete.</desc>
                    <code><![CDATA[$.getScript("test.js", function(){
   alert("Script loaded and executed.");
 });]]></code>
                </example>
            <category name="Shorthand Methods"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="contents" return="jQuery">
              <signature>
                <added>1.2</added>
              </signature>
              <desc>Get the children of each element in the set of matched elements, including text and comment nodes.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.contents()</code> method allows us to search through the immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The <code>.contents()</code> and <code>.children()</code> methods are similar, except that the former includes text nodes as well as HTML elements in the resulting jQuery object.</p>
<p>The <code>.contents()</code> method can also be used to get the content document of an iframe, if the iframe is on the same domain as the main page.</p>
<p>Consider a simple <code>&lt;div&gt;</code> with a number of text nodes, each of which is separated by two line break elements (<code>&lt;br /&gt;</code>):</p>
<pre>&lt;div class="container"&gt;
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
  do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
  &lt;br /&gt;&lt;br /&gt;
  Ut enim ad minim veniam, quis nostrud exercitation ullamco 
  laboris nisi ut aliquip ex ea commodo consequat.
  &lt;br /&gt; &lt;br /&gt;
  Duis aute irure dolor in reprehenderit in voluptate velit 
  esse cillum dolore eu fugiat nulla pariatur.
&lt;/div&gt;
</pre>
<p>We can employ the <code>.contents()</code> method to help convert this blob of text into three well-formed paragraphs:</p>
<pre>
$('.container').contents().filter(function() {
  return this.nodeType == 3;
})
  .wrap('&lt;p&gt;&lt;/p&gt;')
.end()
.filter('br')
  .remove();
</pre>
<p>This code first retrieves the contents  of <code>&lt;div class="container"&gt;</code> and then filters it for text nodes, which are wrapped in paragraph tags. This is accomplished by testing the <a href="https://developer.mozilla.org/en/nodeType"><code>.nodeType</code> property</a> of the element. This DOM property holds a numeric code indicating the node's type; text nodes use the code 3. The contents are again filtered, this time for <code>&lt;br /&gt;</code> elements, and these elements are removed.</p>
</longdesc>
  <example>
    <desc>Find all the text nodes inside a paragraph and wrap them with a bold tag.</desc>
    <code><![CDATA[$("p").contents().filter(function(){ return this.nodeType != 1; }).wrap("<b/>");]]></code>
    <html><![CDATA[<p>Hello <a href="http://ejohn.org/">John</a>, how are you doing?</p>]]></html>
  </example>
  <example>
    <desc>Change the background colour of links inside of an iframe.</desc>
    <code><![CDATA[$("#frameDemo").contents().find("a").css("background-color","#BADA55");]]></code>
    <html><![CDATA[<iframe src="http://api.jquery.com/" width="80%" height="600" id='frameDemo'></iframe> ]]></html>
  </example>

  <category name="Miscellaneous Traversing"/>
<category name="Version 1.2"/>
</entry>

            <entry type='method' name="closest" return="jQuery">
              <signature>
                <added>1.3</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.4</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
                <argument name="context" optional="true" type="Element">
                  <desc>A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.</desc>
                </argument>
              </signature>
              <desc>Get the first ancestor element that matches the selector, beginning at the current element and progressing up through the DOM tree.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.closest()</code> method allows us to search through these elements and their ancestors in the DOM tree and construct a new jQuery object from the matching elements. The <code>.parents()</code> and <code>.closest()</code> methods are similar in that they both traverse up the DOM tree. The differences between the two, though subtle, are significant:</p>
<table>
  <thead>
  	<tr>
  	  <th>.closest()</th>
  	  <th>.parents()</th>
  	</tr>
  </thead>
  <tbody>
  	<tr>
  	  <td>Begins with the current element</td>
  	  <td>Begins with the parent element</td></tr>
  	<tr>
  	  <td>Travels up the DOM tree until it finds a match for the supplied selector</td>
  	  <td>Travels up the DOM tree to the document's root element, adding each ancestor element to a temporary collection; it then filters that collection based on a selector if one is supplied </td>
  	  </tr>
  	<tr>
  	  <td>The returned jQuery object contains zero or one element</td>
  	  <td>The returned jQuery object contains zero, one, or multiple elements</td>
  	</tr>
  </tbody>
</table>

              
<pre>
  &lt;ul id="one" class="level-1"&gt;
    &lt;li class="item-i"&gt;I&lt;/li&gt;
    &lt;li id="ii" 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>Suppose we perform a search for <code>&lt;ul&gt;</code> elements starting at item A:</p>
<pre>
$('li.item-a').closest('ul')
  .css('background-color', 'red');
</pre>
<p>This will change the color of the level-2 <code>&lt;ul&gt;</code>, since it is the first encountered when traveling up the DOM tree.</p>
<p>Suppose we search for an <code>&lt;li&gt;</code> element instead:</p>
<pre>$('li.item-a').closest('li')
  .css('background-color', 'red');
</pre>
<p>This will change the color of list item A. The <code>.closest()</code> method begins its search with the element itself before progressing up the DOM tree, and stops when item A matches the selector.</p>
<p>We can pass in a DOM element as the context within which to search for the closest element.</p>
<pre>var listItemII = document.getElementById('ii');
$('li.item-a').closest('ul', listItemII)
  .css('background-color', 'red');
$('li.item-a').closest('#one', listItemII)
  .css('background-color', 'green');</pre>
<p>This will change the color of the level-2 <code>&lt;ul&gt;</code>, because it is both the first <code>&lt;ul&gt;</code> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <code>&lt;ul&gt;</code>, however, because it is not a descendant of list item II.</p>
</longdesc>
                <example>
                    <desc>Show how event delegation can be done with closest.</desc>
                    <code><![CDATA[

    $(document).bind("click", function (e) {
      $(e.target).closest("li").toggleClass("hilight");
    });
]]></code>
                    <css><![CDATA[
  li { margin: 3px; padding: 3px; background: #EEEEEE; }
  li.hilight { background: yellow; }
  ]]></css>
  <html><![CDATA[<ul>
<li><b>Click me!</b></li>
<li>You can also <b>Click me!</b></li>
</ul>]]></html>
  </example>
  <category name="Tree Traversal"/>
<category name="Version 1.3"/>
<category name="Version 1.4"/>
</entry>
  <entry type='method' name="closest" return="Array">
    <signature>
      <added>1.4</added>
      <argument name="selectors" type="Array">
        <desc>An array or string containing a selector expression to match elements against (can also be a jQuery object).</desc>
      </argument>
      <argument name="context" optional="true" type="Element">
        <desc>A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.</desc>
      </argument>
    </signature>
    <desc>Gets an array of all the elements and selectors matched against the current element up through the DOM tree.</desc>
    <longdesc><p>This method is primarily meant to be used internally or by plugin authors.</p></longdesc>
    <example>
      <desc>Show how event delegation can be done with closest.</desc>
      <code><![CDATA[var close = $("li:first").closest(["ul", "body"]);
        $.each(close, function(i){
  $("li").eq(i).html( this.selector + ": " + this.elem.nodeName );
});]]></code>
        <css><![CDATA[]]></css>
        <html><![CDATA[<ul><li></li><li></li></ul>]]></html>
      </example>
    <category name="Tree Traversal"/>
<category name="Version 1.3"/>
<category name="Version 1.4"/>
</entry>
  
<entry type='method' name="jQuery.getJSON" return="XMLHttpRequest">
  <signature>
    <added>1.0</added>
    <argument name="url" type="String">
      <desc>A string containing the URL to which the request is sent.</desc>
    </argument>
    <argument name="data" optional="true" type="Map">
      <desc>A map or string that is sent to the server with the request.</desc>
    </argument>
    <argument name="callback(data, textStatus, xhr)" optional="true" type="Function">
      <desc>A callback function that is executed if the request succeeds.</desc>
    </argument>
  </signature>
  <desc>Load JSON-encoded data from the server using a GET HTTP request.</desc>
  <longdesc>
    <p>This is a shorthand Ajax function, which is equivalent to:</p>
				<pre>$.ajax({
  url: <em>url</em>,
  dataType: 'json',
  data: <em>data</em>,
  success: <em>callback</em>
});
</pre>
    <p>Data that is sent to the server is appended to the URL as a query string. If the value of the <code>data</code> parameter is an object (map), it is converted to a string and url-encoded before it is appended to the URL.</p>
    <p>The callback is passed the returned data, which will be a JavaScript object or array as defined by the JSON structure and parsed using the <code><a href="/jQuery.parseJSON">$.parseJSON()</a></code> method.</p>
    <p>Most implementations will specify a success handler:</p>
    <pre>$.getJSON('ajax/test.json', function(data) {
  $('.result').html('&lt;p&gt;' + data.foo + '&lt;/p&gt;'
    + '&lt;p&gt;' + data.baz[1] + '&lt;/p&gt;');
});
</pre>
	<p>This example, of course, relies on the structure of the JSON file:</p>
	<pre>{
  "foo": "The quick brown fox jumps over the lazy dog.",
  "bar": "ABCDEFG",
  "baz": [52, 97]
}
</pre>
  <p>Using this structure, the example inserts the first string and second number from the file onto the page.</p>
  <blockquote>
    <p><strong>Important:</strong> As of jQuery 1.4, if the JSON file contains a syntax error, the request will usually fail silently. Avoid frequent hand-editing of JSON data for this reason. JSON is a data-interchange format with syntax rules that are stricter than those of JavaScript's object literal notation. For example, all strings represented in JSON, whether they are properties or values, must be enclosed in double-quotes. For details on the JSON format, see <a href="http://json.org/">http://json.org/</a>.</p>
	</blockquote>
	<h4 id="jsonp">JSONP</h4>
  <p>If the URL includes the string "callback=?" (or similar, as defined by the server-side API), the request is treated as JSONP instead. See the discussion of the <code>jsonp</code> data type in <code><a href="/jQuery.ajax">$.ajax()</a></code> for more details.</p></longdesc>
  <example>
    <desc>Loads the four most recent cat pictures from the Flickr JSONP API.</desc>
<code><![CDATA[
$.getJSON("http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?",
  {
    tags: "cat",
    tagmode: "any",
    format: "json"
  },
  function(data) {
    $.each(data.items, function(i,item){
      $("<img/>").attr("src", item.media.m).appendTo("#images");
      if ( i == 3 ) return false;
    });
  });]]></code>
<html><![CDATA[<div id="images">

</div>]]></html>
<css><![CDATA[img{ height: 100px; float: left; }]]></css>
</example>
<example>
  <desc>Load the JSON data from test.js and access a name from the returned JSON data.</desc>
  <code><![CDATA[$.getJSON("test.js", function(json) {
   alert("JSON Data: " + json.users[3].name);
 });]]></code>
</example>
<example>
  <desc>Load the JSON data from test.js, passing along additional data, and access a name from the returned JSON data.</desc>
  <code><![CDATA[$.getJSON("test.js", { name: "John", time: "2pm" }, function(json){
    alert("JSON Data: " + json.users[3].name);
    });]]></code>
  </example>
  <example>
    <desc>List the result of a consultation of pages.php in HTML as an array. By Manuel Gonzalez.</desc>
    <code><![CDATA[

var id=$("#id").attr("value");
$.getJSON("pages.php",{id:id},dates);

function dates(datos) {
    
  $("#list").html("Name:"+datos[1].name+"<br>"+"Last Name:"+datos[1].lastname+"<br>"+"Address:"+datos[1].address);
}

]]></code>
</example>
<category name="Shorthand Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.get" return="XMLHttpRequest">
  <signature>
    <added>1.0</added>
    <argument name="url" type="String">
      <desc>A string containing the URL to which the request is sent.</desc>
    </argument>
    <argument name="data" optional="true" type="Map, String">
      <desc>A map or string that is sent to the server with the request.</desc>
    </argument>
    <argument name="callback(data, textStatus, XMLHttpRequest)" optional="true" type="Function">
      <desc>A callback function that is executed if the request succeeds.</desc>
    </argument>
    <argument name="dataType" optional="true" type="String">
      <desc>The type of data expected from the server.</desc>
    </argument>
  </signature>
  <desc>Load data from the server using a HTTP GET request.</desc>
  <longdesc><p>This is a shorthand Ajax function, which is equivalent to:</p>
				<pre>$.ajax({
  url: <em>url</em>,
  data: <em>data</em>,
  success: <em>success</em>,
  dataType: <em>dataType</em>
});
</pre>
				<p>The <code>success</code> callback function is passed the returned data, which will be an XML root element, text string, JavaScript file, or JSON object, depending on the MIME type of the response. It is also passed the text status of the response. </p>
				<p>As of jQuery 1.4, the <code>success</code> callback function is also passed the XMLHttpRequest object.</p>
				<p>Most implementations will specify a success handler:</p>
				<pre>$.get('ajax/test.html', function(data) {
  $('.result').html(data);
  alert('Load was performed.');
});
</pre>
				<p>This example fetches the requested HTML snippet and inserts it on the page.</p></longdesc>
                <example>
                    <desc>Request the test.php page, but ignore the return results.</desc>
                    <code><![CDATA[$.get("test.php");]]></code>
                </example>
                <example>
                    <desc>Request the test.php page and send some additional data along (while still ignoring the return results).</desc>
                    <code><![CDATA[$.get("test.php", { name: "John", time: "2pm" } );]]></code>
                </example>
                <example>
                    <desc>pass arrays of data to the server (while still ignoring the return results).</desc>
                    <code><![CDATA[$.get("test.php", { 'choices[]': ["Jon", "Susan"]} );]]></code>
                </example>
                <example>
                    <desc>Alert out the results from requesting test.php (HTML or XML, depending on what was returned).</desc>
                    <code><![CDATA[$.get("test.php", function(data){
   alert("Data Loaded: " + data);
 });]]></code>
                </example>
                <example>
                    <desc>Alert out the results from requesting test.cgi with an additional payload of data (HTML or XML, depending on what was returned).</desc>
                    <code><![CDATA[$.get("test.cgi", { name: "John", time: "2pm" },
   function(data){
     alert("Data Loaded: " + data);
   });]]></code>
                </example>
            <category name="Shorthand Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="load" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="url" type="String">
      <desc>A string containing the URL to which the request is sent.</desc>
    </argument>
    <argument name="data" optional="true " type="Map, String">
      <desc>A map or string that is sent to the server with the request.</desc>
    </argument>
    <argument name="complete(responseText, textStatus, XMLHttpRequest)" type="Function" optional="true">
      <desc>A callback function that is executed when the request completes.</desc>
    </argument>
  </signature>
  <desc>Load data from the server and place the returned HTML into the matched element.</desc>
  <longdesc>
    <p>This method is the simplest way to fetch data from the server. It is roughly equivalent to <code>$.get(url, data, success)</code> except that it is a method rather than global function and it has an implicit callback function.  When a successful response is detected (i.e. when <code>textStatus</code> is "success" or "notmodified"), <code>.load()</code> sets the HTML contents of the matched element to the returned data. This means that most uses of the method can be quite simple:</p>
    <pre>$('#result').load('ajax/test.html');</pre>
    <p>The provided callback, if any, is executed after this post-processing has been performed:</p>
    <pre>$('#result').load('ajax/test.html', function() {
  alert('Load was performed.');
});</pre>
    <p>In the two examples above, if the current document does not contain an element with an ID of "result," the <code>.load()</code> method is not executed.</p>
    <p>The POST method is used if data is provided as an object; otherwise, GET is assumed.</p>

    <blockquote><p>Note: The event handling suite also has a method named <code><a href='/load-event'>.load()</a></code>. Which one is fired depends on the set of arguments passed.</p></blockquote>
    <h4>Loading Page Fragments</h4>
    <p>The <code>.load()</code> method, unlike <code><a href='/jQuery.get'>$.get()</a></code>, allows us to specify a portion of the remote document to be inserted. This is achieved with a special syntax for the <code>url</code> parameter. If one or more space characters are included in the string, the portion of the string following the first space is assumed to be a jQuery selector that determines the content to be loaded.   </p>
    <p>We could modify the example above to use only part of the document that is fetched:</p>
    <pre>$('#result').load('ajax/test.html #container');</pre>
    <p>When this method executes, it retrieves the content of <code>ajax/test.html</code>, but then jQuery parses the returned document to find the element with an ID of <code>container</code>. This element, along with its contents, is inserted into the element with an ID of <code>result</code>, and the rest of the retrieved document is discarded.</p>
<p>jQuery uses the browser's <code>.innerHTML</code> property to parse the retrieved document and insert it into the current document. During this process, browsers often filter elements from the document such as <code>&lt;html&gt;</code>, <code>&lt;title&gt;</code>, or <code>&lt;head&gt;</code> elements. As a result, the elements retrieved by <code>.load()</code> may not be exactly the same as if the document were retrieved directly by the browser.</p>
  </longdesc>
  <example>
    <desc>Load the main page's footer navigation into an ordered list.</desc>
    <code><![CDATA[
  $("#new-nav").load("/ #jq-footerNavigation li");
]]></code>
    <css><![CDATA[
 body{ font-size: 12px; font-family: Arial; }
 ]]></css>
    <html><![CDATA[
<b>Footer navigation:</b>
<ol id="new-nav"></ol>
]]></html>
  </example>
    <example>
      <desc>Display a notice if the Ajax request encounters an error.</desc>
      <code><![CDATA[
$("#success").load("/not-here.php", function(response, status, xhr) {
  if (status == "error") {
    var msg = "Sorry but there was an error: ";
    $("#error").html(msg + xhr.status + " " + xhr.statusText);
  }
});
  ]]></code>
<css><![CDATA[
  body{ font-size: 12px; font-family: Arial; }
  ]]></css>
<html><![CDATA[
<b>Successful Response (should be blank):</b>
<div id="success"></div>
<b>Error Response:</b>
<div id="error"></div>
  ]]></html>
    </example>
  
  <example>
    <desc>Load the feeds.html file into the div with the ID of feeds.</desc>
    <code><![CDATA[$("#feeds").load("feeds.html");]]></code>
    <results><![CDATA[<div id="feeds"><b>45</b> feeds found.</div>]]></results>
  </example>
  <example>
    <desc>pass arrays of data to the server.</desc>
    <code><![CDATA[$("#objectID").load("test.php", { 'choices[]': ["Jon", "Susan"] } );]]></code>
  </example>
  <example>
    <desc>Same as above, but will POST the additional parameters to the server and a callback that is executed when the server is finished responding.</desc>
    <code><![CDATA[$("#feeds").load("feeds.php", {limit: 25}, function(){
alert("The last 25 entries in the feed have been loaded");
});]]></code>
  </example>
<category name="Shorthand Methods"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.ajax" return="XMLHttpRequest">
  <signature>
    <added>1.0</added>
    <argument name="settings" type="Map">
      <desc>A set of key/value pairs that configure the Ajax request. All options are optional. A default can be set for any option with <a href="/jQuery.ajaxSetup">$.ajaxSetup()</a>.</desc>
    </argument>
    <option default="true" name="async" type="Boolean">
      <desc>By default, all requests are sent asynchronous (i.e. this is set to true by default). If you need synchronous requests, set this option to false. Cross-domain requests and <code>dataType: "jsonp"</code> requests do not support synchronous operation. Note that synchronous requests may temporarily lock the browser, disabling any actions while the request is active.</desc>
    </option>
    <option name="beforeSend(XMLHttpRequest)" type="Function">
      <desc>A pre-callback to modify the XMLHttpRequest object before it is sent. Use this to set custom headers etc. The XMLHttpRequest is passed as the only argument. This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>. You may return false in function to cancel the request.</desc>
    </option>
    <option default="true, false for dataType 'script' and 'jsonp'" name="cache" type="Boolean">
      <desc>If set to false it will force the pages that you request to not be cached by the browser.</desc>
    </option>
    <option name="complete(XMLHttpRequest, textStatus)" type="Function">
      <desc>A function to be called when the request finishes (after success and error callbacks are executed). The function gets passed two arguments: The XMLHttpRequest object and a string categorizing the status of the request (<code>"success"</code>, <code>"notmodified"</code>, <code>"error"</code>, <code>"timeout"</code>, or <code>"parsererror"</code>). This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
    </option>
    <option default="'application/x-www-form-urlencoded'" name="contentType" type="String">
      <desc>When sending data to the server, use this content-type. Default is "application/x-www-form-urlencoded", which is fine for most cases. If you explicitly pass in a content-type to $.ajax() then it'll always be sent to the server (even if no data is sent). Data will always be transmitted to the server using UTF-8 charset; you must decode this appropriately on the server side.</desc>
    </option>
    <option name="context" type="Object">
      <desc>This object will be made the context of all Ajax-related callbacks. For example specifying a DOM element as the context will make that the context for the complete callback of a request, like so: <pre>$.ajax({ url: "test.html", context: document.body, success: function(){
        $(this).addClass("done");
      }});</pre></desc>
    </option>
    <option name="data" type="Object, String">
      <desc>Data to be sent to the server. It is converted to a query string, if not already a string. It's appended to the url for GET-requests. See processData option to prevent this automatic processing. Object must be Key/Value pairs. If value is an Array, jQuery serializes multiple values with same key based on the value of the <code>traditional</code> setting (described below).</desc>
    </option>
    <option name="dataFilter(data, type)" type="Function">
      <desc>A function to be used to handle the raw responsed data of XMLHttpRequest.This is a pre-filtering function to sanitize the response.You should return the sanitized data.The function gets passed two arguments: The raw data returned from the server, and the 'dataType' parameter.</desc>
    </option>
    <option default="Intelligent Guess (xml, json, script, or html)" name="dataType" type="String">
      <desc>The type of data that you're expecting back from the server. If none is specified, jQuery will intelligently try to get the results, based on the MIME type of the response (an XML MIME type will yield XML, in 1.4 JSON will yield a JavaScript object, in 1.4 script will execute the script, and anything else will be returned as a string). The available types (and the result passed as the first argument to your success callback) are:
        <ul>
          <li>"xml": Returns a XML document that can be processed via jQuery.</li>
          <li>"html": Returns HTML as plain text; included script tags are evaluated when inserted in the DOM.</li>
          <li>"script": Evaluates the response as JavaScript and returns it as plain text. Disables caching unless option "cache" is used. <strong>Note:</strong> This will turn POSTs into GETs for remote-domain requests.</li>
          <li>"json": Evaluates the response as JSON and returns a JavaScript object. In jQuery 1.4 the JSON data is parsed in a strict manner; any malformed JSON is rejected and a parse error is thrown. (See <a href="http://json.org/">json.org</a> for more information on proper JSON formatting.)</li>
          <li>"jsonp": Loads in a JSON block using <a href="http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/">JSONP</a>. Will add an extra "?callback=?" to the end of your URL to specify the callback.</li>
          <li>"text": A plain text string.</li>
        </ul></desc>
      </option>
      <option name="error(XMLHttpRequest, textStatus, errorThrown)" type="Function">
        <desc>A function to be called if the request fails. The function is passed three arguments: The XMLHttpRequest object, a string describing the type of error that occurred and an optional exception object, if one occurred. Possible values for the second argument (besides null) are "timeout", "error", "notmodified" and "parsererror". This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
      </option>
      <option default="true" name="global" type="Boolean">
        <desc>Whether to trigger global Ajax event handlers for this request. The default is true. Set to false to prevent the global handlers like ajaxStart or ajaxStop from being triggered. This can be used to control various <a href='http://docs.jquery.com/Ajax_Events'>Ajax Events</a>.</desc>
      </option>
      <option default="false" name="ifModified" type="Boolean">
        <desc>Allow the request to be successful only if the response has changed since the last request. This is done by checking the Last-Modified header. Default value is false, ignoring the header. In jQuery 1.4 this technique also checks the 'etag' specified by the server to catch unmodified data.</desc>
      </option>
      <option name="jsonp" type="String">
        <desc>Override the callback function name in a jsonp request.  This value will be used instead of 'callback' in the 'callback=?' part of the query string in the url.  So <code>{jsonp:'onJsonPLoad'}</code> would result in <code>'onJsonPLoad=?'</code> passed to the server.</desc>
      </option>
      <option name="jsonpCallback" type="String">
        <desc>Specify the callback function name for a jsonp request.  This value will be used instead of the random name automatically generated by jQuery. It is preferable to let jQuery generate a unique name as it'll make it easier to manage the requests and provide callbacks and error handling. You may want to specify the callback when you want to enable better browser caching of GET requests.</desc>
      </option>
      <option name="password" type="String">
        <desc>A password to be used in response to an HTTP access authentication request.</desc>
      </option>
      <option default="true" name="processData" type="Boolean">
        <desc>By default, data passed in to the data option as an object (technically, anything other than a string) will be processed and transformed into a query string, fitting to the default content-type "application/x-www-form-urlencoded". If you want to send a DOMDocument, or other non-processed data, set this option to false.</desc>
      </option>
      <option name="scriptCharset" type="String">
        <desc>Only for requests with "jsonp" or "script" dataType and "GET" type. Forces the request to be interpreted as a certain charset. Only needed for charset differences between the remote and local content.</desc>
      </option>
      <option name="success(data, textStatus, XMLHttpRequest)" type="Function">
        <desc>A function to be called if the request succeeds. The function gets passed three arguments: The data returned from the server, formatted according to the 'dataType' parameter; a string describing the status; and the XMLHttpRequest object (available as of jQuery 1.4). This is an <a href='http://docs.jquery.com/Ajax_Events'>Ajax Event</a>.</desc>
      </option>
      <option name="timeout" type="Number">
        <desc>Set a local timeout (in milliseconds) for the request. This will override the global timeout, if one is set via <a href='/jQuery.ajaxSetup'>$.ajaxSetup</a>. For example, you could use this property to give a single request a longer timeout than all other requests that you've set to time out in one second. See <a href='/jQuery.ajaxSetup'>$.ajaxSetup</a>() for global timeouts.</desc>
      </option>
      <option name="traditional" type="Boolean">
        <desc>Set this to true if you wish to use the traditional style of <a href="/jQuery.param">param serialization</a>.</desc>
      </option>
      <option default="'GET'" name="type" type="String">
        <desc>The type of request to make ("POST" or "GET"), default is "GET". <strong>Note:</strong> Other HTTP request methods, such as PUT and DELETE, can also be used here, but they are not supported by all browsers.</desc>
      </option>
      <option default="The current page" name="url" type="String">
        <desc> A string containing the URL to which the request is sent.</desc>
      </option>
      <option name="username" type="String">
        <desc>A username to be used in response to an HTTP access authentication request.</desc>
      </option>
      <option name="xhr" type="Function">
        <desc>Callback for creating the XMLHttpRequest object. Defaults to the ActiveXObject when available (IE), the XMLHttpRequest otherwise. Override to provide your own implementation for XMLHttpRequest or enhancements to the factory.</desc>
      </option>
    </signature>
    <desc>Perform an asynchronous HTTP (Ajax) request.</desc>
    <longdesc><p>The <code>$.ajax()</code> function underlies all Ajax requests sent by jQuery.  It is often unnecessary to directly call this function, as several higher-level alternatives like <code><a href="/jQuery.get">$.get()</a></code> and <code><a href="/load">.load()</a></code> are available and are easier to use. If less common options are required, though, <code>$.ajax()</code> can be used more flexibly.</p>
      <p>At its simplest, the <code>$.ajax()</code> function can be called with no arguments:</p>
      <pre>$.ajax();</pre>

      <p><strong>Note:</strong> Default settings can be set globally by using the <code><a href="/jQuery.ajaxSetup">$.ajaxSetup()</a></code> function.</p>

      <p>This example, using no options, loads the contents of the current page, but does nothing with the result. To use the result, we can implement one of the callback functions.</p>

      <h4 id="callback-functions">Callback Functions</h4>
      <p>The <code>beforeSend</code>, <code>error</code>, <code>dataFilter</code>, <code>success</code> and <code>complete</code> options all take callback functions that are invoked at the appropriate times. The <code>this</code> object for all of them will be the object in the <code>context</code> property passed to <code>$.ajax</code> in the settings; if that was not specified it will be a reference to the Ajax settings themselves. Some types of Ajax requests, such as JSONP and cross-domain GET requests, do not use XHR; in those cases the <code>XMLHttpRequest</code> parameter passed to the callback will be <code>undefined</code>.</p>
      <ol>
        <li><code>beforeSend</code> is called before the request is sent, and is passed the <code>XMLHttpRequest</code> object as a parameter.</li>
        <li><code>error</code> is called if the request fails. It is passed the <code>XMLHttpRequest</code>, a string indicating the error type, and an exception object if applicable.</li>
        <li><code>dataFilter</code> is called on success. It is passed the returned data and the value of <code>dataType</code>, and must return the (possibly altered) data to pass on to <code>success</code>.</li>
        <li><code>success</code> is called if the request succeeds. It is passed the returned data, a string containing the success code, and the <code>XMLHttpRequest</code> object.</li>
        <li><code>complete</code> is called when the request finishes, whether in failure or success. It is passed the <code>XMLHttpRequest</code> object, as well as a string containing the success or error code.</li>
      </ol>
      <p>To make use of the returned HTML, we can implement a <code>success</code> handler:</p>
<pre>$.ajax({
  url: 'ajax/test.html',
  success: function(data) {
    $('.result').html(data);
    alert('Load was performed.');
  }
});</pre>
	    <p>Such a simple example would generally be better served by using <code><a href="/load">.load()</a></code> or <code><a href="/jQuery.get">$.get()</a></code>.</p>
				
      <h4 id="data-types">Data Types</h4>
      <p>The <code>$.ajax()</code> function relies on the server to provide information about the retrieved data. If the server reports the return data as XML, the result can be traversed using normal XML methods or jQuery's selectors. If another type is detected, such as HTML in the example above, the data is treated as text.</p>
      <p>Different data handling can be achieved by using the <code>dataType</code> option. Besides plain <code>xml</code>, the <code>dataType</code> can be <code>html</code>, <code>json</code>, <code>jsonp</code>, <code>script</code>, or <code>text</code>.</p>
      <p>The <code>text</code> and <code>xml</code> types return the data with no processing. The data is simply passed on to the success handler, either through the <code>responseText</code> or <code>responseXML</code> property of the <code>XMLHttpRequest</code> object, respectively.</p>
      <p><strong>Note:</strong> We must ensure that the MIME type reported by the web server matches our choice of <code>dataType</code>. In particular, XML must be declared by the server as <code>text/xml</code> or <code>application/xml</code> for consistent results.</p>
      <p>If <code>html</code> is specified, any embedded JavaScript inside the retrieved data is executed before the HTML is returned as a string. Similarly, <code>script</code> will execute the JavaScript that is pulled back from the server, then return the script itself as textual data.</p>
      <p>The <code>json</code> type parses the fetched data file as a JavaScript object and returns the constructed object as the result data. To do so, it uses <code>JSON.parse()</code> when the browser supports it; otherwise it uses a <code>Function</code> <strong>constructor</strong>. Malformed JSON data will throw a parse error (see <a href="http://json.org/">json.org</a> for more information). JSON data is convenient for communicating structured data in a way that is concise and easy for JavaScript to parse. If the fetched data file exists on a remote server, specify the <code>jsonp</code> type instead.</p>
      <p>The <code>jsonp</code> type appends a query string parameter of <code>callback=?</code> to the URL. The server should prepend the JSON data with the callback name to form a valid JSONP response. We can specify a parameter name other than <code>callback</code> with the <code>jsonp</code> option to <code>$.ajax()</code>.</p>
      <p><strong>Note:</strong> JSONP is an extension of the JSON format, requiring some server-side code to detect and handle the query string parameter. More information about it can be found in the <a href="http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/">original post detailing its use</a>.</p>
      <p>When data is retrieved from remote servers (which is only possible using the <code>script</code> or <code>jsonp</code> data types), the operation is performed using a <code>&lt;script&gt;</code> tag rather than an <code>XMLHttpRequest</code> object. In this case, no <code>XMLHttpRequest</code> object is returned from <code>$.ajax()</code>, nor is one passed to the handler functions such as <code>beforeSend</code>.</p>
				
					<h4 id="sending-data-to-server">Sending Data to the Server</h4>
					<p>By default, Ajax requests are sent using the GET HTTP method. If the POST method is required, the method can be specified by setting a value for the <code>type</code> option. This option affects how the contents of the <code>data</code> option are sent to the server. POST data will always be transmitted to the server using UTF-8 charset, per the W3C XMLHTTPRequest standard.</p>
					<p>The <code>data</code> option can contain either a query string of the form <code>key1=value1&amp;key2=value2</code>, or a map of the form <code>{key1: 'value1', key2: 'value2'}</code>. If the latter form is used, the data is converted into a query string using <code><a href="http://api.jquery.com/jQuery.param/">jQuery.param()</a></code> before it is sent. This processing can be circumvented by setting <code>processData</code> to <code>false</code>.  The processing might be undesirable if we wish to send an XML object to the server; in this case, we would also want to change the <code>contentType</code> option from <code>application/x-www-form-urlencoded</code> to a more appropriate MIME type.</p>
				
					<h4 id="advanced-options">Advanced Options</h4>
					<p>The <code>global</code> option prevents handlers registered using <code><a href="/ajaxSend">.ajaxSend()</a></code>, <code><a href="/ajaxError">.ajaxError()</a></code>, and similar methods from firing when this request would trigger them. This can be useful to, for example, suppress a loading indicator that was implemented with <code><a href="/ajaxSend">.ajaxSend()</a></code> if the requests are frequent and brief. See the descriptions of these methods below for more details.</p>
					<p>If the server performs HTTP authentication before providing a response, the user name and password pair can be sent via the <code>username</code> and <code>password</code> options.</p>
					<p>Ajax requests are time-limited, so errors can be caught and handled to provide a better user experience. Request timeouts are usually either left at their default or set as a global default using <code><a href="/jQuery.ajaxSetup">$.ajaxSetup()</a></code> rather than being overridden for specific requests with the <code>timeout</code> option.</p>
					<p>By default, requests are always issued, but the browser may serve results out of its cache. To disallow use of the cached results, set <code>cache</code> to <code>false</code>. To cause the request to report failure if the asset has not been modified since the last request, set <code>ifModified</code> to <code>true</code>.</p>
					<p>The <code>scriptCharset</code> allows the character set to be explicitly specified for requests that use a <code>&lt;script&gt;</code> tag (that is, a type of <code>script</code> or <code>jsonp</code>). This is useful if the script and host page have differing character sets.</p>
					<p>The first letter in Ajax stands for "asynchronous," meaning that the operation occurs in parallel and the order of completion is not guaranteed. The <code>async</code> option to <code>$.ajax()</code> defaults to <code>true</code>, indicating that code execution can continue after the request is made. Setting this option to <code>false</code> (and thus making the call no longer asynchronous) is strongly discouraged, as it can cause the browser to become unresponsive.</p>
					
					<p>The <code>$.ajax()</code> function returns the <code>XMLHttpRequest</code> object that it creates. Normally jQuery handles the creation of this object internally, but a custom function for manufacturing one can be specified using the <code>xhr</code> option. The returned object can generally be discarded, but does provide a lower-level interface for observing and manipulating the request. In particular, calling <code>.abort()</code> on the object will halt the request before it completes.</p></longdesc>
                <example>
                    <desc>Load and execute a JavaScript file.</desc>
                    <code><![CDATA[$.ajax({
   type: "GET",
   url: "test.js",
   dataType: "script"
 });]]></code>
                </example>
                <example>
                    <desc>Save some data to the server and notify the user once it's complete.</desc>
                    <code><![CDATA[$.ajax({
   type: "POST",
   url: "some.php",
   data: "name=John&location=Boston",
   success: function(msg){
     alert( "Data Saved: " + msg );
   }
 });]]></code>
                </example>
                <example>
                    <desc>Retrieve the latest version of an HTML page.</desc>
                    <code><![CDATA[$.ajax({
  url: "test.html",
  cache: false,
  success: function(html){
    $("#results").append(html);
  }
});]]></code>
                </example>
                <example>
                    <desc>Loads data synchronously. Blocks the browser while the requests is active.
It is better to block user interaction by other means when synchronization is
necessary.</desc>
                    <code><![CDATA[var html = $.ajax({
  url: "some.php",
  async: false
 }).responseText;]]></code>
                </example>
                <example>
                    <desc>Sends an xml document as data to the server. By setting the processData
option to false, the automatic conversion of data to strings is prevented.</desc>
                   <code><![CDATA[var xmlDocument = [create xml document];
 $.ajax({
   url: "page.php",
   processData: false,
   data: xmlDocument,
   success: handleResponse
 });]]></code>
                </example>
                <example>
                    <desc>Sends an id as data to the server, save some data to the server and notify the user once it's complete.  <strong>Note that this usage - returning the result of the call into a variable - requires a synchronous (blocking) request! <em>(async:false)</em></strong></desc>
                    <code><![CDATA[bodyContent = $.ajax({
      url: "script.php",
      global: false,
      type: "POST",
      data: ({id : this.getAttribute('id')}),
      dataType: "html",
      async:false,
      success: function(msg){
         alert(msg);
      }
   }
).responseText;]]></code>
                </example>
            <category name="Low-Level Interface"/>
<category name="Version 1.0"/>
</entry>
   <entry type='property' name="length" return="Number">
                <signature><added>1.0</added></signature>
                <desc>The number of elements in the jQuery object.</desc>
                <longdesc><p>The number of elements currently matched. The .<a href='/size'>size()</a> method will return the same value.</p></longdesc>
                <example>
                    <desc>Count the divs.  Click to add more.</desc>
                    <code><![CDATA[$(document.body).click(function () {
      $(document.body).append($("<div>"));
      var n = $("div").length;
      $("span").text("There are " + n + " divs." +
                     "Click to add more.");
    }).trigger('click'); // trigger the click to start]]></code>
                    <css><![CDATA[

  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<span></span>
  <div></div>]]></html>
                </example>
            <category name="Properties of jQuery Object Instances"/>
<category name="Version 1.0"/>
</entry>
            
            
            <entry type='method' name="children" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" optional="true" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <desc>Get the children of each element in the set of matched elements, optionally filtered by a selector.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.children()</code> method allows us to search through the immediate children of these elements in the DOM tree and construct a new jQuery object from the matching elements. The <code>.find()</code> and <code>.children()</code> methods are similar, except that the latter only travels a single level down the DOM tree. Note also that like most jQuery methods, <code>.children()</code> does not return text nodes; to get <em>all</em> children including text and comment nodes, use <code>.contents()</code>.</p>
<p>The method optionally accepts a selector expression of the same type that we can pass to the <code>$()</code> function. If the selector is supplied, the elements will be filtered by testing whether they match it.</p>
<p>Consider a page with a basic nested list on it:</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 the level-2 list, we can find its children:</p>
<pre>$('ul.level-2').children().css('background-color', 'red');</pre>
<p>The result of this call is a red background behind items A, B, and C. Since we do not supply a selector expression, all of the children are part of the returned jQuery object. If we had supplied one, only the matching items among these three would be included.</p></longdesc>
                <example>
                    <desc>Find all children of the clicked element.</desc>
                    <code><![CDATA[

    $("#container").click(function (e) {
      $("*").removeClass("hilite");
      var $kids = $(e.target).children();
      var len = $kids.addClass("hilite").length;

      $("#results span:first").text(len);
      $("#results span:last").text(e.target.tagName);

      e.preventDefault();
      return false;
    });
]]></code>
                    <css><![CDATA[
  body { font-size:16px; font-weight:bolder; }
  div { width:130px; height:82px; margin:10px; float:left;
        border:1px solid blue; padding:4px; }
  #container { width:auto; height:105px; margin:0; float:none;
        border:none; }
  .hilite { border-color:red; }
  #results { display:block; color:red; }
  p { margin:10px; border:1px solid transparent; }
  span { color:blue; border:1px solid transparent; }
  input { width:100px; }
  em { border:1px solid transparent; }
  a { border:1px solid transparent; }
  b { border:1px solid transparent; }
  button { border:1px solid transparent; }
  ]]></css>
                    <html><![CDATA[<div id="container">

    <div>
      <p>This <span>is the <em>way</em> we</span> 
      write <em>the</em> demo,</p>

    </div>
    <div>
      <a href="#"><b>w</b>rit<b>e</b></a> the <span>demo,</span> <button>write 
      the</button> demo,
    </div>

    <div>
      This <span>the way we <em>write</em> the <em>demo</em> so</span>

      <input type="text" value="early" /> in
    </div>
    <p>
      <span>t</span>he <span>m</span>orning.
      <span id="results">Found <span>0</span> children in <span>TAG</span>.</span>

    </p>
  </div>]]></html>
                </example>
                <example>
                    <desc>Find all children of each div.</desc>
                    <code><![CDATA[$("div").children().css("border-bottom", "3px double red");]]></code>
                    <css><![CDATA[
  body { font-size:16px; font-weight:bolder; }
  span { color:blue; }
  p { margin:5px 0; }
  ]]></css>
                    <html><![CDATA[<p>Hello (this is a paragraph)</p>

  <div><span>Hello Again (this span is a child of the a div)</span></div>
  <p>And <span>Again</span> (in another paragraph)</p>

  <div>And One Last <span>Time</span> (most text directly in a div)</div>]]></html>
                </example>
                <example>
                    <desc>Find all children with a class "selected" of each div.</desc>
                    <code><![CDATA[$("div").children(".selected").css("color", "blue");]]></code>
                    <css><![CDATA[

  body { font-size:16px; font-weight:bolder; }
  p { margin:5px 0; }
  ]]></css>
                    <html><![CDATA[<div>
    <span>Hello</span>
    <p class="selected">Hello Again</p>
    <div class="selected">And Again</div>

    <p>And One Last Time</p>
  </div>]]></html>
                </example>
            <category name="Tree Traversal"/>
<category name="Version 1.0"/>
</entry>
<entry type='property' name="selector" return="String">
  <signature><added>1.3</added></signature>
  <desc>A selector representing selector originally passed to jQuery().</desc>
  <longdesc><p>Should be used in conjunction with context to determine the exact query used.</p>
    <p>The <code>.live()</code> method for binding event handlers uses this property to determine how to perform its searches. Plug-ins which perform similar tasks may also find the property useful. This property contains a string representing the matched set of elements, but if DOM traversal methods have been called on the object, the string may not be a valid jQuery selector expression. For this reason, the value of <code>.selector</code> is generally most useful immediately following the original creation of the object. Consequently, the <code>.live()</code> method should only be used in this scenario. </p></longdesc>
    <example>
      <desc>Determine the selector used.</desc>
      <code><![CDATA[$("ul")
  .append("<li>" + $("ul").selector + "</li>")
  .append("<li>" + $("ul li").selector + "</li>")
  .append("<li>" + $("div#foo ul:not([class])").selector + "</li>");

]]></code>
  <css><![CDATA[
  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  ]]></css>
  <html><![CDATA[Some selectors:<ul></ul>]]></html>
  </example>
                
  <example>
    <desc>Collecting elements differently</desc>
    <code><![CDATA[
   $('<div>' + $('ul li.foo').selector + '</div>').appendTo('body');  // "ul li.foo"
   $('<div>' + $('ul').find('li').filter('.foo').selector + '</div>').appendTo('body'); // "ul li.filter(.foo)"
]]></code>
    <html><![CDATA[Some selectors:<ul></ul>
]]></html>
  </example>
<category name="Internals"/>
<category name="Properties of jQuery Object Instances"/>
<category name="Version 1.3"/>
</entry>
            <entry type='method' name="add" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match additional elements against.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.0</added>
                <argument name="elements" type="Elements">
                    <desc>one or more elements to add to the set of matched elements.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.0</added>
                <argument name="html" type="HTML">
                    <desc>An HTML fragment to add to the set of matched elements.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.4</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match additional elements against.</desc>
                </argument>
                <argument name="context" type="Element">
                    <desc>Add some elements rooted against the specified context.</desc>
                </argument>
              </signature>
              <desc>Add elements to the set of matched elements.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.add()</code> method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to <code>.add()</code> can be pretty much anything that  <code>$()</code> accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.</p>
<p>Consider a page with a simple list and a paragraph following it:</p>
<pre>&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;a paragraph&lt;/p&gt;</pre>
<p>We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the <code>.add()</code> method's argument:</p>
<pre>$('li').add('p').css('background-color', 'red');</pre>
<p>Or:</p>
<pre>$('li').add(document.getElementsByTagName('p')[0])
  .css('background-color', 'red');</pre>
<p>The result of this call is a red background behind all four elements.
Using an HTML snippet as the <code>.add()</code> method's argument (as in the third version), we can create additional elements on the fly and add those elements to the matched set of elements. Let's say, for example, that we want to alter the background of the list items along with a newly created paragraph:</p>
<pre>$('li').add('&lt;p id="new"&gt;new paragraph&lt;/p&gt;')
  .css('background-color', 'red');</pre>
<p>Although the new paragraph has been created and its background color changed, it still does not appear on the page. To place it on the page, we could add one of the insertion methods to the chain.</p>
<p>As of jQuery 1.4 the results from .add() will always be returned in document order (rather than a simple concatenation).</p>
</longdesc>
<example>
	<desc>Finds all divs and makes a border.  Then adds all paragraphs to the jQuery object to set their backgrounds yellow.</desc>
	<code><![CDATA[

$("div").css("border", "2px solid red")
        .add("p")
        .css("background", "yellow");
]]></code>
	<css><![CDATA[
 div { width:60px; height:60px; margin:10px; float:left; }
 p { clear:left; font-weight:bold; font-size:16px; 
     color:blue; margin:0 10px; padding:2px; }
 ]]></css>
<html><![CDATA[<div></div>

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <p>Added this... (notice no border)</p>]]></html>
</example>
<example>
	<desc>Adds more elements, matched by the given expression, to the set of matched elements.</desc>
	<code><![CDATA[$("p").add("span").css("background", "yellow");]]></code>
	<html><![CDATA[<p>Hello</p><span>Hello Again</span>]]></html>
</example>
<example>
	<desc>Adds more elements, created on the fly, to the set of matched elements.</desc>
	<code><![CDATA[$("p").clone().add("<span>Again</span>").appendTo(document.body);]]></code>
	<html><![CDATA[<p>Hello</p>]]></html>
</example>
<example>
	<desc>Adds one or more Elements to the set of matched elements.</desc>
	<code><![CDATA[$("p").add(document.getElementById("a")).css("background", "yellow");]]></code>
	<html><![CDATA[<p>Hello</p><span id="a">Hello Again</span>]]></html>
</example>
<example>
	<desc>Demonstrates how to add (or push) elements to an existing collection</desc>
	<code><![CDATA[var collection = $("p");
// capture the new collection
collection = collection.add(document.getElementById("a"));
collection.css("background", "yellow");]]></code>
	<html><![CDATA[<p>Hello</p><span id="a">Hello Again</span>]]></html>
</example>
<category name="Miscellaneous Traversing"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
    <entry type='property' name="context" return="Element">
                <signature><added>1.3</added></signature>
                <desc>The DOM node context originally passed to jQuery(); if none was passed then context will likely be the document.</desc>
                <longdesc><p>The <code>.live()</code> method for binding event handlers uses this property to determine the root element to use for its event delegation needs. Plug-ins which perform similar tasks may also find the property useful.</p><p>
The value of this property is typically equal to document, as this is the default context for jQuery objects if none is supplied. The context may differ if, for example, the object was created by searching within an <code>&lt;iframe&gt;</code> or XML document.</p></longdesc>
                <example>
                    <desc>Determine the exact context used.</desc>
                    <code><![CDATA[$("ul")
  .append("<li>" + $("ul").context + "</li>")
  .append("<li>" + $("ul", document.body).context.nodeName + "</li>");

]]></code>
                    <css><![CDATA[
  body { cursor:pointer; }
  div { width:50px; height:30px; margin:5px; float:left;
        background:green; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[Context:<ul></ul>]]></html>
                </example>
            <category name="Internals"/>
<category name="Properties of jQuery Object Instances"/>
<category name="Version 1.3"/>
</entry>
            <entry type='method' name="not" return="jQuery">
              <signature>
                <added>1.0</added>
                <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match elements against.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.0</added>
                <argument name="elements" type="Elements">
                    <desc>One or more DOM elements to remove from the matched set.</desc>
                </argument>
              </signature>
              <signature>
                <added>1.4</added>
                <argument name="function(index)" type="Function">
                    <desc>A function used as a test for each element in the set. <code>this</code> is the current DOM element.</desc>
                </argument>
              </signature>
              <desc>Remove elements from the set of matched elements.</desc>
                <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.not()</code> method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result.</p>
<p>Consider a page with a simple list on it:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can apply this method to the set of list items:</p>
<pre>$('li').not(':even').css('background-color', 'red');</pre>
<p>The result of this call is a red background for items 2 and 4, as they do not match the selector (recall that :even and :odd use 0-based indexing).</p>
<h4>Removing Specific Elements</h4>
<p>The second version of the <code>.not()</code> method allows us to remove elements from the matched set, assuming we have found those elements previously by some other means. For example, suppose our list had an id applied to one of its items:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li id="notli"&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can fetch the third list item using the native JavaScript <code>getElementById()</code> function, then remove it from a jQuery object:</p>
<pre>
$('li').not(document.getElementById('notli'))
  .css('background-color', 'red');
</pre>
<p>This statement changes the color of items 1, 2, 4, and 5. We could have accomplished the same thing with a simpler jQuery expression, but this technique can be useful when, for example, other libraries provide references to plain DOM nodes.</p>
<p>As of jQuery 1.4, the <code>.not()</code> method can take a function as its argument in the same way that <code>.filter()</code> does. Elements for which the function returns <code>true</code> are excluded from the filtered set; all other elements are included.</p></longdesc>
                <example>
                    <desc>Adds a border to divs that are not green or blue.</desc>
                    <code><![CDATA[
    $("div").not(".green, #blueone")
            .css("border-color", "red");

]]></code>
                    <css><![CDATA[
  div { width:50px; height:50px; margin:10px; float:left;
        background:yellow; border:2px solid white; }
  .green { background:#8f8; }
  .gray { background:#ccc; }
  #blueone { background:#99f; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div id="blueone"></div>
  <div></div>
  <div class="green"></div>

  <div class="green"></div>
  <div class="gray"></div>
  <div></div>]]></html>
                </example>
                <example>
                    <desc>Removes the element with the ID "selected" from the set of all paragraphs.</desc>
                    <code><![CDATA[$("p").not( $("#selected")[0] )]]></code>
                </example>
                <example>
                    <desc>Removes the element with the ID "selected" from the set of all paragraphs.</desc>
                    <code><![CDATA[$("p").not("#selected")]]></code>
                </example>
                <example>
                    <desc>Removes all elements that match "div p.selected" from the total set of all paragraphs.</desc>
                    <code><![CDATA[$("p").not($("div p.selected"))]]></code>
                </example>
            <category name="Filtering"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="outerWidth" return="Integer">
				<signature>
					<added>1.2.6</added>
					<argument name="includeMargin" optional="true" type="Boolean">
	                    <desc>A Boolean indicating whether to include the element's margin in the calculation.</desc>
	                </argument>
				</signature>
                <desc>Get the current computed width for the first element in the set of matched elements, including padding and border.</desc>
                <longdesc><p>Returns the width of the element, along with left and right padding, border, and optionally margin, in pixels.</p>
				<p>If <code>includeMargin</code> is omitted or <code>false</code>, the padding and border are included in the calculation; if <code>true</code>, the margin is also included.</p>
				<p>This method is not applicable to <code>window</code> and <code>document</code> objects; for these, use <code><a href='/width'>.width()</a></code> instead.</p>
				<p class="image"><img src="/images/0042_04_06.png"/></p></longdesc>
                <example>
                    <desc>Get the outerWidth of a paragraph.</desc>
                    <code><![CDATA[var p = $("p:first");
$("p:last").text( "outerWidth:" + p.outerWidth()+ " , outerWidth(true):" + p.outerWidth(true) );

]]></code>
                    <css><![CDATA[
  p { margin:10px;padding:5px;border:2px solid #666; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p><p></p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
            <entry type='method' name="outerHeight" return="Integer">
				<signature>
					<added>1.2.6</added>
					<argument name="includeMargin" optional="true" type="Boolean">
	                    <desc>A Boolean indicating whether to include the element's margin in the calculation.</desc>
	                </argument>
				</signature>
                <desc>Get the current computed height for the first element in the set of matched elements, including padding, border, and optionally margin.</desc>
                <longdesc><p>The top and bottom padding and border are always included in the <code>.outerHeight()</code> calculation; if the <code>includeMargin</code> argument is set to <code>true</code>, the margin (top and bottom) is also included.</p>
				<p>This method is not applicable to <code>window</code> and <code>document</code> objects; for these, use <code><a href='/height'>.height()</a></code> instead.</p>
				<p class="image"><img src="/images/0042_04_03.png"/></p></longdesc>
                <example>
                    <desc>Get the outerHeight of a paragraph.</desc>
                    <code><![CDATA[var p = $("p:first");
$("p:last").text( "outerHeight:" + p.outerHeight() + " , outerHeight(true):" + p.outerHeight(true) );]]></code>
                    <css><![CDATA[p { margin:10px;padding:5px;border:2px solid #666; } ]]></css>
                    <html><![CDATA[<p>Hello</p><p></p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
<entry type='method' name="toggle" return="jQuery">
  <desc>Display or hide the matched elements.</desc>
<signature>
  <added>1.0</added>
  <argument name="duration" type="String,Number" optional="true">
    <desc>A string or number determining how long the animation will run.</desc>
  </argument>
  <argument name="callback" type="Callback" optional="true">
    <desc>A function to call once the animation is complete.</desc>
  </argument>
</signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>

<signature>
  <added>1.3</added>
  <argument name="showOrHide" type="Boolean">
    <desc>A Boolean indicating whether to show or hide the elements.</desc>
  </argument>
</signature>

<longdesc><p>With no parameters, the <code>.toggle()</code> method simply toggles the visibility of elements:</p>
<pre>$('.target').toggle();
</pre>
<p>The matched elements will be revealed or hidden immediately, with no animation, by changing the CSS <code>display</code> property. If the element is initially displayed, it will be hidden; if hidden, it will be shown. The <code>display</code> property is saved and restored as needed. If an element has a <code>display</code> value of <code>inline</code>, then is hidden and shown, it will once again be displayed <code>inline</code>.</p>
<p>When a duration is provided, <code>.toggle()</code> becomes an animation method. The <code>.toggle()</code> method animates the width, height, and opacity of the matched elements simultaneously. When these properties reach 0 after a hiding animation, the <code>display</code> style property is set to <code>none</code> to ensure that the element no longer affects the layout of the page.</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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
<blockquote><p>Note: The event handling suite also has a method named <a href="http://api.jquery.com/toggle-event/">.toggle()</a>. Which one is fired depends on the set of arguments passed.</p></blockquote>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
<p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
<p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;
</pre>
<p>We will cause <code>.toggle()</code> to be called when another element is clicked:</p>
<pre>$('#clickme').click(function() {
  $('#book').toggle('slow', function() {
    // Animation complete.
  });
});
</pre>
<p>With the element initially shown, we can hide it slowly with the first click:
</p>
<p class="image four-across"> 
<img src="/images/0042_06_09.png" alt="" />
<img src="/images/0042_06_10.png" alt="" />
<img src="/images/0042_06_11.png" alt="" />
<img src="/images/0042_06_12.png" alt="" />
</p>
<p>A second click will show the element once again:</p>
<p class="image four-across"><img src="/images/0042_06_13.png" alt="" />
<img src="/images/0042_06_14.png" alt="" />
<img src="/images/0042_06_15.png" alt="" />
<img src="/images/0042_06_16.png" alt="" />
</p>
<p>The second version of the method accepts a Boolean parameter. If this parameter is <code>true</code>, then the matched elements are shown; if <code>false</code>, the elements are hidden. In essence, the statement:
</p>
<pre>$('#foo').toggle(showOrHide);</pre>
<p>is equivalent to:</p>
<pre>if (showOrHide) {
  $('#foo').show();
} else {
  $('#foo').hide();
}
</pre></longdesc>
  <example>
      <desc>Toggles all paragraphs.</desc>
      <code><![CDATA[

$("button").click(function () {
$("p").toggle();
});
]]></code>
      <html><![CDATA[<button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>]]></html>
  </example>
  
  <example>
      <desc>Animates all paragraphs to be shown if they are hidden and hidden if they are visible, completing the animation within 600 milliseconds.</desc>
      <code><![CDATA[
$("button").click(function () {
$("p").toggle("slow");
});    
]]></code>
      <css><![CDATA[
p { background:#dad;
font-weight:bold;
font-size:16px; }
]]></css>
      <html><![CDATA[<button>Toggle 'em</button>

<p>Hiya</p>
<p>Such interesting text, eh?</p>]]></html>
  </example>
  
  <example>
      <desc>Shows all paragraphs, then hides them all, back and forth.</desc>
      <code><![CDATA[

var flip = 0;
$("button").click(function () {
$("p").toggle( flip++ % 2 == 0 );
});
]]></code>
      <html><![CDATA[<button>Toggle</button>
<p>Hello</p>
<p style="display: none">Good Bye</p>]]></html>
  </example>
 
<category name="Basics"/>
<category name="Version 1.0"/>
<category name="Version 1.3"/>
<category name="Version 1.4.3"/>
</entry>
            <entry type='method' name="innerWidth" return="Integer">
				<signature>
					<added>1.2.6</added>
				</signature>
                <desc>Get the current computed width for the first element in the set of matched elements, including padding but not border.</desc>
                <longdesc><p>This method returns the width of the element, including left and right padding, in pixels.</p>
<p>This method is not applicable to <code>window</code> and <code>document</code> objects; for these, use <code><a href='/width'>.width()</a></code> instead.</p>
<p class="image"><img src="/images/0042_04_05.png"/></p></longdesc>
                <example>
                    <desc>Get the innerWidth of a paragraph.</desc>
                    <code><![CDATA[var p = $("p:first");
$("p:last").text( "innerWidth:" + p.innerWidth() );]]></code>
                    <css><![CDATA[p { margin:10px;padding:5px;border:2px solid #666; } ]]></css>
                    <html><![CDATA[<p>Hello</p><p></p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
            <entry type='method' name="innerHeight" return="Integer">
				<signature>
					<added>1.2.6</added>
				</signature>
                <desc>Get the current computed height for the first element in the set of matched elements, including padding but not border.</desc>
                <longdesc><p>This method returns the height of the element, including top and bottom padding, in pixels.</p>
<p>This method is not applicable to <code>window</code> and <code>document</code> objects; for these, use <code><a href='/height'>.height()</a></code> instead.</p>
<p class="image"><img src="/images/0042_04_02.png"/></p></longdesc>
                <example>
                    <desc>Get the innerHeight of a paragraph.</desc>
                    <code><![CDATA[var p = $("p:first");
$("p:last").text( "innerHeight:" + p.innerHeight() );]]></code>
                    <css><![CDATA[p { margin:10px;padding:5px;border:2px solid #666; }]]></css>
                    <html><![CDATA[<p>Hello</p><p></p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
<entry type='method' name="jQuery.param" return="String">
  <signature>
    <added>1.2</added>
    <argument name="obj" type="Array, Object">
        <desc>An array or object to serialize.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="obj" type="Array, Object">
        <desc>An array or object to serialize.</desc>
    </argument>
    <argument name="traditional" type="Boolean">
        <desc>A Boolean indicating whether to perform a traditional "shallow" serialization.</desc>
    </argument>
  </signature>
  <desc>Create a serialized representation of an array or object, suitable for use in a URL query string or Ajax request. </desc>
  <longdesc>
    <p>This function is used internally to convert form element values into a serialized string representation (See <a href="/serialize/">.serialize()</a> for more information).</p>

    <p>As of jQuery 1.3, the return value of a function is used instead of the function as a String.</p>

    <p>As of jQuery 1.4, the <code>$.param()</code> method serializes deep objects recursively to accommodate modern scripting languages and frameworks such as PHP and Ruby on Rails. You can disable this functionality globally by setting <code>jQuery.ajaxSettings.traditional = true;</code>.</p>
<p>If the object passed is in an Array, it must be an array of objects in the format returned by <a href="/serializeArray/">.serializeArray()</a></p> 
<pre>[{name:"first",value:"Rick"},
{name:"last",value:"Astley"},
{name:"job",value:"Rock Star"}]</pre>
    <p>Note: Because some frameworks have limited ability to parse serialized arrays, we should exercise caution when passing an <code>obj</code> argument that contains objects or arrays nested within another array.</p>
<p>In jQuery 1.4 HTML5 input elements are serialized, as well.</p>
    <p>We can display a query string representation of an object and a URI-decoded version of the same as follows:</p>
<pre>var myObject = {
  a: {
    one: 1, 
    two: 2, 
    three: 3
  }, 
  b: [1,2,3]
};
var recursiveEncoded = $.param(myObject);
var recursiveDecoded = decodeURIComponent($.param(myObject));

alert(recursiveEncoded);
alert(recursiveDecoded);
</pre>
  <p>The values of <code>recursiveEncoded</code> and <code>recursiveDecoded</code> are alerted as follows:</p>
<p><span class="output">a%5Bone%5D=1&amp;a%5Btwo%5D=2&amp;a%5Bthree%5D=3&amp;b%5B%5D=1&amp;b%5B%5D=2&amp;b%5B%5D=3</span><br />
<span class="output">a[one]=1&amp;a[two]=2&amp;a[three]=3&amp;b[]=1&amp;b[]=2&amp;b[]=3</span></p>
    <p>To emulate the behavior of <code>$.param()</code> prior to jQuery 1.4, we can set the <code>traditional</code> argument to <code>true</code>:</p>
<pre>var myObject = {
  a: {
    one: 1, 
    two: 2, 
    three: 3
  }, 
  b: [1,2,3]
};
var shallowEncoded = $.param(myObject, true);
var shallowDecoded = decodeURIComponent(shallowEncoded);

alert(shallowEncoded);
alert(shallowDecoded);
</pre>
<p>The values of <code>shallowEncoded</code> and <code>shallowDecoded</code> are alerted as follows:</p>
<p><span class="output">a=%5Bobject+Object%5D&amp;b=1&amp;b=2&amp;b=3</span><br />
<span class="output">a=[object+Object]&amp;b=1&amp;b=2&amp;b=3</span></p>
  </longdesc>
                <example>
                    <desc>Serialize a key/value object.</desc>
                    <code><![CDATA[

    var params = { width:1680, height:1050 };
    var str = jQuery.param(params);
    $("#results").text(str);
]]></code>
                    <css><![CDATA[div { color:red; }]]></css>
                    <html><![CDATA[<div id="results"></div>]]></html>
                </example>
                   <example>
                    <desc>Serialize a few complex objects</desc>
                    <code><![CDATA[
// <=1.3.2: 
$.param({ a: [2,3,4] }) // "a=2&a=3&a=4"
// >=1.4:
$.param({ a: [2,3,4] }) // "a[]=2&a[]=3&a[]=4"

// <=1.3.2: 
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a=[object+Object]&d=3&d=4&d=[object+Object]"
// >=1.4: 
$.param({ a: { b:1,c:2 }, d: [3,4,{ e:5 }] }) // "a[b]=1&a[c]=2&d[]=3&d[]=4&d[2][e]=5"

]]></code>
                    <css><![CDATA[div { color:red; }]]></css>
                </example>
                
            <category name="Collection Manipulation"/>
<category name="Forms"/>
<category name="Helper Functions"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="hide" return="jQuery">
  <desc>Hide the matched elements.</desc>
<signature>
  <added>1.0</added>
</signature>
<signature>
  <added>1.0</added>
  <argument name="duration" type="String,Number">
    <desc>A string or number determining how long the animation will run.</desc>
  </argument>
  <argument name="callback" type="Callback" optional="true">
    <desc>A function to call once the animation is complete.</desc>
  </argument>
</signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
<longdesc>
<p>With no parameters, the <code>.hide()</code> method is the simplest way to hide an element:</p>
<pre>$('.target').hide();
</pre>
<p>The matched elements will be hidden immediately, with no animation. This is roughly equivalent to calling <code>.css('display', 'none')</code>, except that the value of the <code>display</code> property is saved in jQuery's data cache so that <code>display</code> can later be restored to its initial value. If an element has a <code>display</code> value of <code>inline</code>, then is hidden and shown, it will once again be displayed <code>inline</code>.</p>
<p>When a duration is provided, <code>.hide()</code> becomes an animation method. The <code>.hide()</code> method animates the width, height, and opacity of the matched elements simultaneously. When these properties reach 0, the <code>display</code> style property is set to <code>none</code> to ensure that the element no longer affects the layout of the page.</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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
<p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
<p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;
With the element initially shown, we can hide it slowly:
$('#clickme').click(function() {
  $('#book').hide('slow', function() {
    alert('Animation complete.');
  });
});</pre>

<p class="image four-across"> 
  <img src="/images/0042_06_05.png" alt="" /> 
  <img src="/images/0042_06_06.png" alt="" />
  <img src="/images/0042_06_07.png" alt="" />
  <img src="/images/0042_06_08.png" alt="" />
</p>

</longdesc>
                <example>
                    <desc>Hides all paragraphs then the link on click.</desc>
                    <code><![CDATA[

    $("p").hide();
    $("a").click(function () {
      $(this).hide();
      return true;
    });
]]></code>
                    <html><![CDATA[<p>Hello</p>
  <a href="#">Click to hide me too</a>
  <p>Here is another paragraph</p>]]></html>
                </example>
                <example>
                    <desc>Animates all shown paragraphs to hide slowly, completing the animation within 600 milliseconds.</desc>
                    <code><![CDATA[
    $("button").click(function () {
      $("p").hide("slow");
    });    
]]></code>
                    <css><![CDATA[
  p { background:#dad; font-weight:bold; }
  ]]></css>
                    <html><![CDATA[<button>Hide 'em</button>

  <p>Hiya</p>
  <p>Such interesting text, eh?</p>]]></html>
                </example>
                <example>
                    <desc>Animates all spans (words in this case) to hide fastly, completing each animation within 200 milliseconds. Once each animation is done, it starts the next one.</desc>
                    <code><![CDATA[
    $("#hidr").click(function () {
      $("span:last-child").hide("fast", function () {
        // use callee so don't have to name the function
        $(this).prev().hide("fast", arguments.callee); 
      });
    });
    $("#showr").click(function () {
      $("span").show(2000);
    });

]]></code>
                    <css><![CDATA[
  span { background:#def3ca; padding:3px; float:left; }
  ]]></css>
                    <html><![CDATA[<button id="hidr">Hide</button>
  <button id="showr">Show</button>
  <div>

    <span>Once</span> <span>upon</span> <span>a</span> 
    <span>time</span> <span>there</span> <span>were</span> 
    <span>three</span> <span>programmers...</span>

  </div>]]></html>
                </example>
                <example>
                    <desc>Hides the divs when clicked over 2 seconds, then removes the div element when its hidden.  Try clicking on more than one box at a time.</desc>
                    <code><![CDATA[
    for (var i = 0; i < 5; i++) {
      $("<div>").appendTo(document.body);
    }
    $("div").click(function () {
      $(this).hide(2000, function () {
        $(this).remove();
      });
    });
]]></code>
                    <css><![CDATA[
  div { background:#ece023; width:30px; 
        height:40px; margin:2px; float:left; }
  ]]></css>
                    <html><![CDATA[<div></div>]]></html>
                </example>
<category name="Basics"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>


            <entry type='method' name="width" return="Integer">
				<signature>
                	<added>1.0</added>
				</signature>
                <desc>Get the current computed width for the first element in the set of matched elements.</desc>
                <longdesc><p>The difference between <code>.css(width)</code> and <code>.width()</code> is that the latter returns a unit-less pixel value (for example, <code>400</code>) while the former returns a value with units intact (for example, <code>400px</code>). The <code>.width()</code> method is recommended when an element's width needs to be used in a mathematical calculation.</p>
<p class="image"><img src="/images/0042_04_04.png"/></p>
<p>This method is also able to find the width of the window and document.</p>

<pre>$(window).width();   // returns width of browser viewport
$(document).width(); // returns width of HTML document</pre>

<p>Note that <code>.width()</code> will always return the content width, regardless of the value of the CSS <code>box-sizing</code> property.</p></longdesc>
                <example>
                    <desc>Show various widths.  Note the values are from the iframe so might be smaller than you expected.  The yellow highlight shows the iframe body.</desc>
                    <code><![CDATA[
    function showWidth(ele, w) {
      $("div").text("The width for the " + ele + 
                    " is " + w + "px.");
    }
    $("#getp").click(function () { 
      showWidth("paragraph", $("p").width()); 
    });
    $("#getd").click(function () { 
      showWidth("document", $(document).width()); 
    });
    $("#getw").click(function () { 
      showWidth("window", $(window).width()); 
    });

]]></code>
                    <css><![CDATA[
  body { background:yellow; }
  button { font-size:12px; margin:2px; }
  p { width:150px; border:1px red solid; }
  div { color:red; font-weight:bold;  }
  ]]></css>
                    <html><![CDATA[<button id="getp">Get Paragraph Width</button>
  <button id="getd">Get Document Width</button>
  <button id="getw">Get Window Width</button>

  <div>&nbsp;</div>
  <p>
    Sample paragraph to test width
  </p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4.1"/>
</entry>
            <entry type='method' name="width" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="value" type="String, Number">
	                    <desc>An integer representing the number of pixels, or an integer along with an optional unit of measure appended (as a string).</desc>
	                </argument>
				</signature>
    <signature>
      <added>1.4.1</added>
      <argument name="function(index, width)" type="Function">
        <desc>A function returning the width to set. Receives the index position of the element in the set and the old width as arguments.</desc>
      </argument>
    </signature>
                <desc>Set the CSS width of each element in the set of matched elements.</desc>
                <longdesc><p>When calling <code>.width('value')</code>, the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, any valid CSS measurement may be used for the width (such as <code>100px</code>, <code>50%</code>, or <code>auto</code>). Note that in modern browsers, the CSS width property does not include padding, border, or margin, unless the <code>box-sizing</code> CSS property is used.</p>

<p>If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.</p>

<p>Note that <code>.width('value')</code> sets the width of the box in accordance with the CSS <code>box-sizing</code> property. Changing this property to <code>border-box</code> will cause this function to change the outerWidth of the box instead of the content width.</p></longdesc>
                <example>
                    <desc>To set the width of each div on click to 30px plus a color change.</desc>
                    <code><![CDATA[

    $("div").one('click', function () {
      $(this).width(30)
             .css({cursor:"auto", "background-color":"blue"});
    });
]]></code>
                    <css><![CDATA[
  div { width:70px; height:50px; float:left; margin:5px;
        background:red; cursor:pointer; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div>d</div>

  <div>d</div>
  <div>d</div>
  <div>d</div>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4.1"/>
</entry>


            <entry type='method' name="height" return="Integer">
				<signature>
                	<added>1.0</added>
				</signature>
                <desc>Get the current computed height for the first element in the set of matched elements.</desc>
                <longdesc><p>The difference between <code>.css('height')</code> and <code>.height()</code> is that the latter returns a unit-less pixel value (for example, <code>400</code>) while the former returns a value with units intact (for example, <code>400px</code>). The <code>.height()</code> method is recommended when an element's height needs to be used in a mathematical calculation.</p>
<p class="image"><img src='/images/0042_04_01.png'/></p>

<p>This method is also able to find the height of the window and document.</p>

<pre>$(window).height();   // returns height of browser viewport
$(document).height(); // returns height of HTML document</pre>

<p>Note that <code>.height()</code> will always return the content height, regardless of the value of the CSS <code>box-sizing</code> property.</p></longdesc>
                <example>
                    <desc>Show various heights.  Note the values are from the iframe so might be smaller than you expected.  The yellow highlight shows the iframe body.</desc>
                    <code><![CDATA[
    function showHeight(ele, h) {
      $("div").text("The height for the " + ele + 
                    " is " + h + "px.");
    }
    $("#getp").click(function () { 
      showHeight("paragraph", $("p").height()); 
    });
    $("#getd").click(function () { 
      showHeight("document", $(document).height()); 
    });
    $("#getw").click(function () { 
      showHeight("window", $(window).height()); 
    });

]]></code>
                    <css><![CDATA[
  body { background:yellow; }
  button { font-size:12px; margin:2px; }
  p { width:150px; border:1px red solid; }
  div { color:red; font-weight:bold; }
  ]]></css>
                    <html><![CDATA[<button id="getp">Get Paragraph Height</button>
  <button id="getd">Get Document Height</button>
  <button id="getw">Get Window Height</button>

  <div>&nbsp;</div>
  <p>
    Sample paragraph to test height
  </p>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4.1"/>
</entry>
            <entry type='method' name="height" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="value" type="String, Number">
	                    <desc>An integer representing the number of pixels, or an integer with an optional unit of measure appended (as a string).</desc>
	                </argument>
				</signature>
    <signature>
      <added>1.4.1</added>
      <argument name="function(index, height)" type="Function">
        <desc>A function returning the height to set. Receives the index position of the element in the set and the old height as arguments.</desc>
      </argument>
    </signature>
                <desc>Set the CSS height of every matched element.</desc>
                <longdesc><p>When calling <code>.height(value)</code>, the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, any valid CSS measurement may be used for the height (such as <code>100px</code>, <code>50%</code>, or <code>auto</code>). Note that in modern browsers, the CSS height property does not include padding, border, or margin.</p>
<p>If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.</p>
<p>Note that <code>.height(value)</code> sets the height of the box in accordance with the CSS <code>box-sizing</code> property. Changing this property to <code>border-box</code> will cause this function to change the outerHeight of the box instead of the content height.</p></longdesc>

                <example>
                    <desc>To set the height of each div on click to 30px plus a color change.</desc>
                    <code><![CDATA[$("div").one('click', function () {
      $(this).height(30)
             .css({cursor:"auto", backgroundColor:"green"});
    });]]></code>
                    <css><![CDATA[div { width:50px; height:70px; float:left; margin:5px;
        background:rgb(255,140,0); cursor:pointer; }  ]]></css>
                    <html><![CDATA[<div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>]]></html>
                </example>
            <category name="CSS"/>
<category name="Dimensions"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4.1"/>
</entry>

<entry type='method' name="show" return="jQuery">
  <desc>Display the matched elements.</desc>  
<signature>
  <added>1.0</added>
</signature>
<signature>
  <added>1.0</added>
  <argument name="duration" type="String,Number">
    <desc>A string or number determining how long the animation will run.</desc>
  </argument>
  <argument name="callback" type="Callback" optional="true">
    <desc>A function to call once the animation is complete.</desc>
  </argument>  
</signature>
  <signature>
    <added>1.4.3</added>
    <argument name="duration" type="String,Number" optional="true">
      <desc>A string or number determining how long the animation will run.</desc>
    </argument>
    <argument name="easing" type="String" optional="true">
      <desc>A string indicating which easing function to use for the transition.</desc>
    </argument>
    <argument name="callback" type="Callback" optional="true">
      <desc>A function to call once the animation is complete.</desc>
    </argument>
  </signature>
<longdesc>
<p>With no parameters, the <code>.show()</code> method is the simplest way to display an element:
</p>
<pre>$('.target').show();
</pre>
<p>The matched elements will be revealed immediately, with no animation. This is roughly equivalent to calling <code>.css('display', 'block')</code>, except that the <code>display</code> property is restored to whatever it was initially. If an element has a <code>display</code> value of <code>inline</code>, then is hidden and shown, it will once again be displayed <code>inline</code>.</p>
<p>When a duration is provided, <code>.show()</code> becomes an animation method. The <code>.show()</code> method animates the width, height, and opacity of the matched elements simultaneously.</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 <code>200</code> and <code>600</code> milliseconds, respectively.</p>
    <p>As of jQuery 1.4.3, an optional string naming an easing function may be used. Easing functions specify the speed at which the animation progresses at different points within the animation. The only easing implementations in the jQuery library are the default, called <code>swing</code>, and one that progresses at a constant pace, called <code>linear</code>. More easing functions are available with the use of plug-ins, most notably the <a href="http://jqueryui.com">jQuery UI suite</a>.</p>
<p>If supplied, the callback is fired once the animation is complete. This can be useful for stringing different animations together in sequence. The callback is not sent any arguments, but <code>this</code> is set to the DOM element being animated. If multiple elements are animated, it is important to note that the callback is executed once per matched element, not once for the animation as a whole.</p>
<p>We can animate any element, such as a simple image:</p>
<pre>&lt;div id="clickme"&gt;
  Click here
&lt;/div&gt;
&lt;img id="book" src="book.png" alt="" width="100" height="123" /&gt;
With the element initially hidden, we can show it slowly:
$('#clickme').click(function() {
  $('#book').show('slow', function() {
    // Animation complete.
  });
});</pre>
<p class="image four-across">
  <img src="/images/0042_06_01.png" alt="" />
  <img src="/images/0042_06_02.png" alt="" />
  <img src="/images/0042_06_03.png" alt="" />
  <img src="/images/0042_06_04.png" alt="" />
</p>

</longdesc>
<example>
  <desc>Animates all hidden paragraphs to show slowly, completing the animation within 600 milliseconds.</desc>
  <code><![CDATA[
    $("button").click(function () {
    $("p").show("slow");
    });
    ]]></code>
    <css><![CDATA[
      p { background:yellow; }
      ]]></css>
      <html><![CDATA[<button>Show it</button>

      <p style="display: none">Hello  2</p>]]></html>
    </example>
    <example>
      <desc>Animates all hidden divs to show fastly in order, completing each animation within 200 milliseconds. Once each animation is done, it starts the next one.</desc>
      <code><![CDATA[
$("#showr").click(function () {
  $("div:eq(0)").show("fast", function () {
    /* use callee so don't have to name the function */
    $(this).next("div").show("fast", arguments.callee);
  });
});
$("#hidr").click(function () {
  $("div").hide(2000);
});

]]></code>
<css><![CDATA[
  div { background:#def3ca; margin:3px; width:80px; 
  display:none; float:left; text-align:center; }
  ]]></css>
  <html><![CDATA[
  <button id="showr">Show</button>
  <button id="hidr">Hide</button>
  <div>Hello 3,</div>

  <div>how</div>
  <div>are</div>
  <div>you?</div>]]></html>
</example>
<example>
  <desc>Shows all span and input elements with an animation. Once the animation is done, it changes the text.</desc>
  <code><![CDATA[
function doIt() {
  $("span,div").show("slow");
}
/* can pass in function name */
$("button").click(doIt);

$("form").submit(function () {
  if ($("input").val() == "yes") {
    $("p").show(4000, function () {
      $(this).text("Ok, DONE! (now showing)");
    });
  }
  $("span,div").hide("fast");
  /* to stop the submit */
  return false; 
});
]]></code>
<css><![CDATA[
  span { display:none; }
  div { display:none; }
  p { font-weight:bold; background-color:#fcd; }
  ]]></css>
  <html><![CDATA[<button>Do it!</button>
  <span>Are you sure? (type 'yes' if you are) </span>
  <div>
    <form>
      <input type="text"  value="as;ldkfjalsdf"/>
    </form>
  </div>
  <p style="display:none;">I'm hidden...</p>
  ]]></html>
</example>

<category name="Basics"/>
<category name="Version 1.0"/>
<category name="Version 1.4.3"/>
</entry>

<entry type='method' name="scrollLeft" return="Integer">
  <signature>
    <added>1.2.6</added>
  </signature>
  <desc>Get the current horizontal position of the scroll bar for the first element in the set of matched elements.</desc>
  <longdesc><p>The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very left, or if the element is not scrollable, this number will be <code>0</code>.</p></longdesc>
  <example>
    <desc>Get the scrollLeft of a paragraph.</desc>
    <code><![CDATA[var p = $("p:first");
			$("p:last").text( "scrollLeft:" + p.scrollLeft() );

			]]></code>
      <css><![CDATA[
    p { margin:10px;padding:5px;border:2px solid #666; }
    ]]></css>
    <html><![CDATA[<p>Hello</p><p></p>]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
<entry type='method' name="scrollLeft" return="jQuery">
  <signature>
    <added>1.2.6</added>
    <argument name="value" type="Number">
      <desc>An integer indicating the new position to set the scroll bar to.</desc>
    </argument>
  </signature>
  <desc>Set the current horizontal position of the scroll bar for each of the set of matched elements.</desc>
  <longdesc><p>The horizontal scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the <code>scrollLeft</code> positions the horizontal scroll of each matched element.</p></longdesc>
  <example>
    <desc>Set the scrollLeft of a div.</desc>
    <code><![CDATA[$("div.demo").scrollLeft(300);
]]></code>
<css><![CDATA[
  div.demo {
  background:#CCCCCC none repeat scroll 0 0;
  border:3px solid #666666;
  margin:5px;
  padding:5px;
  position:relative;
  width:200px;
  height:100px;
  overflow:auto;
  }
  p { margin:10px;padding:5px;border:2px solid #666;width:1000px;height:1000px; }
	]]></css>
  <html><![CDATA[<div class="demo"><h1>lalala</h1><p>Hello</p></div>]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>

<entry type='method' name="jQuery.trim" return="String">
  <signature>
    <added>1.0</added>
    <argument name="str" type="String">
      <desc>The string to trim.</desc>
    </argument>
  </signature>
  <desc>Remove the whitespace from the beginning and end of a string.</desc>
  <longdesc>
    <p>The <code>$.trim()</code> function removes all newlines, spaces (including non-breaking spaces), and tabs from the beginning and end of the supplied string. If these whitespace characters occur in the middle of the string, they are preserved.</p>
  </longdesc>
  
  <example>
      <desc>Remove the two white spaces at the start and at the end of the string.</desc>
      <code><![CDATA[

$("button").click(function () {
var str = "     lots of spaces before and after     ";
alert("'" + str + "'");

str = jQuery.trim(str);
alert("'" + str + "' - no longer");
});

]]></code>
      <html><![CDATA[<button>Show Trim Example</button>]]></html>
  </example>
  <example>
      <desc>Remove the two white spaces at the start and at the end of the string.</desc>
      <code><![CDATA[$.trim("  hello, how are you?  ");]]></code>
      <results><![CDATA["hello, how are you?"]]></results>
  </example>
<category name="Utilities"/>
<category name="Version 1.0"/>
</entry>


 <entry type='method' name="jQuery.isFunction" return="boolean">
                <signature>
                   <added>1.2</added>
                   <argument name="obj" type="Object">
                       <desc>Object to test whether or not it is a function.</desc>
                    </argument>
                </signature>
                <desc>Determine if the argument passed is a Javascript function object. </desc>
                <longdesc><p><strong>Note:</strong> As of jQuery 1.3, functions provided by the browser like <code>alert()</code> and DOM element methods like <code>getAttribute()</code> are not guaranteed to be detected as functions in browsers such as Internet Explorer.</p></longdesc>
                <example>
                    <desc>Test a few parameter examples.</desc>
                    <code><![CDATA[
    function stub() {
    }
    var objs = [
          function () {},
          { x:15, y:20 },
          null,
          stub,
          "function"
        ];

    jQuery.each(objs, function (i) {
      var isFunc = jQuery.isFunction(objs[i]);
      $("span").eq(i).text(isFunc);
    });
]]></code>
                    <css><![CDATA[
  div { color:blue; margin:2px; font-size:14px; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[
  <div>jQuery.isFunction(objs[0]) = <span></span></div>

  <div>jQuery.isFunction(objs[1]) = <span></span></div>
  <div>jQuery.isFunction(objs[2]) = <span></span></div>
  <div>jQuery.isFunction(objs[3]) = <span></span></div>

  <div>jQuery.isFunction(objs[4]) = <span></span></div>
  ]]></html>
                </example>
                <example>
                    <desc>Finds out if the parameter is a funcion.</desc>
                    <code><![CDATA[$.isFunction(function(){});]]></code>
                    <results><![CDATA[true]]></results>
                </example>
            <category name="Utilities"/>
<category name="Version 1.2"/>
</entry>
  <entry type='method' name="jQuery.isArray" return="boolean">
                <signature>
                  <added>1.3</added>
                    <argument name="obj" type="Object">
                       <desc>Object to test whether or not it is an array.</desc>
                    </argument>
                </signature>
                <desc>Determine whether the argument is an array.</desc>
                <longdesc><p><code>$.isArray()</code> returns a Boolean indicating whether the object is a JavaScript array (not an array-like object, such as a jQuery object).</p></longdesc>
                <example>
                    <desc>Finds out if the parameter is an array.</desc>
                    <code><![CDATA[$("b").append( "" + $.isArray([]) );]]></code>
                    <html><![CDATA[Is [] an Array? <b></b>]]></html>
                </example>
            <category name="Utilities"/>
<category name="Version 1.3"/>
</entry>
            <entry type='method' name="jQuery.unique" return="Array">
                <signature>
                   <added>1.1.3</added>
                   <argument name="array" type="Array">
                     <desc>The Array of DOM elements.</desc>
                   </argument>
                </signature>
                <desc>Sorts an array of DOM elements, in place, with the duplicates removed. Note that this only works on arrays of DOM elements, not strings or numbers.</desc>
                <longdesc><p>The <code>$.unique()</code> function searches through an array of objects, sorting the array, and removing any duplicate nodes. This function only works on plain JavaScript arrays of DOM elements, and is chiefly used internally by jQuery.</p>
<p>As of jQuery 1.4 the results will always be returned in document order.</p></longdesc>
                <example>
                    <desc>Removes any duplicate elements from the array of divs.</desc>
                    <code><![CDATA[

    var divs = $("div").get(); // unique() must take a native array

    // add 3 elements of class dup too (they are divs)
    divs = divs.concat($(".dup").get());
    $("div:eq(1)").text("Pre-unique there are " + divs.length + " elements.");

    divs = jQuery.unique(divs);
    $("div:eq(2)").text("Post-unique there are " + divs.length + " elements.")
                  .css("color", "red");

]]></code>
                    <css><![CDATA[
  div { color:blue; }
  ]]></css>
                    <html><![CDATA[<div>There are 6 divs in this document.</div>
  <div></div>
  <div class="dup"></div>
  <div class="dup"></div>

  <div class="dup"></div>
  <div></div>]]></html>
                </example>
                
            <category name="Utilities"/>
<category name="Version 1.1.3"/>
</entry>
<entry type='method' name="jQuery.merge" return="Array">
  <desc>Merge the contents of two arrays together into the first array. </desc>
  <signature>
    <added>1.0</added>
    <argument name="first" type="Array">
      <desc>The first array to merge, the elements of second added.</desc>
    </argument>
    <argument name="second" type="Array">
      <desc>The second array to merge into the first, unaltered.</desc>
    </argument>
  </signature>
  <longdesc><p>The <code>$.merge()</code> operation forms an array that contains all elements from the two arrays. The orders of items in the arrays are preserved, with items from the second array appended. The <code>$.merge()</code> function is destructive. It alters the first parameter to add the items from the second.  </p>
    <p>If you need the original first array, make a copy of it before calling <code>$.merge()</code>. Fortunately, <code>$.merge()</code> itself can be used for this duplication:</p>
    <pre>var newArray = $.merge([], oldArray);</pre>
    <p>This shortcut creates a new, empty array and merges the contents of oldArray into it, effectively cloning the array.</p>
    <p>Prior to jQuery 1.4, the arguments should be true Javascript Array objects; use <code>$.makeArray</code> if they are not.</p></longdesc>

    <example>
      <desc>Merges two arrays, altering the first argument.</desc>
      <code><![CDATA[$.merge( [0,1,2], [2,3,4] )]]></code>
      <results><![CDATA[[0,1,2,2,3,4] ]]></results>
    </example>
    <example>
      <desc>Merges two arrays, altering the first argument.</desc>
      <code><![CDATA[$.merge( [3,2,1], [4,3,2] )  ]]></code>
      <results><![CDATA[[3,2,1,4,3,2] ]]></results>
    </example>
    <example>
      <desc>Merges two arrays, but uses a copy, so the original isn't altered.</desc>
      <code><![CDATA[var first = ['a','b','c'];
var second = ['d','e','f'];
$.merge( $.merge([],first), second);
      ]]></code>
    <results><![CDATA[["a","b","c","d","e","f"] ]]></results>
  </example>
<category name="Utilities"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.inArray" return="Number">
  <signature><added>1.2</added>
    <argument name="value" type="Any">
      <desc>The value to search for.</desc>
    </argument>
    <argument name="array" type="Array">
      <desc>An array through which to search.</desc>
    </argument>
  </signature>
<desc>Search for a specified value within an array and return its index (or -1 if not found).</desc>
  <longdesc><p>The <code>$.inArray()</code> method is similar to JavaScript's native <code>.indexOf()</code> method in that it returns -1 when it doesn't find a match. If the first element within the array matches <code>value</code>, <code>$.inArray()</code> returns 0.</p> 

    <p>Because JavaScript treats 0 as loosely equal to false (i.e. 0 == false, but 0 !== false), if we're checking for the presence of <code>value</code> within <code>array</code>, we need to check if it's not equal to (or greater than) -1.</p>
  </longdesc>
                
<example>
  <desc>Report the index of some elements in the array.</desc>
  <code><![CDATA[var arr = [ 4, "Pete", 8, "John" ];

$("span:eq(0)").text(jQuery.inArray("John", arr));
$("span:eq(1)").text(jQuery.inArray(4, arr));
$("span:eq(2)").text(jQuery.inArray("Karl", arr));

]]></code>
<css><![CDATA[
  div { color:blue; }
  span { color:red; }
]]></css>
<html><![CDATA[
<div>"John" found at <span></span></div>
<div>4 found at <span></span></div>
<div>"Karl" not found, so <span></span></div>]]></html>
  </example>
<category name="Utilities"/>
<category name="Version 1.2"/>
</entry>
<entry type='method' name="jQuery.map" return="Array">
  <signature>
    <added>1.0</added>
    <argument name="array" type="Array">
      <desc>The Array to translate.</desc>
    </argument>
    <argument name="callback(elementOfArray, indexInArray)" type="Function">
      <desc>The function to process each item against.  The first argument to the function is the list item, the second argument is the index in array The function can return any value.  <code>this</code> will be the global window object. </desc>
    </argument>
  </signature>
  <desc>Translate all items in an array or array-like object to another array of items.</desc>
  <longdesc><p>The $.map() method applies a function to each item in an array, collecting the results into a new array.</p> 
    <p>The translation function that is provided to this method is called for each item in the array and is passed two arguments: The item to be translated, and the index within the array.</p>

    <p>The function can return:</p>
    <ul>
      <li>the translated value, which will be mapped to the resulting array</li>
      <li><code>null</code>, to remove the item</li>
      <li>an array of values, which will be flattened into the full array</li>
    </ul>
    <p>Map can  iterate through Array-like objects, like a jQuery object, that have a length property.</p></longdesc>
      
      <example>
        <desc>A couple examples of using .map()</desc>
        <code><![CDATA[

    var arr = [ "a", "b", "c", "d", "e" ];
    $("div").text(arr.join(", "));

    arr = jQuery.map(arr, function(n, i){
      return (n.toUpperCase() + i);
    });
    $("p").text(arr.join(", "));

    arr = jQuery.map(arr, function (a) { return a + a; });
    $("span").text(arr.join(", "));

]]></code>
                    <css><![CDATA[
  div { color:blue; }
  p { color:green; margin:0; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <p></p>
  <span></span>
  ]]></html>
                </example>
                <example>
                    <desc>Maps the original array to a new one and adds 4 to each value.</desc>
                    <code><![CDATA[$.map( [0,1,2], function(n){
   return n + 4;
 });]]></code>
                    <results><![CDATA[[4, 5, 6] ]]></results>
                </example>
                <example>
                    <desc>Maps the original array to a new one and adds 1 to each value if it is bigger then zero, otherwise it's removed.</desc>
                    <code><![CDATA[$.map( [0,1,2], function(n){
   return n > 0 ? n + 1 : null;
 });]]></code>
                    <results><![CDATA[[2, 3] ]]></results>
                </example>
                <example>
                    <desc>Maps the original array to a new one, each element is added with it's original value and the value plus one.</desc>
                    <code><![CDATA[$.map( [0,1,2], function(n){
   return [ n, n + 1 ];
 });]]></code>
                    <results><![CDATA[[0, 1, 1, 2, 2, 3] ]]></results>
                </example>
                <example>
                    <desc>Maps the original array to a new one, each element is squared.</desc>
                    <code><![CDATA[$.map( [0,1,2,3], function (a) { return a * a; } );]]></code>
                    <results><![CDATA[[0, 1, 4, 9] ]]></results>
                </example>
                
                <example>
                    <desc>Remove items by returning <code>null</code> from the function. This removes any numbers less than 50, and the rest are decreased by 45.</desc>
                    <code><![CDATA[$.map( [0, 1, 52, 97], function (a) { return (a > 50 ? a - 45 : null); } );]]></code>
                    <results><![CDATA[[7, 52] ]]></results>
                </example>
                
                 
                <example>
                    <desc>Augmenting the resulting array by returning an array inside the function.</desc>
                    <code><![CDATA[var array = [0, 1, 52, 97];
array = $.map(array, function(a, index) {
  return [a - 45, index];
}); ]]></code>
                    <results><![CDATA[[-45, 0, -44, 1, 7, 2, 52, 3] ]]></results>
                </example>
                
            <category name="Utilities"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.makeArray" return="Array">
  <signature>
    <added>1.2</added>
    <argument name="obj" type="Object">
      <desc>Any object to turn into a native Array.</desc>
    </argument>
  </signature>
  <desc>Convert an array-like object into a true JavaScript array.</desc>
  <longdesc>
    <p>Many methods, both in jQuery and in JavaScript in general, return objects that are array-like. For example, the jQuery factory function <code>$()</code> returns a jQuery object that has many of the properties of an array (a length, the <code>[]</code> array access operator, etc.), but is not exactly the same as an array and lacks some of an array's built-in methods (such as <code>.pop()</code> and <code>.reverse()</code>).</p>

    <p>Note that after the conversion, any special features the object had (such as the jQuery methods in our example) will no longer be present. The object is now a plain array.</p></longdesc>
    <example>
      <desc>Turn a collection of HTMLElements into an Array of them.</desc>
      <code><![CDATA[
    var elems = document.getElementsByTagName("div"); // returns a nodeList
    var arr = jQuery.makeArray(elems);
    arr.reverse(); // use an Array method on list of dom elements
    $(arr).appendTo(document.body);
]]></code>
    <css><![CDATA[
  div { color:red; }
  ]]></css>
    <html><![CDATA[<div>First</div>
  <div>Second</div>  
  <div>Third</div>

  <div>Fourth</div>]]></html>
    </example>
    <example>
      <desc>Turn a jQuery object into an array</desc>
      <code><![CDATA[
    var obj = $('li');
    var arr = $.makeArray(obj);
]]></code>
    <results><![CDATA[(typeof obj === 'object' && obj.jquery) === true;
jQuery.isArray(arr) === true;]]>
    </results>
  </example>
<category name="Utilities"/>
<category name="Version 1.2"/>
</entry>
<entry type='method' name="jQuery.grep" return="Array">
  <desc>Finds the elements of an array which satisfy a filter function. The original array is not affected.</desc>
  <signature>
    <added>1.0</added>
    <argument name="array" type="Array">
      <desc>The array to search through.</desc>
    </argument>
    <argument name="function(elementOfArray, indexInArray)" type="Function">
      <desc>The function to process each item against.  The first argument to the function is the item, and the second argument is the index.  The function should return a Boolean value.  <code>this</code> will be the global window object.</desc>
    </argument>
    <argument name="invert" optional="true" type="Boolean">
      <desc>If "invert" is false, or not provided, then the function returns an array consisting of all elements for which "callback" returns true.  If "invert" is true, then the function returns an array consisting of all elements for which "callback" returns false.</desc>
    </argument>
  </signature>

  <longdesc><p>The <code>$.grep()</code> method removes items from an array as necessary so that all remaining items pass a provided test. The test is a function that is passed an array item and the index of the item within the array. Only if the test returns true will the item be in the result array.</p>

  <p> The filter function will be passed two arguments: the current array item and its index. The filter function must return 'true' to include the item in the result array.</p>
</longdesc>


<example>
  <desc>Filters the original array of numbers leaving that are not 5 and have an index greater than 4.  Then it removes all 9s.</desc>
  <code><![CDATA[
var arr = [ 1, 9, 3, 8, 6, 1, 5, 9, 4, 7, 3, 8, 6, 9, 1 ];
$("div").text(arr.join(", "));

arr = jQuery.grep(arr, function(n, i){
  return (n != 5 && i > 4);
});
$("p").text(arr.join(", "));

arr = jQuery.grep(arr, function (a) { return a != 9; });
$("span").text(arr.join(", "));

]]></code>
  <css><![CDATA[
  div { color:blue; }
  p { color:green; margin:0; }
  span { color:red; }
  ]]></css>
  <html><![CDATA[<div></div>
  <p></p>
  <span></span>
  ]]></html>
</example>
<example>
  <desc>Filter an array of numbers to include only numbers bigger then zero.</desc>
  <code><![CDATA[$.grep( [0,1,2], function(n,i){
   return n > 0;
 });]]></code>
 <results><![CDATA[[1, 2] ]]></results>
</example>
<example>
  <desc>Filter an array of numbers to include numbers that are not bigger than zero.</desc>
  <code><![CDATA[$.grep( [0,1,2], function(n,i){
    return n > 0;
},true);]]></code>
  <results><![CDATA[[0] ]]></results>
  </example>
<category name="Utilities"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.extend" return="Object">
  <signature>
    <added>1.0</added>
    <argument name="target" type="Object">
      <desc> An object that will receive the new properties if additional objects are passed in or that will extend the jQuery namespace if it is the sole argument.</desc>
    </argument>
    <argument name="object1" type="Object" optional="true">
      <desc>An object containing additional properties to merge in.</desc>
    </argument>
    <argument name="objectN" optional="true" type="Object">
      <desc>Additional objects containing properties to merge in.</desc>
    </argument>    
  </signature>
  <signature>
    <added>1.1.4</added>
    <argument name="deep" optional="true" type="Boolean">
      <desc>If true, the merge becomes recursive (aka. deep copy).</desc>
    </argument>
    <argument name="target" type="Object">
      <desc>The object to extend. It will receive the new properties.</desc>
    </argument>
    <argument name="object1" type="Object">
      <desc>An object containing additional properties to merge in.</desc>
    </argument>
    <argument name="objectN" optional="true" type="Object">
      <desc>Additional objects containing properties to merge in.</desc>
    </argument>    
  </signature>

  <desc>Merge the contents of two or more objects together into the first object.</desc>
  <longdesc><p>When we supply two or more objects to <code>$.extend()</code>, properties from all of the objects are added to the target object.</p>
  <p>If only one argument is supplied to <code>$.extend()</code>, this means the target argument was omitted. In this case, the jQuery object itself is assumed to be the target. By doing this, we can add new functions to the jQuery namespace.  This can be useful for plugin authors wishing to add new methods to JQuery.</p>
  <p>Keep in mind that the target object (first argument) will be modified, and will also be returned from <code>$.extend()</code>. If, however, we want to preserve both of the original objects, we can do so by passing an empty object as the target:</p>
  <pre>var object = $.extend({}, object1, object2);</pre>

  <p>The merge performed by <code>$.extend()</code> is not recursive by default; if a property of the first object is itself an object or array, it will be completely overwritten by a property with the same key in the second object. The values are not merged. This can be seen in the example below by examining the value of banana. However, by passing <code>true</code> for the first function argument, objects will be recursively merged.</p>
  <p>Undefined properties are not copied. However, properties inherited from the object's prototype <em>will</em> be copied over.</p>
  </longdesc>

  <example>
    <desc>Merge two objects, modifying the first.</desc>
    <code><![CDATA[
var object1 = {
  apple: 0,
  banana: {weight: 52, price: 100},
  cherry: 97
};
var object2 = {
  banana: {price: 200},
  durian: 100
};

$.extend(object1, object2);
]]></code>
  <results><![CDATA[object1 === {apple: 0, banana: {price: 200}, cherry: 97, durian: 100}]]></results>
  </example>

  <example>
    <desc>Merge two objects recursively, modifying the first.</desc>
    <code><![CDATA[
var object1 = {
  apple: 0,
  banana: {weight: 52, price: 100},
  cherry: 97
};
var object2 = {
  banana: {price: 200},
  lime: 100
};

$.extend(true, object1, object2);
]]></code>
    <results><![CDATA[object1 === {apple: 0, banana: {weight: 52, price: 200}, cherry: 97, lime: 100}]]></results>
  </example>


  <example>
    <desc>Merge settings and options, modifying settings.</desc>
    <code><![CDATA[var settings = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
jQuery.extend(settings, options);]]></code>
    <results><![CDATA[settings == { validate: true, limit: 5, name: "bar" }]]></results>
  </example>
  <example>
    <desc>Merge defaults and options, without modifying the defaults. This is a common plugin development pattern.</desc>
    <code><![CDATA[var empty = {}
var defaults = { validate: false, limit: 5, name: "foo" };
var options = { validate: true, name: "bar" };
var settings = $.extend(empty, defaults, options);]]></code>
    <results><![CDATA[settings == { validate: true, limit: 5, name: "bar" }
empty == { validate: true, limit: 5, name: "bar" }]]></results>
  </example>
<category name="Utilities"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="jQuery.each" return="Object">
  <signature>
    <added>1.0</added>
    <argument name="collection" type="Object">
      <desc>The object or array to iterate over.</desc>
    </argument>
    <argument name="callback(indexInArray, valueOfElement)" type="Function">
      <desc>The function that will be executed on every object.</desc>
    </argument>
  </signature>
  <desc>A generic iterator function, which can be used to seamlessly iterate over both objects and arrays. Arrays and array-like objects with a length property (such as a function's arguments object) are iterated by numeric index, from 0 to length-1. Other objects are iterated via their named properties.</desc>
  <longdesc>
    <p>The <code>$.each()</code> function is not the same as <a href="/each/">.each()</a>, which is used to iterate, exclusively, over a jQuery object. The <code>$.each()</code> function can be used to iterate over any collection, whether it is a map (JavaScript object) or an array. In the case of an array, the callback is passed an array index and a corresponding array value each time. (The value can also be accessed through the <code>this</code> keyword, but Javascript will always wrap the <code>this</code> value as an <code>Object</code> even if it is a simple string or number value.) The method returns its first argument, the object that was iterated.</p>

<pre>$.each([52, 97], function(index, value) { 
  alert(index + ': ' + value); 
});
</pre>
<p>This produces two messages:</p>
<p>
  <span class="output">0: 52</span><br />
  <span class="output">1: 97</span>
</p>
    <p>If a map is used as the collection, the callback is passed a key-value pair each time:</p>
<pre>var map = { 
  'flammable': 'inflammable', 
  'duh': 'no duh' 
}; 
$.each(map, function(key, value) { 
  alert(key + ': ' + value); 
});</pre>
    <p>Once again, this produces two messages:</p>
    <p>
      <span class="output">flammable: inflammable</span><br />
      <span class="output">duh: no duh</span>
    </p>
    
    <p>We can break the <code>$.each()</code> loop at a particular iteration by making the callback function return <code>false</code>. Returning <em>non-false</em> is the same as a <code>continue</code> statement in a for loop; it will skip immediately to the next iteration.</p></longdesc>
    <example>
      <desc>Iterates through the array displaying each number as both a word and numeral</desc>
      <code><![CDATA[
    var arr = [ "one", "two", "three", "four", "five" ];
    var obj = { one:1, two:2, three:3, four:4, five:5 };

    jQuery.each(arr, function() {
      $("#" + this).text("Mine is " + this + ".");
       return (this != "three"); // will stop running after "three"
   });

    jQuery.each(obj, function(i, val) {
      $("#" + i).append(document.createTextNode(" - " + val));
    });
]]></code>
  <css><![CDATA[
  div { color:blue; }
  div#five { color:red; }
  ]]></css>
  <html><![CDATA[
  <div id="one"></div>
  <div id="two"></div>
  <div id="three"></div>
  <div id="four"></div>
  <div id="five"></div>]]></html>
  </example>
  <example>
    <desc>Iterates over items in an array, accessing both the current item and its index.</desc>
    <code><![CDATA[$.each( ['a','b','c'], function(i, l){
   alert( "Index #" + i + ": " + l );
 });]]></code>
  </example>
  <example>
    <desc>Iterates over the properties in an object, accessing both the current item and its key.</desc>
    <code><![CDATA[$.each( { name: "John", lang: "JS" }, function(k, v){
   alert( "Key: " + k + ", Value: " + v );
 });]]></code>
</example>
<category name="Utilities"/>
<category name="Version 1.0"/>
</entry>
            <entry type='property' name="jQuery.boxModel" return="Boolean">
                <signature><added>1.0</added></signature>
                <desc><strong>Deprecated in jQuery 1.3 (see <a href="/jQuery.support">jQuery.support</a>)</strong>. States if the current page, in the user's browser, is being rendered using the <a href="http://www.w3.org/TR/REC-CSS2/box.html">W3C CSS Box Model</a>.</desc>
                <longdesc></longdesc>
                <example>
                    <desc>Returns the box model for the iframe.</desc>
                    <code><![CDATA[

    $("p").html("The box model for this iframe is: <span>" +
                jQuery.boxModel + "</span>");
]]></code>
                    <css><![CDATA[

  p { color:blue; margin:20px; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<p>
  </p>]]></html>
                </example>
                <example>
                    <desc>Returns false if the page is in Quirks Mode in Internet Explorer</desc>
                    <code><![CDATA[$.boxModel]]></code>
                    <results><![CDATA[false]]></results>
                </example>
            <category name="Utilities"/>
<category name="Version 1.0"/>
</entry>

<entry type='method' name="scrollTop" return="Integer">
  <signature>
    <added>1.2.6</added>
  </signature>
  <desc>Get the current vertical position of the scroll bar for the first element in the set of matched elements.</desc>  
  <longdesc><p>The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. If the scroll bar is at the very top, or if the element is not scrollable, this number will be <code>0</code>.</p></longdesc>
  <example>
    <desc>Get the scrollTop of a paragraph.</desc>
    <code><![CDATA[var p = $("p:first");
$("p:last").text( "scrollTop:" + p.scrollTop() );

]]></code>
    <css><![CDATA[
  p { margin:10px;padding:5px;border:2px solid #666; }
  ]]></css>
      <html><![CDATA[<p>Hello</p><p></p>]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>
<entry type='method' name="scrollTop" return="jQuery">
  <signature>
    <added>1.2.6</added>
    <argument name="value" type="Number">
      <desc>An integer indicating the new position to set the scroll bar to.</desc>
    </argument>
  </signature>
  <desc>Set the current vertical position of the scroll bar for each of the set of matched elements.</desc>
  <longdesc><p>The vertical scroll position is the same as the number of pixels that are hidden from view above the scrollable area. Setting the <code>scrollTop</code> positions the vertical scroll of each matched element.</p></longdesc>
  <example>
    <desc>Set the scrollTop of a div.</desc>
    <code><![CDATA[$("div.demo").scrollTop(300);
]]></code>
  <css><![CDATA[
div.demo {
background:#CCCCCC none repeat scroll 0 0;
border:3px solid #666666;
margin:5px;
padding:5px;
position:relative;
width:200px;
height:100px;
overflow:auto;
}
  p { margin:10px;padding:5px;border:2px solid #666;width:1000px;height:1000px; }
  ]]></css>
    <html><![CDATA[<div class="demo"><h1>lalala</h1><p>Hello</p></div>]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2.6"/>
</entry>

<entry type='property' name="jQuery.support" return="Object">
  <signature><added>1.3</added></signature>
  <desc>A collection of properties that represent the presence of different browser features or bugs.</desc>
  <longdesc>
    <p>Rather than using <code>$.browser</code> to detect the current user agent and alter the page presentation based on which browser is running, it is a good practice to perform <strong>feature detection</strong>. This means that prior to executing code which relies on a browser feature, we test to ensure that the feature works properly. To make this process simpler, jQuery performs many such tests and makes the results available to us as properties of the <code>jQuery.support</code> object.</p>
    <p>The values of all the support properties are determined using feature detection (and do not use any form of browser sniffing). </p>

<blockquote>
    <p>Following are a few resources that explain how feature detection works:</p>
    <ul>
      <li><a href="http://peter.michaux.ca/articles/feature-detection-state-of-the-art-browser-scripting">http://peter.michaux.ca/articles/feature-detection-state-of-the-art-browser-scripting</a></li>
      <li><a href="http://www.jibbering.com/faq/faq_notes/not_browser_detect.html">http://www.jibbering.com/faq/faq_notes/not_browser_detect.html</a></li>
      <li><a href="http://yura.thinkweb2.com/cft/">http://yura.thinkweb2.com/cft/</a></li>
    </ul>
</blockquote>
    <p>While jQuery includes a number of properties, developers should feel free to add their own as their needs dictate. Many of the <code>jQuery.support</code> properties are rather low-level, so they are most useful for plugin and jQuery core development, rather than general day-to-day development. Since jQuery requires these tests internally, they must be performed on <em>every</em> page load; for that reason this list is kept short and limited to features needed by jQuery itself.</p>

<p>The tests included in <code>jQuery.support</code> are as follows:</p>
<ul>
<li><code>boxModel</code>: Is equal to true if the page is rendering according to the <a href="http://www.w3.org/TR/REC-CSS2/box.html">W3C CSS Box Model</a> (is currently false in IE 6 and 7 when they are in Quirks Mode). This property is null until document ready occurs.</li>
<li><code>changeBubbles</code>: Is equal to true if the change event bubbles up the DOM tree, as required by the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-eventgroupings-htmlevents">W3C DOM event model</a>. (It is currently false in IE, and jQuery simulates bubbling).</li>
<li><code>cssFloat</code>: Is equal to true if the name of the property containing the CSS float value is .cssFloat, as defined in the <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSS2Properties-cssFloat">CSS Spec</a>. (It is currently false in IE, it uses styleFloat instead).</li>
<li><code>hrefNormalized</code>: Is equal to true if the <code>.getAttribute()</code> method retrieves the <code>href</code> attribute of elements unchanged, rather than normalizing it to a fully-qualified URL. (It is currently false in IE, the URLs are normalized). 
  <div><a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#ID-666EE0F9">DOM l3 spec</a></div></li>
<li><code>htmlSerialize</code>: Is equal to true  if the browser is able to serialize/insert <code>&lt;link&gt;</code> elements using the <code>.innerHTML</code> property of elements. (is currently false in IE). <div><a href="http://www.w3.org/TR/2008/WD-html5-20080610/serializing.html#html-fragment">HTML5 wd</a></div></li>
<li><code>leadingWhitespace</code>: Is equal to true if the browser inserts content with .innerHTML exactly as provided—specifically, if leading whitespace characters are preserved. (It is currently false in IE 6-8). <div><a href="http://www.w3.org/TR/2008/WD-html5-20080610/dom.html#innerhtml0">HTML5 wd</a></div></li>
<li><code>noCloneEvent</code>: Is equal to true  if cloned DOM elements are created without event handlers (that is, if the event handlers on the source element are not cloned). (It is currently false in IE). <div><a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-Registration-interfaces-h3">DOM l2 spec</a></div></li>
<li><code>opacity</code>: Is equal to true if a browser can properly interpret the opacity style property. (It is currently false in IE, it uses alpha filters instead). <div><a href="http://www.w3.org/TR/css3-color/#transparency">CSS3 spec</a></div></li>
<li><code>scriptEval</code>: Is equal to true if inline scripts are automatically evaluated and executed when inserted to the document using standard DOM manipulation methods, such as <code>appendChild()</code> and <code>createTextNode()</code>. (It is currently false in IE, it uses <code>.text</code> to insert executable scripts). <div><a href="http://www.w3.org/TR/2008/WD-html5-20080610/tabular.html#script">HTML5 WD</a></div></li>
<li><code>style</code>: Is equal to true if inline styles for an element can be accessed through the DOM attribute called style, as required by the DOM Level 2 specification. In this case, <code>.getAttribute('style')</code> can retrieve this value; in Internet Explorer, <code>.cssText</code> is used for this purpose. <div><a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-ElementCSSInlineStyle">DOM l2 Style spec</a></div></li>
<li><code>submitBubbles</code>: Is equal to true if the submit event bubbles up the DOM tree, as required by the <a href="http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-eventgroupings-htmlevents">W3C DOM event model</a>. (It is currently false in IE, and jQuery simulates bubbling).</li>
<li><code>tbody</code>: Is equal to true if an empty <code>&lt;table&gt;</code> element can exist without a <code>&lt;tbody&gt;</code> element. According to the HTML specification, this sub-element is optional, so the property should be true in a fully-compliant browser. If false, we must account for the possibility of the browser injecting <code>&lt;tbody&gt;</code> tags implicitly. (It is currently false in IE, which automatically inserts <code>tbody</code> if it is not present in a string assigned to <code>innerHTML</code>). <div><a href="http://dev.w3.org/html5/spec/Overview.html#the-table-element">HTML5 spec</a></div></li>
</ul></longdesc>
                <example>
                    <desc>Returns the box model for the iframe.</desc>
                    <code><![CDATA[

    $("p").html("This frame uses the W3C box model: <span>" +
                jQuery.support.boxModel + "</span>");

]]></code>
                    <css><![CDATA[
  p { color:blue; margin:20px; }
  span { color:red; }
  ]]></css>
                    <html><![CDATA[<p>
  </p>]]></html>
                </example>
                <example>
                    <desc>Returns false if the page is in QuirksMode in Internet Explorer</desc>
                    <code><![CDATA[jQuery.support.boxModel]]></code>
                    <results><![CDATA[false]]></results>
                </example>
            <category name="Properties of the Global jQuery Object"/>
<category name="Utilities"/>
<category name="Version 1.3"/>
</entry>
            <entry type='method' name="position" return="Object">
				<signature>
                	<added>1.2</added>
				</signature>
                <desc>Get the current coordinates of the first element in the set of matched elements, relative to the offset parent.</desc>
                <longdesc><p>The <code>.position()</code> method allows us to retrieve the current position of an element <em>relative to the offset parent</em>. Contrast this with <code><a href='/offset'>.offset()</a></code>, which retrieves the current position <em>relative to the document</em>. When positioning a new element near another one and within the same containing DOM element, <code>.position()</code> is the more useful.</p>
<p>Returns an object containing the properties <code>top</code> and <code>left</code>.</p></longdesc>
                <example>
                    <desc>Access the position of the second paragraph:</desc>
                    <code><![CDATA[
var p = $("p:first");
var position = p.position();
$("p:last").text( "left: " + position.left + ", top: " + position.top );
]]></code>
<css><![CDATA[

  div { padding: 15px;}
  p { margin-left:10px; }
  ]]></css>
                    <html><![CDATA[
<div>
  <p>Hello</p>
</div>
<p></p>
]]></html>
                </example>
            <category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2"/>
</entry>

  <entry type='method' name="offset" return="Object">
    <signature>
      <added>1.2</added>
    </signature>
    <desc>Get the current coordinates of the first element in the set of matched elements, relative to the document.</desc>
    <longdesc><p>The <code>.offset()</code> method allows us to retrieve the current position of an element <em>relative to the document</em>. Contrast this with <code>.position()</code>, which retrieves the current position <em>relative to the offset parent</em>. When positioning a new element on top of an existing one for global manipulation (in particular, for implementing drag-and-drop), <code>.offset()</code> is the more useful.</p>

    <p><code>.offset()</code> returns an object containing the properties <code>top</code> and <code>left</code>.</p>
<blockquote><p><strong>Note:</strong> jQuery does not support getting the offset coordinates of hidden elements.</p></blockquote>    
    </longdesc>
    <example>
      <desc>Access the offset of the second paragraph:</desc>
      <code><![CDATA[var p = $("p:last");
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );]]></code>
  <css><![CDATA[
p { margin-left:10px; }
  ]]></css>
  <html><![CDATA[<p>Hello</p><p>2nd Paragraph</p>]]></html>
</example>
<example>
  <desc>Click to see the offset.</desc>
  <code><![CDATA[
$("*", document.body).click(function (e) {
  var offset = $(this).offset();
  e.stopPropagation();
  $("#result").text(this.tagName + " coords ( " + offset.left + ", " +
                                  offset.top + " )");
});

]]></code>
  <css><![CDATA[
p { margin-left:10px; color:blue; width:200px; 
    cursor:pointer; }
span { color:red; cursor:pointer; }
div.abs { width:50px; height:50px; position:absolute;
          left:220px; top:35px; background-color:green; 
          cursor:pointer; }
  ]]></css>
  <html><![CDATA[<div id="result">Click an element.</div>
<p>
  This is the best way to <span>find</span> an offset.
</p>

<div class="abs">
</div>
  ]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="offset" return="jQuery">
  <signature>
    <added>1.4</added>
    <argument name="coordinates" type="Object">
      <desc>An object containing the properties <code>top</code> and <code>left</code>, which are integers indicating the new top and left coordinates for the elements.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, coords)" type="Function">
      <desc>A function to return the coordinates to set. Receives the index of the element in the collection as the first argument and the current coordinates as the second argument. The function should return an object with the new <code>top</code> and <code>left</code> properties.</desc>
    </argument>
  </signature>
  <desc>Set the current coordinates of every element in the set of matched elements, relative to the document.</desc>
  <longdesc><p>The <code>.offset()</code> setter method allows us to reposition an element. The element's position is specified <em>relative to the document</em>. If the element's <code>position</code> style property is currently <code>static</code>, it will be set to <code>relative</code> to allow for this repositioning.</p></longdesc>
  <example>
    <desc>Set the offset of the second paragraph:</desc>
    <code><![CDATA[$("p:last").offset({ top: 10, left: 30 });]]></code>
    <css><![CDATA[p { margin-left:10px; } ]]></css>
    <html><![CDATA[<p>Hello</p><p>2nd Paragraph</p>]]></html>
  </example>
<category name="CSS"/>
<category name="Offset"/>
<category name="Style Properties"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>


            <entry type='method' name="css" return="String">
				<signature>
                	<added>1.0</added>
	                <argument name="propertyName" type="String">
	                    <desc>A CSS property.</desc>
	                </argument>
				</signature>
                <desc>Get the value of a style property for the first element in the set of matched elements.</desc>
                <longdesc><p>The <code>.css()</code> method is a convenient way to get a style property from the first matched element, especially in light of the different ways browsers access most of those properties (the <code>getComputedStyle()</code> method in standards-based browsers versus the <code>currentStyle</code> and <code>runtimeStyle</code> properties in Internet Explorer) and the different terms browsers use for certain properties. For example, Internet Explorer's DOM implementation refers to the <code>float</code> property as <code>styleFloat</code>, while W3C standards-compliant browsers refer to it as <code>cssFloat</code>. The <code>.css()</code> method accounts for such differences, producing the same result no matter which term we use. For example, an element that is floated left will return the string <code>left</code> for each of the following three lines:</p>
				<ol>
					<li><code>$('div.left').css('float');</code></li>
					<li><code>$('div.left').css('cssFloat');</code></li>
					<li><code>$('div.left').css('styleFloat');</code></li>
				</ol>
				<p>Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both <code>.css('background-color')</code> and <code>.css('backgroundColor')</code>.</p>
				<p>Shorthand CSS properties (e.g. margin, background, border) are not supported. For example, if you want to retrieve the rendered margin, use: <code>$(elem).css('marginTop')</code> and <code>$(elem).css('marginRight')</code>, and so on.</p></longdesc>
    <example>
      <desc>To access the background color of a clicked div.</desc>
      <code><![CDATA[
$("div").click(function () {
  var color = $(this).css("background-color");
  $("#result").html("That div is <span style='color:" +
                     color + ";'>" + color + "</span>.");
});

]]></code>
                    <css><![CDATA[
div { width:60px; height:60px; margin:5px; float:left; }
  ]]></css>
<html><![CDATA[
<span id="result">&nbsp;</span>
<div style="background-color:blue;"></div>
<div style="background-color:rgb(15,99,30);"></div>

<div style="background-color:#123456;"></div>
<div style="background-color:#f11;"></div>]]></html>
    </example>
  <category name="CSS"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
  <entry type='method' name="css" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="propertyName" type="String">
        <desc>A CSS property name.</desc>
      </argument>
      <argument name="value" type="String, Number">
        <desc>A value to set for the property.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.4</added>
      <argument name="propertyName" type="String">
        <desc>A CSS property name.</desc>
      </argument>
      <argument name="function(index, value)" type="Function">
        <desc>A function returning the value to set. Receives the index position of the element in the set and the old value as arguments.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="map" type="Map">
        <desc>A map of property-value pairs to set.</desc>
      </argument>
    </signature>
    <desc>Set one or more CSS properties for the  set of matched elements.</desc>
    <longdesc><p>As with the <code>.attr()</code> method, the <code>.css()</code> method makes setting properties of elements quick and easy. This method can take either a property name and value as separate parameters, or a single map of key-value pairs (JavaScript object notation).</p>
				<p>Also, jQuery can equally interpret the CSS and DOM formatting of multiple-word properties. For example, jQuery understands and returns the correct value for both <code>.css({'background-color': '#ffe', 'border-left': '5px solid #ccc'})</code> and <code>.css({backgroundColor: '#ffe', borderLeft: '5px solid #ccc'})</code>. Notice that with the DOM notation, quotation marks around the property names are optional, but with CSS notation they're required due to the hyphen in the name.</p>
				<p>As with <code><a href='/attr'>.attr()</a></code>, <code>.css()</code> allows us to pass a function as the property value:</p>
<pre>$('div.example').css('width', function(index) {
  return index * 50;
});</pre>
  <p>This example sets the widths of the matched elements to incrementally larger values.</p></longdesc>
  <example>
    <desc>To change the color of any paragraph to red on mouseover event.</desc>
    <code><![CDATA[
  $("p").mouseover(function () {
    $(this).css("color","red");
  });
]]></code>
  <css><![CDATA[
  p { color:blue; width:200px; font-size:14px; }
  ]]></css>
<html><![CDATA[
  <p>Just roll the mouse over me.</p>

  <p>Or me to see a color change.</p>
  ]]></html>
</example>
<example>
  <desc>To highlight a clicked word in the paragraph.</desc>
  <code><![CDATA[
  var words = $("p:first").text().split(" ");
  var text = words.join("</span> <span>");
  $("p:first").html("<span>" + text + "</span>");
  $("span").click(function () {
    $(this).css("background-color","yellow");
  });

]]></code>
  <css><![CDATA[
  p { color:blue; font-weight:bold; cursor:pointer; }
  ]]></css>
  <html><![CDATA[
<p>
  Once upon a time there was a man
  who lived in a pizza parlor. This
  man just loved pizza and ate it all 
  the time.  He went on to be the
  happiest man in the world.  The end.
</p>]]></html>
</example>
<example>
  <desc>To set the color of all paragraphs to red and background to blue:</desc>
  <code><![CDATA[
  $("p").hover(function () {
    $(this).css({'background-color' : 'yellow', 'font-weight' : 'bolder'});
  }, function () {
    var cssObj = {
      'background-color' : '#ddd',
      'font-weight' : '',
      'color' : 'rgb(0,40,244)'
    }
    $(this).css(cssObj);
  });
]]></code>
<css><![CDATA[
  p { color:green; }
]]></css>
<html><![CDATA[
  <p>Move the mouse over a paragraph.</p>
  <p>Like this one or the one above.</p>
]]></html>
</example>

<example>
  <desc>Increase the size of a div when you click it:</desc>
  <code><![CDATA[
  $("div").click(function() {
    $(this).css({
      width: function(index, value) {
        return parseFloat(value) * 1.2;
      }, 
      height: function(index, value) {
        return parseFloat(value) * 1.2;
      }

    });
  });
]]></code>
<css><![CDATA[
  div { width: 20px; height: 15px; background-color: #f33; }
  ]]></css>
  <html><![CDATA[
  <div>click</div>
  <div>click</div>
]]></html>
  </example>
<category name="CSS"/>
<category name="Style Properties"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>

<entry type='method' name="unwrap" return="jQuery">
  <signature>
    <added>1.4</added>
  </signature>
                <desc>Remove the parents of the set of matched elements from the DOM, leaving the matched elements in their place.</desc>
                <longdesc><p>The <code>.unwrap()</code> method removes the element's parent. This is effectively the inverse of the <code><a href='/wrap'>.wrap()</a></code> method. The matched elements (and their siblings, if any) replace their parents within the DOM structure.</p></longdesc>
                <example>
                    <desc>Wrap/unwrap a div around each of the paragraphs.</desc>
                    <code><![CDATA[
$("button").toggle(function(){
  $("p").wrap("<div></div>");
}, function(){
  $("p").unwrap();
});]]></code>
                    <css><![CDATA[
  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  ]]></css>
                    <html><![CDATA[<button>wrap/unwrap</button>
<p>Hello</p>
<p>cruel</p>
<p>World</p>]]></html>
                </example>
            <category name="DOM Insertion, Around"/>
<category name="DOM Removal"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="detach" return="jQuery">
				<signature>
                	<added>1.4</added>
	                <argument name="selector" optional="true" type="Selector">
	                    <desc>A selector expression that filters the set of matched elements to be removed.</desc>
	                </argument>
				</signature>
                <desc>Remove the set of matched elements from the DOM.</desc>
                <longdesc><p>The <code>.detach()</code> method is the same as <code><a href='/remove'>.remove()</a></code>, except that <code>.detach()</code> keeps all jQuery data associated with the removed elements. This method is useful when removed elements are to be reinserted into the DOM at a later time.</p></longdesc>
                <example>
                    <desc>Detach all paragraphs from the DOM</desc>
                    <code><![CDATA[
    $("p").click(function(){
      $(this).toggleClass("off");
    });
    var p;
    $("button").click(function(){
      if ( p ) {
        p.appendTo("body");
        p = null;
      } else {
        p = $("p").detach();
      }
    });]]></code>
                    <css><![CDATA[p { background:yellow; margin:6px 0; } p.off { background: black; }]]></css>
                    <html><![CDATA[<p>Hello</p> 
  how are 
  <p>you?</p>
  <button>Attach/detach paragraphs</button>]]></html>
                </example>
            <category name="DOM Removal"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="clone" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="withDataAndEvents" optional="true" type="Boolean">
	                    <desc>A Boolean indicating whether event handlers should be copied along with the elements. As of jQuery 1.4 element data will be copied as well.</desc>
	                </argument>
				</signature>
                <desc>Create a deep copy of the set of matched elements.</desc>
                <longdesc><p>The <code>.clone()</code> method performs a <em>deep</em> copy of the set of matched elements, meaning that it copies the matched elements as well as all of their descendant elements and text nodes. When used in conjunction with one of the insertion methods, <code>.clone()</code> is a convenient way to duplicate elements on a page. Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>As shown in the discussion for <code><a href='/append'>.append()</a></code>,  normally when we insert an element somewhere in the DOM, it is moved from its old location. So, given the code:</p>
				<pre>$('.hello').appendTo('.goodbye');</pre>
				<p>The resulting DOM structure would be:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="goodbye"&gt;
    Goodbye
    &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre>
				<p>To prevent this and instead create a copy of the element, we could write the following:</p>
				<pre>$('.hello').clone().appendTo('.goodbye');</pre>
				<p>This would produce:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;div class="goodbye"&gt;
    Goodbye
    &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre>
				<blockquote><p>Note that when using the <code>.clone()</code> method, we can modify the cloned elements or their contents before (re-)inserting them into the document.</p></blockquote>
				<p>Normally, any event handlers bound to the original element are <em>not</em> copied to the clone. The optional <code>withDataAndEvents </code>parameter allows us to change this behavior, and to instead make copies of all of the event handlers as well, bound to the new copy of the element. As of jQuery 1.4, all element data (attached by the <code>.data()</code> method) is also copied to the new copy. </p></longdesc>
<example>
<desc>Clones all b elements (and selects the clones) and prepends them to all paragraphs.</desc>
<code><![CDATA[
  $("b").clone().prependTo("p");
]]></code>
<html><![CDATA[
  <b>Hello</b><p>, how are you?</p>
]]></html>
</example>
<category name="Copying"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="remove" return="jQuery">
				<signature>
	                <added>1.0</added>
	                <argument name="selector" optional="true" type="String">
	                    <desc>A selector expression that filters the set of matched elements to be removed.</desc>
	                </argument>
				</signature>
                <desc>Remove the set of matched elements from the DOM.</desc>
                <longdesc><p>Similar to <code><a href='/empty'>.empty()</a></code>, the <code>.remove()</code> method takes elements out of the DOM. We use <code>.remove()</code> when we want to remove the element itself, as well as everything inside it. In addition to the elements themselves, all bound events and jQuery data  associated with the elements are removed.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can target any element for removal:</p>
				<pre>$('.hello').remove();</pre>
				<p>This will result in a DOM structure with the <code>&lt;div&gt;</code> element deleted:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>If we had any number of nested elements inside <code>&lt;div class="hello"&gt;</code>, they would be removed, too. Other jQuery constructs such as data or event handlers are erased as well.</p>
				<p>We can also include a selector as an optional parameter. For example, we could rewrite the previous DOM removal code as follows:</p>
				<pre>$('div').remove('.hello');</pre>
				<p>This would result in the same DOM structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre></longdesc>
                <example>
                    <desc>Removes all paragraphs from the DOM</desc>
                    <code><![CDATA[
    $("button").click(function () {
      $("p").remove();
    });

]]></code>
                    <css><![CDATA[p { background:yellow; margin:6px 0; }]]></css>
                    <html><![CDATA[<p>Hello</p> 
  how are 
  <p>you?</p>
  <button>Call remove() on paragraphs</button>]]></html>
                </example>
                <example>
                    <desc>Removes all paragraphs that contain "Hello" from the DOM</desc>
                    <code><![CDATA[

    $("button").click(function () {
      $("p").remove(":contains('Hello')");
    });

]]></code>
                    <css><![CDATA[p { background:yellow; margin:6px 0; }]]></css>
                    <html><![CDATA[<p class="hello">Hello</p>
  how are 
  <p>you?</p>

  <button>Call remove(":contains('Hello')") on paragraphs</button>]]></html>
                </example>
            <category name="DOM Removal"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="empty" return="jQuery">
  <signature>
    <added>1.0</added>
  </signature>
  <desc>Remove all child nodes of the set of matched elements from the DOM.</desc>
  <longdesc><p>This method removes not only child (and other descendant) elements, but also any text within the set of matched elements. This is because, according to the DOM specification, any string of text within an element is considered a child node of that element. Consider the following HTML:</p>
<pre>&lt;div class="container"&gt;
  &lt;div class="hello"&gt;Hello&lt;/div&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
<p>We can target any element for removal:</p>
<pre>$('.hello').empty();</pre>
<p>This will result in a DOM structure with the <code>Hello</code> text deleted:</p>
<pre>&lt;div class="container"&gt;
  &lt;div class="hello"&gt;&lt;/div&gt;
  &lt;div class="goodbye"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
<p>If we had any number of nested elements inside <code>&lt;div class="hello"&gt;</code>, they would be removed, too. </p>
  <p>To avoid memory leaks, jQuery removes other constructs such as data and event handlers from the child elements before removing the elements themselves.</p>
  </longdesc>
  <example>
    <desc>Removes all child nodes (including text nodes) from all paragraphs</desc>
    <code><![CDATA[
  $("button").click(function () {
    $("p").empty();
  });
]]></code>
<css><![CDATA[
  p { background:yellow; }
]]></css>
<html><![CDATA[<p>
  Hello, <span>Person</span> <a href="javascript:;">and person</a>
</p>

<button>Call empty() on above paragraph</button>]]></html>
  </example>
<category name="DOM Removal"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="replaceAll" return="jQuery">
                <signature><added>1.2</added>
                  <argument name="target" type="Selector">
                    <desc>A selector expression indicating which element(s) to replace.</desc>
                  </argument>
                </signature>
                <desc>Replace each target element with the set of matched elements.</desc>
                <longdesc><p>The <code>.replaceAll()</code> method is corollary to <code><a href='/replaceWith'>.replaceWith()</a></code>, but with the source and target reversed. Consider this DOM structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner first"&gt;Hello&lt;/div&gt;
  &lt;div class="inner second"&gt;And&lt;/div&gt;
  &lt;div class="inner third"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create an element, then replace other elements with it:</p>
				<pre>$('&lt;h2&gt;New heading&lt;/h2&gt;').replaceAll('.inner');</pre>
				<p>This causes all of them to be replaced:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
&lt;/div&gt;</pre>
				<p>Or, we could select an element to use as the replacement:</p>
				<pre>$('.first').replaceAll('.third');</pre>
				<p>This results in the DOM structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner second"&gt;And&lt;/div&gt;
  &lt;div class="inner first"&gt;Hello&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>From this example, we can see that the selected element replaces the target by being moved from its old location, not by being cloned.</p></longdesc>
                <example>
                    <desc>Replace all the paragraphs with bold words.</desc>
                    <code><![CDATA[$("<b>Paragraph. </b>").replaceAll("p"); // check replaceWith() examples]]></code>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
            <category name="DOM Replacement"/>
<category name="Version 1.2"/>
</entry>
            <entry type='method' name="replaceWith" return="jQuery">
				<signature>
	                <added>1.2</added>
	                <argument name="newContent" type="String, Element, jQuery">
	                    <desc>The content to insert. May be an HTML string, DOM element, or jQuery object.</desc>
	                </argument>
				</signature>
  <signature>
    <added>1.4</added>
    <argument name="function" type="Function">
      <desc>A function that returns an HTML string to replace the set of matched elements with.</desc>
    </argument>
  </signature>
                <desc>Replace each element in the set of matched elements with the provided new content.</desc>
                <longdesc><p>The <code>.replaceWith()</code> method allows us to remove content from the DOM and insert new content in its place with a single call. Consider this DOM structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner first"&gt;Hello&lt;/div&gt;
  &lt;div class="inner second"&gt;And&lt;/div&gt;
  &lt;div class="inner third"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can replace the second inner <code>&lt;div&gt;</code> with specified HTML:</p>
				<pre>$('.second').replaceWith('&lt;h2&gt;New heading&lt;/h2&gt;');</pre>
				<p>This results in the structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner first"&gt;Hello&lt;/div&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
  &lt;div class="inner third"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We could equally target all inner <code>&lt;div&gt;</code> elements at once:</p>
				<pre>$('.inner').replaceWith('&lt;h2&gt;New heading&lt;/h2&gt;');</pre>
				<p>This causes all of them to be replaced:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
  &lt;h2&gt;New heading&lt;/h2&gt;
&lt;/div&gt;</pre>
				<p>Or, we could select an element to use as the replacement:</p>
				<pre>$('.third').replaceWith($('.first'));</pre>
				<p>This results in the DOM structure:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner second"&gt;And&lt;/div&gt;
  &lt;div class="inner first"&gt;Hello&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>From this example, we can see that the selected element replaces the target by being moved from its old location, not by being cloned.</p>
				<p>The <code>.replaceWith()</code> method, like most jQuery methods, returns the jQuery object so that other methods can be chained onto it. However, it must be noted that the <emphasis role="italics">original</emphasis> jQuery object is returned. This object refers to the element that has been removed from the DOM, not the new element that has replaced it.</p>
<p>In jQuery 1.4 <code>.replaceWith()</code>, <code>.before()</code>, and <code>.after()</code> can also work on disconnected DOM nodes. For example, with the following code:</p>
<pre>$("&lt;div/&gt;").replaceWith("&lt;p&gt;&lt;/p&gt;");</pre>
<p>The <code>.replaceWith()</code> method returns a jQuery set containing only a paragraph.</p></longdesc>
                <example>
                    <desc>On click, replace the button with a div containing the same word.</desc>
                    <code><![CDATA[

    $("button").click(function () {
      $(this).replaceWith("<div>" + $(this).text() + "</div>");
    });
]]></code>
                    <css><![CDATA[
  button { display:block; margin:3px; color:red; width:200px; }
  div { color:red; border:2px solid blue; width:200px; 
        margin:3px; text-align:center; }
  ]]></css>
                    <html><![CDATA[<button>First</button>
  <button>Second</button>

  <button>Third</button>]]></html>
                </example>
                <example>
                    <desc>Replace all the paragraphs with bold words.</desc>
                    <code><![CDATA[$("p").replaceWith("<b>Paragraph. </b>");]]></code>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>

  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Replace all the paragraphs with empty div elements.</desc>
                    <code><![CDATA[$("p").replaceWith(document.createElement("div"));]]></code>
                    <css><![CDATA[
  div { border:2px solid blue; margin:3px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>

  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>On click, replace each paragraph with a jQuery div object that is already in the DOM.  Notice it doesn't clone the object but rather moves it to replace the paragraph.</desc>
                    <code><![CDATA[
    $("p").click(function () {
      $(this).replaceWith($("div"));
    });

]]></code>
                    <css><![CDATA[
  div { border:2px solid blue; color:red; margin:3px; }
  p { border:2px solid red; color:blue; margin:3px; cursor:pointer; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>

  <div>Replaced!</div>]]></html>
                </example>
            <category name="DOM Replacement"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="wrapInner" return="jQuery">
				<signature>
                	<added>1.2</added>
	                <argument name="wrappingElement" type="String">
	                    <desc>An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the content of the matched elements.</desc>
	                </argument>
				</signature>
				<signature>
                	<added>1.4</added>
	                <argument name="wrappingFunction" type="Function">
	                    <desc>A callback function which generates a structure to wrap around the content of the matched elements.</desc>
	                </argument>
				</signature>
                <desc>Wrap an HTML structure around the content of each element in the set of matched elements.</desc>
                <longdesc><p>The <code>.wrapInner()</code> function can take any string or object that could be passed to the <code>$()</code> factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around the content of each of the elements in the set of matched elements.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>Using <code>.wrapInner()</code>, we can insert an HTML structure around the content of each inner <code>&lt;div&gt;</code> elements like so:</p>
				<pre>$('.inner').wrapInner('&lt;div class="new" /&gt;');</pre>
				<p>The new <code>&lt;div&gt;</code> element is created on the fly and added to the DOM. The result is a new <code>&lt;div&gt;</code> wrapped around the content of each matched element:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    &lt;div class="new"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    &lt;div class="new"&gt;Goodbye&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre>
				<p>The second version of this method allows us to instead specify a callback function. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the content of the corresponding element. For example:</p>
				<pre>$('.inner').wrapInner(function() {
  return '&lt;div class="' + this.nodeValue + '" /&gt;';
});</pre>
				<p>This will cause each <code>&lt;div&gt;</code> to have a class corresponding to the text it wraps:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    &lt;div class="Hello"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    &lt;div class="Goodbye"&gt;Goodbye&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre></longdesc>
                <example>
                    <desc>Selects all paragraphs and wraps a bold tag around each of its contents.</desc>
                    <code><![CDATA[$("p").wrapInner("<b></b>");]]></code>
                    <css><![CDATA[p { background:#bbf; }]]></css>
                    <html><![CDATA[<p>Hello</p>

  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Wraps a newly created tree of objects around the inside of the body.</desc>
                    <code><![CDATA[$("body").wrapInner("<div><div><p><em><b></b></em></p></div></div>");]]></code>
                    <css><![CDATA[

  div { border:2px green solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  ]]></css>
                    <html><![CDATA[Plain old text, or is it?]]></html>
                </example>
                <example>
                    <desc>Selects all paragraphs and wraps a bold tag around each of its contents.</desc>
                    <code><![CDATA[$("p").wrapInner(document.createElement("b"));]]></code>
                    <css><![CDATA[p { background:#9f9; }]]></css>
                    <html><![CDATA[<p>Hello</p>

  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Selects all paragraphs and wraps a jQuery object around each of its contents.</desc>
                    <code><![CDATA[$("p").wrapInner($("<span class='red'></span>"));]]></code>
                    <css><![CDATA[

  p { background:#9f9; }
  .red { color:red; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
            <category name="DOM Insertion, Around"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="wrapAll" return="jQuery">
				<signature>
                	<added>1.2</added>
	                <argument name="wrappingElement" type="String, Selector, Element, jQuery">
	                    <desc>An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements.</desc>
	                </argument>
				</signature>
                <desc>Wrap an HTML structure around all elements in the set of matched elements.</desc>
                <longdesc><p>The <code>.wrapAll()</code> function can take any string or object that could be passed to the <code>$()</code> function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around all of the elements in the set of matched elements, as a single group.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>Using <code>.wrapAll()</code>, we can insert an HTML structure around the inner <code>&lt;div&gt;</code> elements like so:</p>
				<pre>$('.inner').wrapAll('&lt;div class="new" /&gt;');</pre>
				<p>The new <code>&lt;div&gt;</code> element is created on the fly and added to the DOM. The result is a new <code>&lt;div&gt;</code> wrapped around all matched elements:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="new"&gt;
    &lt;div class="inner"&gt;Hello&lt;/div&gt;
    &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre></longdesc>
                <example>
                    <desc>Wrap a new div around all of the paragraphs.</desc>
                    <code><![CDATA[$("p").wrapAll("<div></div>");]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Wraps a newly created tree of objects around the spans.  Notice anything in between the spans gets left out like the &lt;strong&gt; (red text) in this example.  Even the white space between spans is left out.  Click View Source to see the original html.</desc>
                    <code><![CDATA[$("span").wrapAll("<div><div><p><em><b></b></em></p></div></div>");]]></code>
                    <css><![CDATA[

  div { border:2px blue solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  strong { color:red; }
  ]]></css>
                    <html><![CDATA[<span>Span Text</span>
  <strong>What about me?</strong>
  <span>Another One</span>]]></html>
                </example>
                <example>
                    <desc>Wrap a new div around all of the paragraphs.</desc>
                    <code><![CDATA[$("p").wrapAll(document.createElement("div"));]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Wrap a jQuery object double depth div around all of the paragraphs.  Notice it doesn't move the object but just clones it to wrap around its target.</desc>
                    <code><![CDATA[$("p").wrapAll($(".doublediv"));]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; margin:2px; padding:2px; }
  .doublediv { border-color:red; }
  p { background:yellow; margin:4px; font-size:14px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>
  <div class="doublediv"><div></div></div>]]></html>
                </example>
            <category name="DOM Insertion, Around"/>
<category name="Version 1.2"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="wrap" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="wrappingElement" type="String, Selector, Element, jQuery">
      <desc>An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="wrappingFunction" type="Function">
      <desc>A callback function which generates a structure to wrap around the matched elements.</desc>
    </argument>
  </signature>
  <desc>Wrap an HTML structure around each element in the set of matched elements.</desc>
  <longdesc><p>The <code>.wrap()</code> function can take any string or object that could be passed to the <code>$()</code> factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around each of the elements in the set of matched elements. This method returns the original set of elements for chaining purposes.</p>
  <p>Consider the following HTML:</p>
  <pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>Using <code>.wrap()</code>, we can insert an HTML structure around the inner <code>&lt;div&gt;</code> elements like so:</p>
				<pre>$('.inner').wrap('&lt;div class="new" /&gt;');</pre>
				<p>The new <code>&lt;div&gt;</code> element is created on the fly and added to the DOM. The result is a new <code>&lt;div&gt;</code> wrapped around each matched element:</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="new"&gt;
    &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="new"&gt;
    &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre>
  <p>The second version of this method allows us to instead specify a callback function. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the corresponding element. For example:</p>
  <pre>$('.inner').wrap(function() {
  return '&lt;div class="' + $(this).text() + '" /&gt;';
});</pre>
  <p>This will cause each <code>&lt;div&gt;</code> to have a class corresponding to the text it wraps:</p>
  <pre>&lt;div class="container"&gt;
  &lt;div class="Hello"&gt;
    &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;/div&gt;
  &lt;div class="Goodbye"&gt;
    &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;/div&gt;
&lt;/div&gt;</pre>
</longdesc>
                <example>
                    <desc>Wrap a new div around all of the paragraphs.</desc>
                    <code><![CDATA[$("p").wrap("<div></div>");]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc><![CDATA[Wraps a newly created tree of objects around the spans.  Notice anything in between the spans gets left out like the <strong> (red text) in this example.  Even the white space between spans is left out.  Click View Source to see the original html.]]></desc>
                    <code><![CDATA[$("span").wrap("<div><div><p><em><b></b></em></p></div></div>");]]></code>
                    <css><![CDATA[

  div { border:2px blue solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  strong { color:red; }
  ]]></css>
                    <html><![CDATA[<span>Span Text</span>
  <strong>What about me?</strong>
  <span>Another One</span>]]></html>
                </example>
                <example>
                    <desc>Wrap a new div around all of the paragraphs.</desc>
                    <code><![CDATA[$("p").wrap(document.createElement("div"));]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; }
  p { background:yellow; margin:4px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>]]></html>
                </example>
                <example>
                    <desc>Wrap a jQuery object double depth div around all of the paragraphs.  Notice it doesn't move the object but just clones it to wrap around its target.</desc>
                    <code><![CDATA[$("p").wrap($(".doublediv"));]]></code>
                    <css><![CDATA[

  div { border: 2px solid blue; margin:2px; padding:2px; }
  .doublediv { border-color:red; }
  p { background:yellow; margin:4px; font-size:14px; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>cruel</p>
  <p>World</p>
  <div class="doublediv"><div></div></div>]]></html>
                </example>
            <category name="DOM Insertion, Around"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="insertBefore" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="target" type="Selector, Element, jQuery">
	                    <desc>A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted before the element(s) specified by this parameter.</desc>
	                </argument>
				</signature>
                <desc>Insert every element in the set of matched elements before the target.</desc>
                <longdesc><p>The <code><a href='/before'>.before()</a></code> and <code>.insertBefore()</code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .before()</code>, the selector expression preceding the method is the container before which the content is inserted. With <code>.insertBefore()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it before several elements at once:</p>
				<pre>$('&lt;p&gt;Test&lt;/p&gt;').insertBefore('.inner');</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can also select an element on the page and insert it before another:</p>
				<pre>$('h2').insertBefore($('.container'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned):</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
                <example>
                    <desc>Inserts all paragraphs before an element with id of "foo". Same as $("#foo").before("p")</desc>
                    <code><![CDATA[$("p").insertBefore("#foo"); // check before() examples]]></code>
                    <css><![CDATA[#foo { background:yellow; }]]></css>
                    <html><![CDATA[<div id="foo">FOO!</div><p>I would like to say: </p>]]></html>
                </example>
            <category name="DOM Insertion, Outside"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="before" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="content" type="String, Element, jQuery">
	                    <desc>An element, HTML string, or jQuery object to insert before each element in the set of matched elements.</desc>
	                </argument>
				</signature>
				<signature>
                	<added>1.4</added>
	                <argument name="function" type="Function">
	                    <desc>A function that returns an HTML string to insert before each element in the set of matched elements.</desc>
	                </argument>
				</signature>
                <desc>Insert content, specified by the parameter, before each element in the set of matched elements.</desc>
                <longdesc><p>The <code>.before()</code> and <code><a href='/insertBefore'>.insertBefore()</a></code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .before()</code>, the selector expression preceding the method is the container before which the content is inserted. With <code>.insertBefore()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted before the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it before several elements at once:</p>
				<pre>$('.inner').before('&lt;p&gt;Test&lt;/p&gt;');</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
<p>We can also select an element on the page and insert it before another:</p>
				<pre>$('.container').before($('h2'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned):</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p>
<p>In jQuery 1.4, <code>.before()</code> and <code>.after()</code> will also work on disconnected DOM nodes:</p>
<pre>$("&lt;div/&gt;").before("&lt;p&gt;&lt;/p&gt;");</pre>
<p>The result is a jQuery set that contains a paragraph and a div (in that order).</p></longdesc>
                <example>
                    <desc>Inserts some HTML before all paragraphs.</desc>
                    <code><![CDATA[$("p").before("<b>Hello</b>");]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p> is what I said...</p>]]></html>
                </example>
                <example>
                    <desc>Inserts a DOM element before all paragraphs.</desc>
                    <code><![CDATA[$("p").before( document.createTextNode("Hello") );]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p> is what I said...</p>]]></html>
                </example>
                <example>
                    <desc>Inserts a jQuery object (similar to an Array of DOM Elements) before all paragraphs.</desc>
                    <code><![CDATA[$("p").before( $("b") );]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p> is what I said...</p><b>Hello</b>]]></html>
                </example>
            <category name="DOM Insertion, Outside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="insertAfter" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="target" type="Selector, Element, jQuery">
	                    <desc>A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted after the element(s) specified by this parameter.</desc>
	                </argument>
				</signature>
                <desc>Insert every element in the set of matched elements after the target.</desc>
                <longdesc><p>The <code><a href='/after'>.after()</a></code> and <code>.insertAfter()</code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .after()</code>, the selector expression preceding the method is the container after which the content is inserted. With <code>.insertAfter()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it after several elements at once:</p>
				<pre>$('&lt;p&gt;Test&lt;/p&gt;').insertAfter('.inner');</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
&lt;/div&gt;</pre>
				<p>We can also select an element on the page and insert it after another:</p>
				<pre>$('h2').insertAfter($('.container'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned):</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;
&lt;h2&gt;Greetings&lt;/h2&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
                <example>
                    <desc>Inserts all paragraphs after an element with id of "foo". Same as $("#foo").after("p")</desc>
                    <code><![CDATA[$("p").insertAfter("#foo"); // check after() examples]]></code>
                    <css><![CDATA[#foo { background:yellow; }]]></css>
                    <html><![CDATA[<p> is what I said... </p><div id="foo">FOO!</div>]]></html>
                </example>
            <category name="DOM Insertion, Outside"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="after" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="content" type="String, Element, jQuery">
      <desc>An element, HTML string, or jQuery object to insert after each element in the set of matched elements.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index)" type="Function">
      <desc>A function that returns an HTML string to insert after each element in the set of matched elements.</desc>
    </argument>
  </signature>
  <desc>Insert content, specified by the parameter, after each element in the set of matched elements.</desc>
  <longdesc><p>The <code>.after()</code> and <code><a href='/insertAfter'>.insertAfter()</a></code> methods perform the same task. The major difference is in the syntax&#8212;specifically, in the placement of the content and target. With<code> .after()</code>, the selector expression preceding the method is the container after which the content is inserted. With <code>.insertAfter()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted after the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it after several elements at once:</p>
				<pre>$('.inner').after('&lt;p&gt;Test&lt;/p&gt;');</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;p&gt;Test&lt;/p&gt;
&lt;/div&gt;</pre>
				<p>We can also select an element on the page and insert it after another:</p>
				<pre>$('.container').after($('h2'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned):</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;
&lt;h2&gt;Greetings&lt;/h2&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p>
<h4 id="disconnected-dom-nodes">Inserting Disconnected DOM nodes</h4>
<p>As of jQuery 1.4, <code>.before()</code> and <code>.after()</code> will also work on disconnected DOM nodes. For example, given the following code:</p>
<pre>$('&lt;div/&gt;').after('&lt;p&gt;&lt;/p&gt;');</pre>
<p>The result is a jQuery set containing a div and a paragraph, in that order. We can further manipulate that set, even before inserting it in the document.</p>
<pre>$('&lt;div/&gt;').after('&lt;p&gt;&lt;/p&gt;').addClass('foo')
  .filter('p').attr('id', 'bar').html('hello')
.end()
.appendTo('body');</pre>
<p>This results in the following elements inserted just before the closing <code>&lt;/body&gt;</code> tag:</p>
<pre>
&lt;div class="foo"&gt;&lt;/div&gt;
&lt;p class="foo" id="bar"&gt;hello&lt;/p&gt;
</pre>
<p>As of jQuery 1.4, <code>.after()</code> allows us to pass a function that returns the elements to insert.</p>
<pre>$('p').after(function() {
  return '&lt;div&gt;' + this.className + '&lt;/div&gt;';
});</pre>
<p>This inserts a <code>&lt;div&gt;</code> after each paragraph, containing the class name(s) of each paragraph in turn.</p>
</longdesc>
  <example>
      <desc>Inserts some HTML after all paragraphs.</desc>
      <code><![CDATA[$("p").after("<b>Hello</b>");]]></code>
      <css><![CDATA[p { background:yellow; }]]></css>
      <html><![CDATA[<p>I would like to say: </p>]]></html>
  </example>
  <example>
      <desc>Inserts a DOM element after all paragraphs.</desc>
      <code><![CDATA[$("p").after( document.createTextNode("Hello") );]]></code>
      <css><![CDATA[p { background:yellow; }]]></css>
      <html><![CDATA[<p>I would like to say: </p>]]></html>
  </example>
  <example>
      <desc>Inserts a jQuery object (similar to an Array of DOM Elements) after all paragraphs.</desc>
      <code><![CDATA[$("p").after( $("b") );]]></code>
      <css><![CDATA[p { background:yellow; }]]></css>
      <html><![CDATA[<b>Hello</b><p>I would like to say: </p>]]></html>
  </example>
<category name="DOM Insertion, Outside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="prependTo" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="target" type="Selector, Element, jQuery">
	                    <desc>A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the beginning of the element(s) specified by this parameter.</desc>
	                </argument>
				</signature>
                <desc>Insert every element in the set of matched elements to the beginning of the target.</desc>
                <longdesc><p>The <code><a href='/prepend'>.prepend()</a></code> and <code>.prependTo()</code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .prepend()</code>, the selector expression preceding the method is the container into which the content is inserted. With <code>.prependTo()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it into several elements at once:</p>
				<pre>$('&lt;p&gt;Test&lt;/p&gt;').prependTo('.inner');</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    &lt;p&gt;Test&lt;/p&gt;
    Hello
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    &lt;p&gt;Test&lt;/p&gt;
    Goodbye
  &lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can also select an element on the page and insert it into another:</p>
				<pre>$('h2').prependTo($('.container'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
                <example>
                    <desc>Prepends all spans to the element with the ID "foo"</desc>
                    <css><![CDATA[div { background:yellow; }]]></css>
                    <code><![CDATA[$("span").prependTo("#foo"); // check prepend() examples]]></code>
                    <html><![CDATA[<div id="foo">FOO!</div>

  <span>I have something to say... </span>]]></html>
                </example>
            <category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="prepend" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="content" type="String, Element, jQuery">
      <desc>An element, HTML string, or jQuery object to insert at the beginning of each element in the set of matched elements.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, html)" type="Function">
      <desc>A function that returns an HTML string to insert at the beginning of each element in the set of matched elements. Receives the index position of the element in the set and the old HTML value of the element as arguments.</desc>
    </argument>
  </signature>
  <desc>Insert content, specified by the parameter, to the beginning of each element in the set of matched elements.</desc>
  <longdesc><p>The <code>.prepend()</code> method inserts the specified content as the first child of each element in the jQuery collection (To insert it as the <em>last</em> child, use <a href="http://api.jquery.com/append/"><code>.append()</code></a>). </p>
<p>The <code>.prepend()</code> and <code><a href='/prependTo'>.prependTo()</a></code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .prepend()</code>, the selector expression preceding the method is the container into which the content is inserted. With <code>.prependTo()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can create content and insert it into several elements at once:</p>
				<pre>$('.inner').prepend('&lt;p&gt;Test&lt;/p&gt;');</pre>
				<p>Each <code>&lt;div class="inner"&gt;</code> element gets this new content:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    &lt;p&gt;Test&lt;/p&gt;
    Hello
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    &lt;p&gt;Test&lt;/p&gt;
    Goodbye
  &lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can also select an element on the page and insert it into another:</p>
				<pre>$('.container').prepend($('h2'));</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):</p>
				<pre>&lt;div class="container"&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
                <example>
                    <desc>Prepends some HTML to all paragraphs.</desc>
                    <code><![CDATA[$("p").prepend("<b>Hello </b>");]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p>there friend!</p>

  <p>amigo!</p>]]></html>
                </example>
                <example>
                    <desc>Prepends a DOM Element to all paragraphs.</desc>
                    <code><![CDATA[$("p").prepend(document.createTextNode("Hello "));]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p>is what I'd say</p>
  <p>is what I said</p>]]></html>
                </example>
                <example>
                    <desc>Prepends a jQuery object (similar to an Array of DOM Elements) to all paragraphs.</desc>
                    <code><![CDATA[$("p").prepend( $("b") );]]></code>
                    <css><![CDATA[p { background:yellow; }]]></css>
                    <html><![CDATA[<p> is what was said.</p><b>Hello</b>]]></html>
                </example>
            <category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="appendTo" return="jQuery">
				<signature>
                	<added>1.0</added>
	                <argument name="target" type="Selector, Element, jQuery">
	                    <desc>A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the end of the element(s) specified by this parameter.</desc>
	                </argument>
				</signature>
                <desc>Insert every element in the set of matched elements to the end of the target.</desc>
                <longdesc><p>The <code><a href='/append'>.append()</a></code> and <code>.appendTo()</code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .append()</code>, the selector expression preceding the method is the container into which the content is inserted. With <code>.appendTo()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.</p>
				<p>Consider the following HTML:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;
</pre>
				<p>We can create content and insert it into several elements at once:</p>
				<pre>$('&lt;p&gt;Test&lt;/p&gt;').appendTo('.inner');
</pre>
				<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
				<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    Hello
    &lt;p&gt;Test&lt;/p&gt;
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    Goodbye
    &lt;p&gt;Test&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;
</pre>
				<p>We can also select an element on the page and insert it into another:</p>
				<pre>$('h2').appendTo($('.container'));
</pre>
				<p>If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):</p>
				<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
&lt;/div&gt;
</pre>
				<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
                <example>
                    <desc>Appends all spans to the element with the ID "foo"</desc>
                    <code><![CDATA[$("span").appendTo("#foo"); // check append() examples]]></code>
                    <css><![CDATA[#foo { background:yellow; }]]></css>
                    <html><![CDATA[<span>I have nothing more to say... </span>

  <div id="foo">FOO! </div>]]></html>
                </example>
            <category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
</entry>
<entry type='method' name="append" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="content" type="String, Element, jQuery">
      <desc>An element, HTML string, or jQuery object to insert at the end of each element in the set of matched elements.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, html)" type="Function">
      <desc>A function that returns an HTML string to insert at the end of each element in the set of matched elements. Receives the index position of the element in the set and the old HTML value of the element as arguments.</desc>
    </argument>
  </signature>
  <desc>Insert content, specified by the parameter, to the end of each element in the set of matched elements.</desc>
  <longdesc><p>The <code>.append()</code> method inserts the  specified content as the last child of each element in the jQuery collection (To insert it as the <em>first</em> child, use <a href="http://api.jquery.com/prepend/"><code>.prepend()</code></a>). </p>
    <p>The <code>.append()</code> and <code><a href='/appendTo'>.appendTo()</a></code> methods perform the same task. The major difference is in the syntax-specifically, in the placement of the content and target. With<code> .append()</code>, the selector expression preceding the method is the container into which the content is inserted. With <code>.appendTo()</code>, on the other hand, the content precedes the method, either as a selector expression or as markup created on the fly, and it is inserted into the target container.</p>
    <p>Consider the following HTML:</p>
    <pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
&lt;/div&gt;
</pre>
<p>We can create content and insert it into several elements at once:</p>
<pre>$('.inner').append('&lt;p&gt;Test&lt;/p&gt;');
</pre>
<p>Each inner <code>&lt;div&gt;</code> element gets this new content:</p>
<pre>&lt;h2&gt;Greetings&lt;/h2&gt;
&lt;div class="container"&gt;
  &lt;div class="inner"&gt;
    Hello
    &lt;p&gt;Test&lt;/p&gt;
  &lt;/div&gt;
  &lt;div class="inner"&gt;
    Goodbye
    &lt;p&gt;Test&lt;/p&gt;
  &lt;/div&gt;
&lt;/div&gt;
</pre>
<p>We can also select an element on the page and insert it into another:</p>
<pre>$('.container').append($('h2'));
</pre>
<p>If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned):</p>
<pre>&lt;div class="container"&gt;
  &lt;div class="inner"&gt;Hello&lt;/div&gt;
  &lt;div class="inner"&gt;Goodbye&lt;/div&gt;
  &lt;h2&gt;Greetings&lt;/h2&gt;
&lt;/div&gt;
</pre>
<p>If there is more than one target element, however, cloned copies of the inserted element will be created for each target after the first.</p></longdesc>
<example>
  <desc>Appends some HTML to all paragraphs.</desc>
  <code><![CDATA[
  $("p").append("<strong>Hello</strong>");
]]></code>
  <css><![CDATA[
  p { background:yellow; }
]]></css>
  <html><![CDATA[<p>I would like to say: </p>]]></html>
</example>
<example>
  <desc>Appends an Element to all paragraphs.</desc>
  <code><![CDATA[
  $("p").append(document.createTextNode("Hello"));
]]></code>
  <css><![CDATA[
  p { background:yellow; }
]]></css>
  <html><![CDATA[<p>I would like to say: </p>
]]></html>
</example>
<example>
  <desc>Appends a jQuery object (similar to an Array of DOM Elements) to all paragraphs.</desc>
  <code><![CDATA[
  $("p").append( $("strong") );
]]></code>
  <css><![CDATA[
  p { background:yellow; }
]]></css>
  <html><![CDATA[<strong>Hello world!!!</strong><p>I would like to say: </p>]]></html>
</example>
<category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>

  <entry type='method' name="val" return="String, Array">
    <signature>
      <added>1.0</added>
    </signature>
    <desc>Get the current value of the first element in the set of matched elements.</desc>
    <longdesc>
      <p>The <code>.val()</code> method is primarily used to get the values of form elements. In the case of <code>&lt;select multiple="multiple"&gt;</code> elements, the <code>.val()</code> method returns an array containing each selected option.</p>

<p>For selects and checkboxes, you can also use the <a href='/selected'>:selected</a> and <a href='/checked'>:checked</a> selectors to get at values, for example:</p>
<pre>$('select.foo option:selected').val();    // get the value from a dropdown select
$('select.foo').val();                    // get the value from a dropdown select even easier
$('input:checkbox:checked').val();        // get the value from a checked checkbox
$('input:radio[name=bar]:checked').val(); // get the value from a set of radio buttons</pre></longdesc>
                <example>
                    <desc>Get the single value from a single select and an array of values from a multiple select and display their values.</desc>
                    <code><![CDATA[
    function displayVals() {
      var singleValues = $("#single").val();
      var multipleValues = $("#multiple").val() || [];
      $("p").html("<b>Single:</b> " + 
                  singleValues +
                  " <b>Multiple:</b> " + 
                  multipleValues.join(", "));
    }

    $("select").change(displayVals);
    displayVals();

]]></code>
                    <css><![CDATA[
  p { color:red; margin:4px; }
  b { color:blue; }
  ]]></css>
                    <html><![CDATA[<p></p>
  <select id="single">
    <option>Single</option>
    <option>Single2</option>

  </select>
  <select id="multiple" multiple="multiple">
    <option selected="selected">Multiple</option>
    <option>Multiple2</option>

    <option selected="selected">Multiple3</option>
  </select>]]></html>
</example>
<example>
    <desc>Find the value of an input box.</desc>
    <code><![CDATA[
    $("input").keyup(function () {
      var value = $(this).val();
      $("p").text(value);
    }).keyup();
]]></code>
  <css><![CDATA[

  p { color:blue; margin:8px; }
  ]]></css>
  <html><![CDATA[<input type="text" value="some text"/>
  <p></p>]]></html>
    </example>
<category name="Attributes"/>
<category name="Forms"/>
<category name="General Attributes"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="val" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="value" type="String">
      <desc>A string of text or an array of strings to set as the value property of each matched element.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, value)" type="Function">
      <desc>A function returning the value to set.</desc>
    </argument>
  </signature>
  <desc>Set the value of each element in the set of matched elements.</desc>
  <longdesc><p>This method is typically used to set the values of form fields. For <code>&lt;select multiple="multiple"&gt;</code> elements, multiple <code>&lt;option&gt;</code>s can be selected by passing in an array.</p>
    <p>The <code>.val()</code> method allows us to set the value by passing in a function. As of jQuery 1.4, the function is passed two arguments, the current element's index and its current value: </p>
<pre>$('input:text.items').val(function(index, value) {
  return value + ' ' + this.className;
});
</pre>
  <p>This example appends the string " items" to the text inputs' values.</p>
  </longdesc>
  <example>
    <desc>Set the value of an input box.</desc>
    <code><![CDATA[
    $("button").click(function () {
      var text = $(this).text();
      $("input").val(text);
    });
]]></code>
                    <css><![CDATA[
  button { margin:4px; cursor:pointer; }
  input { margin:4px; color:blue; }
  ]]></css>
                    <html><![CDATA[<div>
    <button>Feed</button>
    <button>the</button>

    <button>Input</button>
  </div>
  <input type="text" value="click a button" />]]></html>
                </example>
                <example>
                    <desc>Set a single select and a multiple select .</desc>
                    <code><![CDATA[

    $("#single").val("Single2");
    $("#multiple").val(["Multiple2", "Multiple3"]);
    $("input").val(["check1","check2", "radio1" ]);

]]></code>
                    <css><![CDATA[
  body { color:blue; }
  ]]></css>
                    <html><![CDATA[<select id="single">
    <option>Single</option>
    <option>Single2</option>
  </select>

  <select id="multiple" multiple="multiple">
    <option selected="selected">Multiple</option>
    <option>Multiple2</option>

    <option selected="selected">Multiple3</option>
  </select><br/>
  <input type="checkbox" name="checkboxname" value="check1"/> check1
  <input type="checkbox" name="checkboxname" value="check2"/> check2
  <input type="radio"  name="r" value="radio1"/> radio1
  <input type="radio"  name="r" value="radio2"/> radio2]]></html>
                </example>
            <category name="Attributes"/>
<category name="Forms"/>
<category name="General Attributes"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>


  <entry type='method' name="text" return="String">
    <signature>
      <added>1.0</added>
    </signature>
    <desc>Get the combined text contents of each element in the set of matched elements, including their descendants.</desc>
    <longdesc><p>Unlike the <code>.html()</code> method, <code>.text()</code> can be used in both XML and HTML documents. The result of the <code>.text()</code> method is a string containing the combined text of all matched elements. (Due to variations in the HTML parsers in different browsers, the text returned may vary in newlines and other white space.) Consider the following HTML:</p>
<pre>&lt;div class="demo-container"&gt;
  &lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
  &lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list &lt;strong&gt;item&lt;/strong&gt; 2&lt;/li&gt;
  &lt;/ul&gt;
  &lt;/div&gt;
</pre>
      <p>The code <code>$('div.demo-container').text()</code> would produce the following result:</p>
      <p>
        <code>Demonstration Box list item 1 list item 2</code>
      </p>
      <p>The <code>.text()</code> method cannot be used on input elements.  For input field text, use the <a href="/val">.val()</a> method.</p>
      <p>As of jQuery 1.4, the <code>.text()</code> method returns the value of text and CDATA nodes as well as element nodes.</p>
    </longdesc>
    <example>
      <desc>Find the text in the first paragraph (stripping out the html), then set the html of the last paragraph to show it is just text (the red bold is gone).</desc>
      <code><![CDATA[
    var str = $("p:first").text();
    $("p:last").html(str);
]]></code>
<css><![CDATA[
  p { color:blue; margin:8px; }
  b { color:red; }
  ]]></css>
  <html><![CDATA[<p><b>Test</b> Paragraph.</p>

  <p></p>]]></html>
  </example>
<category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="text" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="textString" type="String">
      <desc>A string of text to set as the content of each matched element.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, text)" type="Function">
      <desc>A function returning the text content to set. Receives the index position of the element in the set and the old text value as arguments.</desc>
    </argument>
  </signature>
  
  <desc>Set the content of each element in the set of matched elements to the specified text.</desc>
  <longdesc><p>Unlike the <code>.html()</code> method, <code>.text()</code> can be used in both XML and HTML documents. </p>
  <p>We need to be aware that this method escapes the string provided as necessary so that it will render correctly in HTML. To do so, it calls the DOM method <code>.createTextNode()</code>, which replaces special characters with their HTML entity equivalents (such as <code>&amp;lt;</code> for <code>&lt;</code>).  Consider the following HTML:</p>
				<pre>&lt;div class="demo-container"&gt;
  &lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
  &lt;ul&gt;
    &lt;li&gt;list item 1&lt;/li&gt;
    &lt;li&gt;list &lt;strong&gt;item&lt;/strong&gt; 2&lt;/li&gt;
  &lt;/ul&gt;
&lt;/div&gt;
</pre>
	<p>The code <code>$('div.demo-container').text('&lt;p&gt;This is a test.&lt;/p&gt;');</code> will produce the following DOM output:</p>
	<pre>&lt;div class="demo-container"&gt;
&amp;lt;p&amp;gt;This is a test.&amp;lt;/p&amp;gt;
&lt;/div&gt;</pre>
	<p>It will appear on a rendered page as though the tags were exposed, like this:</p>
	<pre>&lt;p&gt;This is a test&lt;/p&gt;</pre>
	<p>The <code>.text()</code> method cannot be used on input elements.  For input field text, use the <a href="/val">.val()</a> method.</p>
  <p>As of jQuery 1.4, the <code>.text()</code> method allows us to set the text content by passing in a function.</p>
<pre>$('ul li').text(function(index) {
  return 'item number ' + (index + 1);
});</pre>
  <p>Given an unordered list with three <code>&lt;li&gt;</code> elements, this example will produce the following DOM output:</p>
<pre>&lt;ul&gt;
  &lt;li&gt;item number 1&lt;/li&gt;
  &lt;li&gt;item number 2&lt;/li&gt;
  &lt;li&gt;item number 3&lt;/li&gt;
&lt;/ul&gt;
</pre>
</longdesc>
                <example>
                    <desc>Add text to the paragraph (notice the bold tag is escaped).</desc>
                    <code><![CDATA[$("p").text("<b>Some</b> new text.");]]></code>
                    <css><![CDATA[

  p { color:blue; margin:8px; }
  ]]></css>
                    <html><![CDATA[<p>Test Paragraph.</p>]]></html>
                </example>
            <category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>


<entry type='method' name="html" return="String">
  <signature>
    <added>1.0</added>
  </signature>
  <desc>Get the HTML contents of the first element in the set of matched elements.</desc>
  <longdesc>
    <p>This method is not available on XML documents.</p>
    <p>In an HTML document, we can use <code>.html()</code> to get the contents of any element. If the selector expression matches more than one element, only the first one's HTML content is returned. Consider this code:</p>
    <pre>$('div.demo-container').html();</pre>
    <p>In order for the following <code>&lt;div&gt;</code>'s content to be retrieved, it would have to be the first one with <code>class="demo-container"</code> in the document:</p>
    <pre>&lt;div class="demo-container"&gt;
  &lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
&lt;/div&gt;</pre>
  <p>The result would look like this:</p>
  <pre>&lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;</pre>
  <p>This method uses the browser's <code>innerHTML</code> property. Some browsers may not return HTML that exactly replicates the HTML source in an original document. For example, Internet Explorer sometimes leaves off the quotes around attribute values if they contain only alphanumeric characters.</p>
  </longdesc>
  <example>
                    <desc>Click a paragraph to convert it from html to text.</desc>
                    <code><![CDATA[
    $("p").click(function () {
      var htmlStr = $(this).html();
      $(this).text(htmlStr);
    });
]]></code>
                    <css><![CDATA[
  p { margin:8px; font-size:20px; color:blue; 
      cursor:pointer; }
  b { text-decoration:underline; }
  button { cursor:pointer; }
  ]]></css>
                    <html><![CDATA[<p>

    <b>Click</b> to change the <span id="tag">html</span>
  </p>
  <p>

    to a <span id="text">text</span> node.
  </p>
  <p>
    This <button name="nada">button</button> does nothing.
  </p>]]></html>
                </example>
<category name="Attributes"/>
<category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
<entry type='method' name="html" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="htmlString" type="String">
      <desc>A string of HTML to set as the content of each matched element.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, oldhtml)" type="Function">
      <desc>A function returning the HTML content to set. Receives the index position of the element in the set and the old HTML value as arguments. jQuery empties the element before calling the function; use the oldhtml argument to reference the previous content.</desc>
    </argument>
  </signature>
  <desc>Set the HTML contents of each element in the set of matched elements.</desc>
  <longdesc>
    <p>The <code>.html()</code> method is not available in XML documents. </p>
				<p>When we use <code>.html()</code> to set elements' contents, any contents that were in those elements is completely replaced by the new contents. Consider the following HTML:</p>
				<pre>&lt;div class="demo-container"&gt;
  &lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
&lt;/div&gt;</pre>
				<p>We can set the HTML contents of <code>&lt;div class="demo-container"&gt;</code> like so:</p>
				<pre>$('div.demo-container')
  .html('&lt;p&gt;All new content. &lt;em&gt;You bet!&lt;/em&gt;&lt;/p&gt;');</pre>
				<p>That line of code will replace everything inside <code>&lt;div class="demo-container"&gt;</code>:</p>
				<pre>&lt;div class="demo-container"&gt;
  &lt;p&gt;All new content. &lt;em&gt;You bet!&lt;/em&gt;&lt;/p&gt;
&lt;/div&gt;</pre>
<p>As of jQuery 1.4, the <code>.html()</code> method allows us to set the HTML content by passing in a function.</p>
<pre>$('div.demo-container').html(function() {
  var emph = '&lt;em&gt;' + $('p').length + ' paragraphs!&lt;/em&gt;';
  return '&lt;p&gt;All new content for ' + emph + '&lt;/p&gt;';
});</pre>

<p>Given a document with six paragraphs, this example will set the HTML of <code>&lt;div class="demo-container"&gt;</code> to <code>&lt;p&gt;All new content for &lt;em&gt;6 paragraphs!&lt;/em&gt;&lt;/p&gt;</code>.</p>

  <p>This method uses the browser's <code>innerHTML</code> property. Some browsers may not generate a DOM that exactly replicates the HTML source provided. For example, Internet Explorer prior to version 8 will convert all <code>href</code> properties on links to absolute URLs, and Internet Explorer prior to version 9 will not correctly handle HTML5 elements without the addition of a separate <a href="http://code.google.com/p/html5shiv/">compatibility layer</a>.</p>

</longdesc>
                <example>
                    <desc>Add some html to each div.</desc>
                    <code><![CDATA[$("div").html("<span class='red'>Hello <b>Again</b></span>");]]></code>
                    <css><![CDATA[

  .red { color:red; }
  ]]></css>
                    <html><![CDATA[<span>Hello</span>
  <div></div>
  <div></div>
  <div></div>]]></html>
                </example>
                <example>
                    <desc>Add some html to each div then immediately do further manipulations to the inserted html.</desc>
                    <code><![CDATA[

    $("div").html("<b>Wow!</b> Such excitement...");
    $("div b").append(document.createTextNode("!!!"))
              .css("color", "red");

]]></code>
                    <css><![CDATA[
  div { color:blue; font-size:18px; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div></div>
  <div></div>]]></html>
                </example>
            <category name="Attributes"/>
<category name="DOM Insertion, Inside"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>

            <entry type='method' name="map" return="jQuery">
              <signature>
                <added>1.2</added>
                <argument name="callback(index, domElement)" type="Function">
                    <desc>A function object that will be invoked for each element in the current set.</desc>
                </argument>
              </signature>
              <desc>Pass each element in the current matched set through a function, producing a new jQuery object containing the return values.</desc>              
<longdesc><p>As the return value is a jQuery-wrapped array, it's very common to <code>get()</code> the returned object to work with a basic array.</p><p>The <code>.map()</code> method is particularly useful for getting or setting the value of a collection of elements. Consider a form with a set of checkboxes in it:</p>
<pre>
&lt;form method="post" action=""&gt;
  &lt;fieldset&gt;
    &lt;div&gt;
      &lt;label for="two"&gt;2&lt;/label&gt;
      &lt;input type="checkbox" value="2" id="two" name="number[]"&gt;
    &lt;/div&gt;
    &lt;div&gt;
      &lt;label for="four"&gt;4&lt;/label&gt;
      &lt;input type="checkbox" value="4" id="four" name="number[]"&gt;
    &lt;/div&gt;
    &lt;div&gt;
      &lt;label for="six"&gt;6&lt;/label&gt;
      &lt;input type="checkbox" value="6" id="six" name="number[]"&gt;
    &lt;/div&gt;
    &lt;div&gt;
      &lt;label for="eight"&gt;8&lt;/label&gt;
      &lt;input type="checkbox" value="8" id="eight" name="number[]"&gt;
    &lt;/div&gt;
  &lt;/fieldset&gt;
&lt;/form&gt;
</pre>
<p>We can get a comma-separated list of checkbox <code>ID</code>s:</p>
<pre>$(':checkbox').map(function() {
  return this.id;
}).get().join(',');</pre>
<p>The result of this call is the string, <code>"two,four,six,eight"</code>.</p>
<p>Within the callback function, <code>this</code> refers to the current DOM element for each iteration. The function can return an individual data item or an array of data items to be inserted into the resulting set. If an array is returned, the elements inside the array are inserted into the set. If the function returns <code>null</code> or <code>undefined</code>, no element will be inserted.</p>
</longdesc>
                <example>
                    <desc>Build a list of all the values within a form.</desc>
                    <code><![CDATA[
    $("p").append( $("input").map(function(){
      return $(this).val();
    }).get().join(", ") );

]]></code>
                    <css><![CDATA[
  p { color:red; }
  ]]></css>
                    <html><![CDATA[<p><b>Values: </b></p>
  <form>
    <input type="text" name="name" value="John"/>

    <input type="text" name="password" value="password"/>
    <input type="text" name="url" value="http://ejohn.org/"/>

  </form>]]></html>
                </example>
                <example>
                    <desc>A contrived example to show some functionality.</desc>
                    <code><![CDATA[
    var mappedItems = $("li").map(function (index) {
      var replacement = $("<li>").text($(this).text()).get(0);
      if (index == 0) {
        // make the first item all caps
        $(replacement).text($(replacement).text().toUpperCase());
      } else if (index == 1 || index == 3) {
        // delete the second and fourth items
        replacement = null;
      } else if (index == 2) {
        // make two of the third item and add some text
        replacement = [replacement,$("<li>").get(0)];
        $(replacement[0]).append("<b> - A</b>");
        $(replacement[1]).append("Extra <b> - B</b>");
      }

      // replacement will be an dom element, null, 
      // or an array of dom elements
      return replacement;
    });
    $("#results").append(mappedItems);

]]></code>
                    <css><![CDATA[
  body { font-size:16px; }
  ul { float:left; margin:0 30px; color:blue; }
  #results { color:red; }
  ]]></css>
                    <html><![CDATA[<ul>
    <li>First</li>
    <li>Second</li>
    <li>Third</li>

    <li>Fourth</li>
    <li>Fifth</li>
  </ul>
  <ul id="results">

  </ul>]]></html>
                </example>


    <example>
                    <desc>Equalize the heights of the divs.</desc>
                    <code><![CDATA[
$.fn.equalizeHeights = function(){
  return this.height( Math.max.apply(this, $(this).map(function(i,e){ return $(e).height() }).get() ) )
}
$('input').click(function(){
  $('div').equalizeHeights();
});

]]></code>
                    <css><![CDATA[
div { width: 40px; float:left; }
input { clear:left}
  ]]></css>
                    <html><![CDATA[

<input type="button" value="equalize div heights">

<div style="background:red; height: 40px; "></div>
<div style="background:green; height: 70px;"></div>
<div style="background:blue; height: 50px; "></div>

]]></html>
                </example>
               
            <category name="Filtering"/>
<category name="Version 1.2"/>
</entry>
<entry type='method' name="is" return="Boolean">
  <signature>
    <added>1.0</added>
    <argument name="selector" type="Selector">
      <desc>A string containing a selector expression to match elements against.</desc>
    </argument>
  </signature>
  <desc>Check the current matched set of elements against a selector and return true if at least one of these elements matches the selector.</desc>
                <longdesc><p>Unlike the other filtering and traversal methods, <code>.is()</code> does not create a new jQuery object. Instead, it allows us to test the contents of a jQuery object without modification. This is often useful inside callbacks, such as event handlers.</p>
<p>Suppose we have a list, with two of its items containing a child element:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;list &lt;strong&gt;item 1&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;span&gt;list item 2&lt;/span&gt;&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can attach a click handler to the &lt;ul&gt; element, and then limit the code to be triggered only when a list item itself, not one of its children, is clicked:</p>
<pre>$('ul').click(function(event) {
  if ($(event.target).is('li') ) {
    $(event.target).css('background-color', 'red');
  }
});</pre>
<p>Now, when the user clicks on the word list in the first item or anywhere in the third item, the clicked list item will be given a red background. However, when the user clicks on item 1 in the first item or anywhere in the second item, nothing will occur, because in those cases the target of the event would be <code>&lt;strong&gt;</code> or <code>&lt;span&gt;</code>, respectively.
</p></longdesc>
                <example>
                    <desc>Shows a few ways is() can be used inside an event handler.</desc>
                    <code><![CDATA[
    $("div").one('click', function () {
      if ($(this).is(":first-child")) {
        $("p").text("It's the first div.");
      } else if ($(this).is(".blue,.red")) {
        $("p").text("It's a blue or red div.");
      } else if ($(this).is(":contains('Peter')")) {
        $("p").text("It's Peter!");
      } else {
        $("p").html("It's nothing <em>special</em>.");
      }
      $("p").hide().slideDown("slow");
      $(this).css({"border-style": "inset", cursor:"default"});
    });

]]></code>
                    <css><![CDATA[
  div { width:60px; height:60px; margin:5px; float:left;
        border:4px outset; background:green; text-align:center; 
        font-weight:bolder; cursor:pointer; }
  .blue { background:blue; }
  .red { background:red; }
  span { color:white; font-size:16px; }
  p { color:red; font-weight:bolder; background:yellow; 
      margin:3px; clear:left; display:none; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div class="blue"></div>
  <div></div>
  <div class="red"></div>

  <div><br/><span>Peter</span></div>
  <div class="blue"></div>
  <p>&nbsp;</p>]]></html>
                </example>
                <example>
                    <desc>Returns true, because the parent of the input is a form element</desc>
                    <code><![CDATA[

    var isFormParent = $("input[type='checkbox']").parent().is("form")
    $("div").text("isFormParent = " + isFormParent);
]]></code>
                    <css><![CDATA[div { color:red; }]]></css>
                    <html><![CDATA[<form><input type="checkbox" /></form>

  <div></div>]]></html>
                </example>
                <example>
                    <desc>Returns false, because the parent of the input is a p element</desc>
                    <code><![CDATA[
    var isFormParent = $("input[type='checkbox']").parent().is("form")
    $("div").text("isFormParent = " + isFormParent);
]]></code>
                    <css><![CDATA[div { color:red; }]]></css>
                    <html><![CDATA[<form><p><input type="checkbox" /></p></form>

  <div></div>]]></html>
                </example>
            <category name="Filtering"/>
<category name="Version 1.0"/>
</entry>
            <entry type='method' name="eq" return="jQuery">
              <signature>
                <added>1.1.2</added>
                <argument name="index" type="Integer">
                    <desc>An integer indicating the 0-based position of the element. </desc>
                </argument>
              </signature>
              <signature>
                <added>1.4</added>
                <argument name="-index" type="Integer">
                    <desc>An integer indicating the position of the element, counting backwards  from the last element in the set. </desc>
                </argument>
              </signature>
              <desc>Reduce the set of matched elements to the one at the specified index.</desc>
              <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.eq()</code> method constructs a new jQuery object from one element within that set. The supplied index identifies the position of this element in the set. </p>
<p>Consider a page with a simple list on it:</p>
<pre>
  &lt;ul&gt;
    &lt;li&gt;list item 1&lt;/li&gt;
    &lt;li&gt;list item 2&lt;/li&gt;
    &lt;li&gt;list item 3&lt;/li&gt;
    &lt;li&gt;list item 4&lt;/li&gt;
    &lt;li&gt;list item 5&lt;/li&gt;
  &lt;/ul>
</pre>
<p>We can apply this method to the set of list items:</p>
<pre>
  $('li').eq(2).css('background-color', 'red');
</pre>
<p>The result of this call is a red background for item 3. Note that the supplied index is zero-based, and refers to the position of the element within the jQuery object, not within the DOM tree.</p>
<p>Providing a negative number indicates a position starting from the end of the set, rather than the beginning. For example:</p>
<pre>
  $('li').eq(-2).css('background-color', 'red');
</pre>
<p>This time list item 4 is turned red, since it is two from the end of the set.</p>
<p>If an element cannot be found at the specified zero-based index, the method constructs a new jQuery object with an empty set and a <code>length</code> property of 0. </p>
<pre>
  $('li').eq(5).css('background-color', 'red');
</pre>
<p>Here, none of the list items is turned red, since <code>.eq(5)</code> indicates the sixth of five list items.</p>
</longdesc>
                <example>
                    <desc>Turn the div with index 2 blue by adding an appropriate class.</desc>
                    <code><![CDATA[

    $("body").find("div").eq(2).addClass("blue");
]]></code>
                    <css><![CDATA[
  div { width:60px; height:60px; margin:10px; float:left;
        border:2px solid blue; }
  .blue { background:blue; }
  ]]></css>
                    <html><![CDATA[<div></div>
  <div></div>
  <div></div>

  <div></div>
  <div></div>
  <div></div>]]></html>
                </example>
            <category name="Filtering"/>
<category name="Version 1.1.2"/>
</entry>
            <entry type='method' name="filter" return="jQuery">
                <signature>
                  <added>1.0</added>
                  <argument name="selector" type="Selector">
                    <desc>A string containing a selector expression to match the current set of elements against.</desc>
                  </argument>
                </signature>
                <signature>
                  <added>1.0</added>
                  <argument name="function(index)" type="Function">
                    <desc>A function used as a test for each element in the set. <code>this</code> is the current DOM element.</desc>
                  </argument>
                </signature>
                <signature>
                  <added>1.4</added>
                  <argument name="element" type="Element">
                    <desc>An element to match the current set of elements against.</desc>
                  </argument>
                </signature>
                <signature>
                  <added>1.4</added>
                  <argument name="jQuery object" type="Object">
                    <desc>An existing jQuery object to match the current set of elements against.</desc>
                  </argument>
                </signature>
                <desc>Reduce the set of matched elements to those that match the selector or pass the function's test. </desc>
                <longdesc><p>Given a jQuery object that represents a set of DOM elements, the <code>.filter()</code> method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; all elements matching the selector will be included in the result.</p>
<p>Consider a page with a simple list on it:</p>
&lt;ul&gt;
  &lt;li&gt;list item 1&lt;/li&gt;
  &lt;li&gt;list item 2&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
  &lt;li&gt;list item 6&lt;/li&gt;
&lt;/ul&gt;
<p>We can apply this method to the set of list items:</p>
<pre>
  $('li').filter(':even').css('background-color', 'red');
</pre>
<p>The result of this call is a red background for items 1, 3, and 5, as they match the selector (recall that <code>:even</code> and <code>:odd</code> use 0-based indexing).</p>
<h4 id="using-filter-function">Using a Filter Function</h4>
<p>The second form of this method allows us to filter elements against a function rather than a selector. For each element, if the function returns <code>true</code>, the element will be included in the filtered set; otherwise, it will be excluded. Suppose we have a somewhat more involved HTML snippet:</p>
<pre>
&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;list&lt;/strong&gt; item 1 -
    one strong tag&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;list&lt;/strong&gt; item &lt;strong&gt;2&lt;/strong&gt; -
    two &lt;span&gt;strong tags&lt;/span&gt;&lt;/li&gt;
  &lt;li&gt;list item 3&lt;/li&gt;
  &lt;li&gt;list item 4&lt;/li&gt;
  &lt;li&gt;list item 5&lt;/li&gt;
  &lt;li&gt;list item 6&lt;/li&gt;
&lt;/ul&gt;
</pre>
<p>We can select the list items, then filter them based on their contents:</p>
<pre>
$('li').filter(function(index) {
  return $('strong', this).length == 1;
}).css('background-color', 'red');
</pre>
<p>This code will alter the first list item only, as it contains exactly one <code>&lt;strong&gt;</code> tag. Within the filter function, <code>this</code> refers to each DOM element in turn. The parameter passed to the function tells us the index of that DOM element within the set matched by the jQuery object.</p>
<p>We can also take advantage of the <code>index</code> passed through the function, which indicates the 0-based position of the element within the unfiltered set of matched elements:</p>
<pre>
$('li').filter(function(index) {
  return index % 3 == 2;
}).css('background-color', 'red');
</pre>
<p>This alteration to the code will cause the third and sixth list items to be highlighted, as it uses the modulus operator (<code>%</code>) to select every item with an <code>index</code> value that, when divided by 3, has a remainder of <code>2</code>.</p>
</longdesc>
                <example>
                    <desc>Change the color of all divs then put a border around only some of them.</desc>
                    <code><![CDATA[

    $("div").css("background", "#c8ebcc")
            .filter(".middle")
            .css("border-color", "red");
]]></code>
                    <css><![CDATA[
  div { width:60px; height:60px; margin:5px; float:left; 
        border:2px white solid;}
  ]]></css>
                    <html><![CDATA[<div></div>

  <div class="middle"></div>
  <div class="middle"></div>
  <div class="middle"></div>
  <div class="middle"></div>

  <div></div>]]></html>
                </example>
                <example>
                    <desc>Selects all paragraphs and removes those without a class "selected".</desc>
                    <code><![CDATA[$("p").filter(".selected")]]></code>
                </example>
                <example>
                    <desc>Selects all paragraphs and removes those that aren't of class "selected" or the first one.</desc>
                    <code><![CDATA[$("p").filter(".selected, :first")]]></code>
                </example>
                <example>
                    <desc>Change the color of all divs then put a border to specific ones.</desc>
                    <code><![CDATA[
    $("div").css("background", "#b4b0da")
            .filter(function (index) {
                  return index == 1 || $(this).attr("id") == "fourth";
                })
            .css("border", "3px double red");

]]></code>
                    <css><![CDATA[
  div { width:60px; height:60px; margin:5px; float:left; 
        border:3px white solid; }
  ]]></css>
                    <html><![CDATA[<div id="first"></div>
  <div id="second"></div>
  <div id="third"></div>

  <div id="fourth"></div>
  <div id="fifth"></div>
  <div id="sixth"></div>]]></html>
                </example>
                <example>
                    <desc>Remove all elements that have a descendant ol element</desc>
                    <code><![CDATA[$("div").filter(function(index) {
   return $("ol", this).length == 0;
 });]]></code>
                </example>
            <category name="Filtering"/>
<category name="Version 1.0"/>
</entry>

  <entry type='method' name="toggleClass" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="className" type="String">
        <desc>One or more class names (separated by spaces) to be toggled for each element in the matched set.</desc>
      </argument>
    </signature>
    <signature>
        <added>1.3</added>
        <argument name="className" type="String">
            <desc>One or more class names (separated by spaces) to be toggled for each element in the matched set.</desc>
        </argument>
        <argument name="switch" type="Boolean">
            <desc>A boolean value to determine whether the class should be added or removed.</desc>
        </argument>
    </signature>
    <signature>
        <added>1.4</added>
        <argument name="function(index, class)" type="Function">
            <desc>A function that returns class names to be toggled in the class attribute of each element in the matched set. Receives the index position of the element in the set and the old class value as arguments.</desc>
        </argument>
        <argument name="switch" optional="true" type="Boolean">
            <desc>A boolean value to determine whether the class should be added or removed.</desc>
        </argument>
    </signature>
    <desc>Add or remove one or more classes from each element in the set of matched elements, depending on either the class's presence or the value of the switch argument.</desc>
    <longdesc><p>This method takes one or more class names as its parameter. In the first version, if an element in the matched set of elements already has the class, then it is removed; if an element does not have the class, then it is added. For example, we can apply <code>.toggleClass()</code> to a simple <code>&lt;div&gt;</code>: </p>
      <pre>&lt;div class="tumble"&gt;Some text.&lt;/div&gt;
      </pre>
      <p>The first time we apply <code>$('div.tumble').toggleClass('bounce')</code>, we get the following:</p>
      <pre>&lt;div class="tumble bounce"&gt;Some text.&lt;/div&gt;
      </pre>
      <p>The second time we apply <code>$('div.tumble').toggleClass('bounce')</code>, the <code>&lt;div&gt;</code> class is returned to the single <code>tumble</code> value:</p>
      <pre>&lt;div class="tumble"&gt;Some text.&lt;/div&gt;</pre>
      <p>Applying <code>.toggleClass('bounce spin')</code> to the same <code>&lt;div&gt;</code> alternates between <code>&lt;div class="tumble bounce spin"&gt;</code> and <code>&lt;div class="tumble"&gt;</code>.</p>
      <p>The second version of <code>.toggleClass()</code> uses the second parameter for determining whether the class should be added or removed. If this parameter's value is <code>true</code>, then the class is added; if <code>false</code>, the class is removed. In essence, the statement:</p>
  <pre>$('#foo').toggleClass(className, addOrRemove);</pre>
  <p>is equivalent to:</p>
  <pre>if (addOrRemove) {
    $('#foo').addClass(className);
  }
  else {
    $('#foo').removeClass(className);
  }
  </pre>
  <p>As of jQuery 1.4, the <code>.toggleClass()</code> method allows us to indicate the class name to be toggled by passing in a function.</p>
<pre>$('div.foo').toggleClass(function() {
  if ($(this).parent().is('.bar')) {
    return 'happy';
  } else {
    return 'sad';
  }
});</pre>
  <p>This example will toggle the <code>happy</code> class for <code>&lt;div class="foo"&gt;</code> elements if their parent element has a class of <code>bar</code>; otherwise, it will toggle the <code>sad</code> class.</p>
  
      </longdesc>
      <example>
        <desc>Toggle the class 'highlight' when a paragraph is clicked.</desc>
        <code><![CDATA[
    $("p").click(function () {
      $(this).toggleClass("highlight");
    });
]]></code>
                    <css><![CDATA[

  p { margin: 4px; font-size:16px; font-weight:bolder; 
      cursor:pointer; }
  .blue { color:blue; }
  .highlight { background:yellow; }
  ]]></css>
  <html><![CDATA[<p class="blue">Click to toggle</p>
  <p class="blue highlight">highlight</p>
  <p class="blue">on these</p>
  <p class="blue">paragraphs</p>]]></html>
    </example>
    <example>
        <desc>Add the "highlight" class to the clicked paragraph on every third click of that paragraph, remove it every first and second click.</desc>
        <code><![CDATA[
var count = 0;
$("p").each(function() {
  var $thisParagraph = $(this);
  var count = 0;
  $thisParagraph.click(function() {
    count++;
    $thisParagraph.find("span").text('clicks: ' + count);
    $thisParagraph.toggleClass("highlight", count % 3 == 0);
  });
});

]]></code>
  <css><![CDATA[
  p { margin: 4px; font-size:16px; font-weight:bolder; 
      cursor:pointer; }
  .blue { color:blue; }
  .highlight { background:red; }
  ]]></css>
                    <html><![CDATA[<p class="blue">Click to toggle (<span>clicks: 0</span>)</p>
  <p class="blue highlight">highlight (<span>clicks: 0</span>)</p>
  <p class="blue">on these (<span>clicks: 0</span>)</p>

  <p class="blue">paragraphs (<span>clicks: 0</span>)</p>]]></html>
                </example>
            <category name="Attributes"/>
<category name="CSS"/>
<category name="Class Attribute"/>
<category name="Version 1.0"/>
<category name="Version 1.3"/>
<category name="Version 1.4"/>
</entry>

            <entry type='method' name="removeClass" return="jQuery">
                <signature>
                    <added>1.0</added>
                    <argument name="className" optional="true" type="String">
                        <desc>A class name to be removed from the class attribute of each matched element.</desc>
                    </argument>
                </signature>
                <signature>
                  <added>1.4</added>
                  <argument name="function(index, class)" type="Function">
                    <desc>A function returning one or more space-separated class names to be removed. Receives the index position of the element in the set and the old class value as arguments.</desc>
                  </argument>
                </signature>

                <desc>Remove a single class, multiple classes, or all classes from each element in the set of matched elements.</desc>
                <longdesc><p>If a class name is included as a parameter, then only that class will be removed from the set of matched elements. If no class names are specified in the parameter, all classes will be removed.</p>
				<p>More than one class may be removed at a time, separated by a space, from the set of matched elements, like so:</p>
				<pre>$('p').removeClass('myClass yourClass')
</pre>
				<p>This method is often used with <code>.addClass()</code> to switch elements' classes from one to another, like so:</p>
				<pre>$('p').removeClass('myClass noClass').addClass('yourClass');
</pre>
				<p>Here, the <code>myClass</code> and <code>noClass</code> classes are removed from all paragraphs, while <code>yourClass</code> is added.</p>
				<p>To replace all existing classes with another class, we can use <code>.attr('class', 'newClass')</code> instead.</p>
        <p>As of jQuery 1.4, the <code>.removeClass()</code> method allows us to indicate the class to be removed by passing in a function.</p>
        <pre>$('li:last').removeClass(function() {
          return $(this).prev().attr('class');
        });</pre>
        <p>This example removes the class name of the penultimate <code>&lt;li&gt;</code> from the last <code>&lt;li&gt;</code>.</p>
</longdesc>
                <example>
                    <desc>Remove the class 'blue' from the matched elements.</desc>
                    <code><![CDATA[$("p:even").removeClass("blue");]]></code>
                    <css><![CDATA[

  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p class="blue under">Hello</p>
  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>

  <p class="blue under">Goodbye</p>]]></html>
                </example>
                <example>
                    <desc>Remove the class 'blue' and 'under' from the matched elements.</desc>
                    <code><![CDATA[$("p:odd").removeClass("blue under");]]></code>
                    <css><![CDATA[
  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p class="blue under">Hello</p>

  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>
  <p class="blue under">Goodbye</p>]]></html>
                </example>
                <example>
                    <desc>Remove all the classes from the matched elements.</desc>
                    <code><![CDATA[$("p:eq(1)").removeClass();]]></code>
                    <css><![CDATA[

  p { margin: 4px; font-size:16px; font-weight:bolder; }
  .blue { color:blue; }
  .under { text-decoration:underline; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p class="blue under">Hello</p>
  <p class="blue under highlight">and</p>
  <p class="blue under">then</p>

  <p class="blue under">Goodbye</p>]]></html>
                </example>
            <category name="Attributes"/>
<category name="CSS"/>
<category name="Class Attribute"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>
            <entry type='method' name="hasClass" return="Boolean">
                <signature>
                    <added>1.2</added>
                    <argument name="className" type="String">
                        <desc>The class name to search for.</desc>
                    </argument>
                </signature>
                <desc>Determine whether any of the matched elements are assigned the given class.</desc>
                <longdesc><p>Elements may have more than one class assigned to them. In HTML, this is represented by separating the class names with a space:</p>
		<pre>&lt;div id="mydiv" class="foo bar"&gt;&lt;/div&gt;</pre>
		<p>The <code>.hasClass()</code> method will return <code>true</code> if the class is assigned to an element, even if other classes also are. For example, given the HTML above, the following will return <code>true</code>:</p>
		<pre>$('#mydiv').hasClass('foo')</pre>
		<p>as would:</p>
		<pre>$('#mydiv').hasClass('bar')</pre></longdesc>
                <example>
                    <desc>Looks for the class 'selected' on the matched elements.</desc>
                    <code><![CDATA[$("div#result1").append($("p:first").hasClass("selected").toString());
$("div#result2").append($("p:last").hasClass("selected").toString());
$("div#result3").append($("p").hasClass("selected").toString());]]></code>
                    <css><![CDATA[

  p { margin: 8px; font-size:16px; }
  .selected { color:red; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p class="selected">Goodbye</p>
  <div id="result1">First paragraph has selected class: </div>

  <div id="result2">Last paragraph has selected class: </div>
  <div id="result3">Some paragraph has selected class: </div>]]></html>
                </example>
            <category name="Attributes"/>
<category name="CSS"/>
<category name="Class Attribute"/>
<category name="Version 1.2"/>
</entry>
<entry type='method' name="removeAttr" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="attributeName" type="String">
      <desc>An attribute to remove.</desc>
    </argument>
  </signature>
  <desc>Remove an attribute from each element in the set of matched elements.</desc>
  <longdesc><p>The <code>.removeAttr()</code> method uses the JavaScript <code>removeAttribute()</code> function, but it has the advantage of being able to be called directly on a jQuery object and it accounts for different attribute naming across browsers.</p></longdesc>

  <example>
    <desc>Clicking the button enables the input next to it.</desc>
    <code><![CDATA[
$("button").click(function () {
  $(this).next().removeAttr("disabled")
  .focus()
  .val("editable now");
});
]]></code>
      <html><![CDATA[<button>Enable</button>
<input type="text" disabled="disabled" value="can't edit this" />]]></html>
    </example>
  <category name="Attributes"/>
<category name="General Attributes"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>

  <entry type='method' name="attr" return="String">
    <signature>
      <added>1.0</added>
      <argument name="attributeName" type="String">
        <desc>The name of the attribute to get.</desc>
      </argument>
    </signature>
    <desc>Get the value of an attribute for the first element in the set of matched elements.</desc>
    <longdesc><p>It's important to note that the <code>.attr()</code> method gets the attribute value for only the <em>first</em> element in the matched set. To get the value for each element individually, we need to rely on a looping construct such as jQuery's <code>.each()</code> or <code>.map()</code> method.</p>
      <p>Using jQuery's <code>.attr()</code> method to get the value of an element's attribute has two main benefits:</p>
      <ol>
        <li><strong>Convenience</strong>: It can be called directly on a jQuery object and chained to other jQuery methods.</li>
        <li><strong>Cross-browser consistency</strong>: Some attributes have inconsistent naming from browser to browser. Furthermore, the values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The <code>.attr()</code> method reduces such inconsistencies. </li>
      </ol>
    <p>If we try to get the value of an attribute that has not been set, the <code>.attr()</code> method returns <code>undefined</code>.</p>
    </longdesc>
    <example>
                    <desc>Finds the title attribute of the first &lt;em&gt; in the page.</desc>
                    <code><![CDATA[var title = $("em").attr("title");
    $("div").text(title);
]]></code>
                    <css><![CDATA[em { color:blue; font-weight;bold; }
  div { color:red; }]]></css>
                    <html><![CDATA[<p>
    Once there was a <em title="huge, gigantic">large</em> dinosaur...
  </p>

  The title of the emphasis is:<div></div>]]></html>
                </example>
            <category name="Attributes"/>
<category name="General Attributes"/>
<category name="Version 1.0"/>
<category name="Version 1.1"/>
</entry>
            <entry type='method' name="attr" return="jQuery">
				<signature>
					<added>1.0</added>
	                <argument name="attributeName" type="String">
	                    <desc>The name of the attribute to set.</desc>
	                </argument>
	                <argument name="value" type="String,Number">
	                    <desc>A value to set for the attribute.</desc>
	                </argument>
		</signature>
		<signature>
			<added>1.0</added>
	                <argument name="map" type="Map">
	                    <desc>A map of attribute-value pairs to set.</desc>
	                </argument>
		</signature>
		<signature>
			<added>1.1</added>
			<argument name="attributeName" type="String">
	                    <desc>The name of the attribute to set.</desc>
	                </argument>
	                <argument name="function(index, attr)" type="Function">
	                    <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old attribute value as arguments.</desc>
	                </argument>
		</signature>
		<desc>Set one or more attributes for the set of matched elements.</desc>
		<longdesc><p>The <code>.attr()</code> method is a convenient and powerful way to set the value of attributes—especially when setting multiple attributes or using values returned by a function. Let's consider the following image:</p>
			<pre>&lt;img id="greatphoto" src="brush-seller.jpg" alt="brush seller" /&gt;</pre>
			<h4>Setting a simple attribute</h4>
			<p>We can change the <code>alt</code> attribute by simply passing the name of the attribute and its new value to the <code>.attr()</code> method:</p>
			<pre>$('#greatphoto').attr('alt', 'Beijing Brush Seller');</pre>
			<p>We can <em>add</em> an attribute the same way:</p>
			<pre>$('#greatphoto')
  .attr('title', 'Photo by Kelly Clark');</pre>

			<h4>Setting several attributes at once</h4>
			<p>To change the <code>alt</code> attribute and add the <code>title</code> attribute at the same time, we can pass both sets of names and values into the method at once using a map (JavaScript object literal). Each key-value pair in the map adds or modifies an attribute:</p>
			<pre>$('#greatphoto').attr({
  alt: 'Beijing Brush Seller',
  title: 'photo by Kelly Clark'
});</pre>
			<p>When setting multiple attributes, the quotes around attribute names are optional.</p>
			<p><strong>WARNING</strong> When setting the 'class' attribute, you must always use quotes!</p>

			<h4>Computed attribute values</h4>
			<p>By using a function to set attributes, we can compute the value based on other properties of the element. For example, we could concatenate a new value with an existing value:</p>
			<pre>$('#greatphoto').attr('title', function() {
  return this.alt + ' - photo by Kelly Clark'
});</pre>
			<p>This use of a function to compute attribute values can be particularly useful when we modify the attributes of multiple elements at once.</p></longdesc>
                <example>
                    <desc>Set some attributes for all &lt;img&gt;s in the page.</desc>
                    <code><![CDATA[$("img").attr({ 
          src: "/images/hat.gif",
          title: "jQuery",
          alt: "jQuery Logo"
        });
    $("div").text($("img").attr("alt"));]]></code>
                    <css><![CDATA[
  img { padding:10px; }
  div { color:red; font-size:24px; }]]></css>
                    <html><![CDATA[<img />
  <img />
  <img />

  <div><B>Attribute of Ajax</B></div>]]></html>
                </example>
                <example>
                    <desc>Disables buttons greater than the 1st button.</desc>
                    <code><![CDATA[$("button:gt(1)").attr("disabled","disabled");]]></code>
                    <css><![CDATA[button { margin:10px; }
  ]]></css>
                    <html><![CDATA[<button>0th Button</button>
  <button>1st Button</button>
  <button>2nd Button</button>]]></html>
                </example>
                <example>
                    <desc>Sets id for divs based on the position in the page.</desc>
                    <code><![CDATA[$("div").attr("id", function (arr) {
          return "div-id" + arr;
        })
        .each(function () {
          $("span", this).html("(ID = '<b>" + this.id + "</b>')");
        });]]></code>
                    <css><![CDATA[
  div { color:blue; }
  span { color:red; }
  b { font-weight:bolder; }
  ]]></css>
                    <html><![CDATA[<div>Zero-th <span></span></div>
  <div>First <span></span></div>
  <div>Second <span></span></div>]]></html>
                </example>
                <example>
                    <desc>Sets src attribute from title attribute on the image.</desc>
                    <code><![CDATA[$("img").attr("src", function() { 
          return "/images/" + this.title; 
        });
]]></code>
                    <html><![CDATA[<img title="hat.gif"/>]]></html>
                </example>
            <category name="Attributes"/>
<category name="General Attributes"/>
<category name="Version 1.0"/>
<category name="Version 1.1"/>
</entry>
          
<entry type='method' name="addClass" return="jQuery">
  <signature>
    <added>1.0</added>
    <argument name="className" type="String">
      <desc>One or more class names to be added to the class attribute of each matched element.</desc>
    </argument>
  </signature>
  <signature>
    <added>1.4</added>
    <argument name="function(index, class)" type="Function">
      <desc>A function returning one or more space-separated class names to be added. Receives the index position of the element in the set and the old class value as arguments.</desc>
    </argument>
  </signature>
  <desc>Adds the specified class(es) to each of the set of matched elements.</desc>
  <longdesc><p>It's important to note that this method does not replace a class. It simply adds the class, appending it to any which may already be assigned to the elements.</p>
  <p>More than one class may be added at a time, separated by a space, to the set of matched elements, like so:</p>
  <pre>$('p').addClass('myClass yourClass');</pre>
  <p>This method is often used with <code>.removeClass()</code> to switch elements' classes from one to another, like so:</p>
  <pre>$('p').removeClass('myClass noClass').addClass('yourClass');</pre>
  <p>Here, the <code>myClass</code> and <code>noClass</code> classes are removed from all paragraphs, while <code>yourClass</code> is added.</p>
<p>As of jQuery 1.4, the <code>.addClass()</code> method allows us to set the class name by passing in a function.</p>
<pre>$('ul li:last').addClass(function() {
  return 'item-' + $(this).index();
});</pre>
<p>Given an unordered list with five <code>&lt;li&gt;</code> elements, this example adds the class "item-4" to the last <code>&lt;li&gt;</code>.</p>


</longdesc>
                <example>
                    <desc>Adds the class 'selected' to the matched elements.</desc>
                    <code><![CDATA[$("p:last").addClass("selected");]]></code>
                    <css><![CDATA[

  p { margin: 8px; font-size:16px; }
  .selected { color:blue; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>and</p>
  <p>Goodbye</p>]]></html>
                </example>
                <example>
                    <desc>Adds the classes 'selected' and 'highlight' to the matched elements.</desc>
                    <code><![CDATA[$("p:last").addClass("selected highlight");]]></code>
                    <css><![CDATA[

  p { margin: 8px; font-size:16px; }
  .selected { color:red; }
  .highlight { background:yellow; }
  ]]></css>
                    <html><![CDATA[<p>Hello</p>
  <p>and</p>
  <p>Goodbye</p>]]></html>
                </example>
            <category name="Attributes"/>
<category name="CSS"/>
<category name="Class Attribute"/>
<category name="Version 1.0"/>
<category name="Version 1.4"/>
</entry>  </entries>
    <plugins>
    <entry type='method' name="jQuery.tmpl" return="jQuery" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
  <added>1.4.3</added>
  <argument name="template" type="String, Element, jQuery">
    <desc>The HTML markup or text to use as a template.</desc>
  </argument>
  <argument name="data" type="Object" optional="true">
    <desc>The data to render. This can be any JavaScript type, including Array or Object.</desc>
  </argument>
  <argument name="options" type="Options" optional="true">
    <desc>An optional map of user-defined key-value pairs. Extends the <code>tmplItem</code> data structure, available to the template during rendering.</desc>
  </argument>
</signature>
<desc>Render the specified HTML content as a template, using the specified data.</desc>
<longdesc>
<p>Example:</p> 
<pre>$.tmpl( "&lt;li&gt;${Name}&lt;/li&gt;", { "Name" : "John Doe" })</pre>

<p>The <code>template</code> parameter can be any of the following: </p>

<ul>
<li>A string containing markup.</li>
<li>An HTML element (or jQuery object that wraps an element) whose content is to be used as the template.</li>
<li>A string corresponding to the name of a named template (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
<li>A compiled-template function (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
</ul>
<p>
If <code>data</code> is an array, the template is rendered once for each data item in the array. If <code>data</code> is an object, or if the <code>data</code> parameter is missing or null, a single template item is rendered.
</p>
<p>
The return value is a jQuery collection of elements made up of the rendered template items (one for each data item in the array). If the template contains only one top-level element, then there will be one element for each data item in the array.
</p>
<p>
You can insert the rendered template items into the HTML DOM using <code>.appendTo</code>, <code>.prependTo</code>, <code>.insertAfter</code> or <code>.insertBefore</code>, as in the following example:
</p>
<pre>$.tmpl( myTemplate, myData ).appendTo( "#target" );</pre>

<p>See also <a href="http://api.jquery.com/tmpl">.tmpl()</a>.</p>

<h4 id="desc-example">Example</h4>
<p>
The following example shows how to use <code>jQuery.tmpl()</code> to render local data, using a template provided as a string:
</p>
<pre>&lt;script type="text/javascript"&gt;
  var movies = [
      { Name: "The Red Violin", ReleaseYear: "1998" },
      { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
      { Name: "The Inheritance", ReleaseYear: "1976" }
  ];

  var markup = "&lt;li&gt;&lt;b&gt;${Name}&lt;/b&gt; (${ReleaseYear})&lt;/li&gt;";

  // Compile the markup as a named template
  $.template( "movieTemplate", markup );

  // Render the template with the movies data and insert
  // the rendered HTML under the "movieList" element
  $.tmpl( "movieTemplate", movies )
      .appendTo( "#movieList" );
&lt;/script&gt;

&lt;ul id="movieList"&gt;&lt;/ul&gt;
</pre>

<h4 id="using-remote-data">Using Remote Data</h4>
<p>
Typically the data is not local and is instead obtained using an Ajax request to a remote service or page, as in the following example: 
</p>
<pre>var markup = "&lt;li&gt;&lt;b&gt;${Name}&lt;/b&gt; (${ReleaseYear})&lt;/li&gt;";

// Compile the markup as a named template
$.template( "movieTemplate", markup );

$.ajax({
  dataType: "jsonp",
  url: moviesServiceUrl,
  jsonp: "$callback",
  success: showMovies
});

// Within the callback, use .tmpl() to render the data.
function showMovies( data ) {
  // Render the template with the "movies" data and insert
  // the rendered HTML under the &#39;movieList&#39; element
  $.tmpl( "movieTemplate", data )
    .appendTo( "#movieList" );
}
</pre>

<h4 id="markup-for-template">The Markup for the Template </h4>
<p>
You can get the markup for the template from inline markup in the page, or from a string (possibly computed, or obtained remotely). For an example of how to use inline markup, see <a href="http://api.jquery.com/tmpl">.tmpl()</a>. 
</p>

<h4 id="caching-template">Caching the Template</h4>
<p>
When a template is rendered, the markup is first converted into a compiled-template function. Every time <code>$.tmpl( markup , myData ).appendTo( "#target" )</code> is called, the template is recompiled. If the same template is to be used more than once for rendering data, you should ensure that the compiled template is cached. To cache the template when using markup that is obtained from a string (rather than from inline markup in the page), use 
<code>$.template( name, markup )</code> to create a named template for reuse. See <a href="http://api.jquery.com/jquery.template">jQuery.template()</a>. 
</p>

<h4 id="tags-expressions-variables">Template Tags, Expressions, and Template Variables</h4>
<p>Template tags such as the <code>${}</code> tag can used within jQuery templates in addition to text and HTML markup to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. Template tags can render content based on the values of data item fields or template variables such as <code>$item</code> (corresponding to the template item), as well as expressions and function calls. See the documentation topics for each template tag: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. </p>

<h4 id="options-items">The <code>options</code> Parameter, and Template Items</h4>
<p>Each template item (the result of rendering a data item with the template) is associated with a <code>tmplItem</code> data structure, which can be accessed using <a href="http://api.jquery.com/jquery.tmplitem">jQuery.tmplItem()</a> and <a href="http://api.jquery.com/tmplitem">.tmplItem()</a>, or the <code>$item</code> template variable. Any fields or anonomyous methods passed in with the <code>options</code> parameter of <code>jQuery.tmpl()</code> will extend the <code>tmplItem</code> data structure, and so be available to the template as in the following example:
</p>
<pre>
var markup = "&lt;li&gt;Some content: ${$item.myMethod()}.&lt;br/&gt;" 
           + " More content: ${$item.myValue}.&lt;/li&gt;";

// Compile the markup as a named template
$.template( "movieTemplate", markup );

// Render the template with the movies data
$.tmpl( "movieTemplate", movies,
  { 
      myValue: "somevalue", 
      myMethod: function() { 
          return "something";
      } 
  } 
).appendTo( "#movieList" );
</pre>

</longdesc>

<example>
<desc>Render local data using jQuery.tmpl().</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
  var movies = [
  { Name: "The Red Violin", ReleaseYear: "1998" },
  { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
  { Name: "The Inheritance", ReleaseYear: "1976" }
  ];

var markup = "<li><b>${Name}</b> (${ReleaseYear})</li>";

/* Compile the markup as a named template */
$.template( "movieTemplate", markup );

/* Render the template with the movies data and insert
   the rendered HTML under the "movieList" element */
$.tmpl( "movieTemplate", movies )
  .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Render data from a remote service, using jQuery.tmpl().</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var markup = "<li><b>${Name}</b> (${ReleaseYear})</li>";

/* Compile the markup as a named template */
$.template( "movieTemplate", markup );

function getMovies( genre, skip, top ) {
  $.ajax({
    dataType: "jsonp",
    url: "http://odata.netflix.com/Catalog/Genres('" + genre
    + "')/Titles?$format=json&$skip="
    + skip + "&$top=" + top,
    jsonp: "$callback",
    success: function( data ) {
      /* Get the movies array from the data */
      var movies = data.d;

      /* Remove current set of movie template items */
      $( "#movieList" ).empty();

      /* Render the template items for each movie
      and insert the template items into the "movieList" */
      $.tmpl( "movieTemplate", movies )
      .appendTo( "#movieList" );
    }
  });
}

$( "#cartoonsBtn" ).click( function() {
  getMovies( "Cartoons", 0, 6 );
});

$( "#dramaBtn" ).click( function() {
  getMovies( "Drama", 0, 6 );
});

]]></code>
<html><![CDATA[
<button id="cartoonsBtn">Cartoons</button>
<button id="dramaBtn">Drama</button>

<ul id="movieList"></ul>
]]></html>
</example>
<category name="Templates"/>
</entry>
<entry type="template-tag" name="{{else fieldNameOrExpression}} content {{/if}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="fieldNameOrExpression" type="String, Object, Function">
<desc>The name of a field on the current data item, or a JavaScript function or expression to be evaluated.</desc>
</argument>
</signature>

<desc>Used in association with the {{if}}...{{/if}} tag to provide alternative content based on the values of one or more expressions. The {{else}} tag can be used without a parameter, as in: {{if a}}...{{else}}...{{/if}}, or with a parameter, as in: {{if a}}...{{else b}}...{{/if}}.</desc>
<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{else}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the {{else}} Template Tag without a parameter</h4>
<p>
The following example shows how to use <code>{{if expression}}...{{else}}...{{/if}}</code> to insert conditional content. In the example different content is rendered depending on whether or not the <code>Languages</code> field of the data item is defined.
</p>
<h6>Template:</h6>
<pre>
&lt;li&gt;
    Title: ${Name}.
    {{if Languages}}
        (Alternative languages: ${Languages}).
    {{else}}
        (Available only in the original version).
    {{/if}}
&lt;/li&gt;
</pre>
<h6>Data:</h6>
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: "French" },
    { Name: "The Mighty" },
    { Name: "City Hunter", Languages: "Mandarin and Cantonese" }
];
</pre>

<h4>Using the {{else}} Template Tag with a parameter</h4>
<p>
The following example shows how passing a parameter to <code>{{else expression}}</code> provides the equivalent of additional <em>'else if'</em> conditional blocks. In the example different content is rendered depending on whether the <code>Languages</code> field of the data item is defined, and if not, depending on whether the <code>Subtitles</code> field of the data item is defined.
</p>
<h6>Template:</h6>
<pre>
&lt;li&gt;
    Title: ${Name}.
    {{if Languages}}
        (Alternative languages: ${Languages}).
    {{else Subtitles}} 
        (Original language only. Subtitles in ${Subtitles}).
    {{else}} 
        (Original version only, without subtitles).
    {{/if}}
&lt;/li&gt;
</pre>
<h6>Data:</h6>
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: "French", Subtitles: "English" },
    { Name: "The Mighty", Subtitles: "French and Spanish" },
    { Name: "The Mighty" },
    { Name: "City Hunter", Languages: "Mandarin and Cantonese" }
];
</pre>

</longdesc>

<example>
<desc>Using <code>{{if expression}}...{{else}}...{{/if}}</code> to render content conditionally, based on the value of an expression.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: "French" },
    { Name: "The Mighty" },
    { Name: "City Hunter", Languages: "Mandarin and Cantonese" }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
        Title: ${Name}.
        {{if Languages}}
            (Alternative languages: ${Languages}).
        {{else}}
            (Available only in the original version).
        {{/if}}
    </li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Using <code>{{if expression1}}...{{else expression2}}...{{else}}...{{/if}}</code> to render content conditionally, based on the values of different expressions.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: "French", Subtitles: "English" },
    { Name: "The Mighty", Subtitles: "French and Spanish" },
    { Name: "The Mighty" },
    { Name: "City Hunter", Languages: "Mandarin and Cantonese" }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
    Title: ${Name}.
        {{if Languages}}
            (Alternative languages: ${Languages}).
        {{else Subtitles}} 
            (Original language only. Subtitles in ${Subtitles}).
        {{else}} 
            (Original version only, without subtitles).
        {{/if}}
    </li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<category name="Template Tags"/>
</entry>
<entry type="template-tag" name="{{each( index, value ) data}} content {{/each}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="data" type="Object">
<desc>The data to to iterate over. This can be any JavaScript type, including Array or Object.</desc>
</argument>
<argument name="index" type="String" optional="true">
<desc>String specifying a variable name for the iteration index. Defaults to "$index".</desc>
</argument>
<argument name="value" type="Object" optional="true">
<desc>String specifying a variable name for the current data value, during the iteration. Defaults to "$value".</desc>
</argument>
</signature>
<desc>Used to iterate over a data array, and render the content between the opening and closing template tags once for each data item.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{each}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the {{each}} Template Tag</h4>
<p>
The following example shows how to use <code>{{each}}...{{/each}}</code> to render a section of markup iteratively over hierarchical data.
</p>
<h6>Template:</h6>
<pre>
&lt;li&gt;
    Title: ${Name}.
    {{each Languages}}
        ${$index + 1}: &lt;em&gt;${$value}. &lt;/em&gt;
    {{/each}}
&lt;/li&gt;
</pre>
<h6>Data:</h6>
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: ["French"] },
    { Name: "The Mighty", Languages: [] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];
</pre>

<h4>Evaluating Expressions and Functions, Using Template Variables</h4>
<p>
<code>{{each expression}}</code> can be used in a similar way to <code>${expression}</code>, to render content iteratively over an array returned by an expression or a function call, as in the following example:</p>
<pre>
...
{{each $item.getSortedLanguages("a-z")}}
    ...
{{/each}}
...
</pre>
<p>
See <a href="http://api.jquery.com/template-tag-equal">${}</a> for more detailed documentation and examples of using template tags in association with expression evaluation, function calls, template variables, etc. 
</p>

<h4>The index and value parameters of {{each}}</h4>
<p>
The block of template markup between the opening and closing tags <code>{{each}}</code> and <code>{{/each}}</code> is rendered once for each data item in the <code>data</code> array. Within this block the <code>{{each}}</code> template tag exposes the current index and value as additional template variables <code>$index</code> and <code>$value</code>. These default variable names can be changed by passing in <code>index</code> and <code>value</code> parameters to the <code>{{each}}</code> template tag, as in the following example: 
</p>
<pre>
{{each(i, language) Languages}}
    ${i + 1}: &lt;em&gt;${language}. &lt;/em&gt;
{{/each}}
</pre>
</longdesc>

<example>
<desc>Using <code>{{each}}...{{/each}}</code> to render a section of markup iteratively over hierarchical data.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: ["French"] },
    { Name: "The Mighty", Languages: [] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
        Title: ${Name}.
        {{each Languages}}
            ${$index + 1}: <em>${$value}. </em>
        {{/each}}
    </li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Specifying the index and value parameters of the <code>{{each}}</code> tag.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: ["French"] },
    { Name: "The Mighty", Languages: [] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
        Title: ${Name}.
        {{each(i, language) Languages}}
            ${i + 1}: <em>${language}. </em>
        {{/each}}
    </li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>
<category name="Template Tags"/>
</entry>

<entry type='method' name="tmplItem" return="tmplItem" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
</signature>
<desc>Return the <code>tmplItem</code> data structure for the rendered template that the matched element is part of.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>
<p>
<code>$(selector).tmplItem()</code> provides access to the rendered template item which the target element of the selector is part of.
</p>
<p>See also <a href="http://api.jquery.com/jquery.tmplitem/">jQuery.tmplItem()</a>.</p>
<p>
The return value of <code>tmplItem()</code> is a <code>tmplItem</code> data structure providing access to:</p>
<ul>
<li>The HTML elements that the template item is made up of.</li>
<li>The associated data item.</li>
<li>The parent template item, if the template is nested.</li>
<li>The template that was used to render the template item.</li>
<li>User defined parameters or methods, such as any values that were set on the <code>options</code> map, passed to <code>tmpl()</code> when the template was rendered.</li>
</ul>
<p>
The following example shows how to use <code>.tmplItem()</code> to get information about the rendered template:</p>
<pre>
var tmplItem = $( selector ).tmplItem();
alert( "Description: " + tmplItem.data.description );
</pre>

<h4 id="building-ajax-apps">Building Interactive Ajax Applications</h4>
<p>
<code>.tmplItem()</code> and <code>jQuery.tmplItem()</code> make it easy to use templates in scenarios beyond simple string concatenation and read-only rendering. They let you create fully-fledged interactive client-side Ajax applications in which the code needs to perform actions like the following:</p>
<ul>
<li>Accessing the associated data item.</li>
<li>Modifying the data item.</li>
<li>Accessing HTML elements that make up the rendered template item.</li>
<li>Updating (re-rendering) the template item, with modified data, modified user-defined parameters, or using a different template</li>
</ul>

<p><strong>Example:</strong> Access data and HTML elements for a template item.:</p>
<pre>
// Get the template item for an element
var tmplItem = $( selector ).tmplItem();

// Get the corresponding data item and HTML nodes
var movieData = tmplItem.data;
var htmlNodes = tmplItem.nodes;

// Modify style
$( htmlNodes ).css( "backgroundColor", color );

// Access data
alert( "&#39;" + movieData.Name + "&#39; was released in "
        + movieData.ReleaseYear + "." );
</pre>

<p>The following example is from the Master Detail sample, below. It uses <code>.tmplItem()</code> to set selection on the new item that is added to the list:</p>
<pre>
$("#addBtn").click( function () {
    // Add a new item to the data array
    people.push( { firstName: "first", lastName: "last" } );

    // Render the template with the new data
    renderTemplate( "#peopleList", "#listItemTemplate", people );

    // Find the added template item
    var addedTmplItem = $("#peopleList tr:last").tmplItem();
    
    // Set selection on the added item
    select ( addedTmplItem );
});
</pre>
    

</longdesc>

<example>
<desc>Access the template item of matched element, to show data and to modify CSS styles on the rendered template.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" />
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" />
<code><![CDATA[
var movies = [ 
    { Name: "The Red Violin", ReleaseYear: "1998" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
    { Name: "The Inheritance", ReleaseYear: "1976" }
];
var color = "aqua"; 
/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );

$( "#lastItemBtn" ).click( function() {
    /* Flip the color */
    color = (color === "aqua" ? "yellow" : "aqua");

    /* Get the data structure for the last
       template item in the list */
    var lastTmplItem = $( "li:last" ).tmplItem();

    /* Get the corresponding data item and HTML nodes */
    var movie = lastTmplItem.data;
    var htmlNodes = lastTmplItem.nodes;

    /* Switch the background color */
    $( htmlNodes ).css( "backgroundColor", color );

    /* Acces the data */
    alert( "'" + movie.Name + "' was released in " + movie.ReleaseYear + "." );
});
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl">
    <li>
        <b>${Name}</b>
    </li>
</tmpl>

<button id="lastItemBtn">Details of last movie</button>

<ul id="movieList"></ul>
]]></html> 
</example> 

<example>
<desc>Editable master detail view.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var people = [
    { firstName: "Peter", lastName: "Jones" },
    { firstName: "Eva", lastName: "Smolinski" }
];

var selectedItem = null;

function renderTemplate( container, template, data ) {
    $( container ).empty();
    $( template ).tmpl( data ).appendTo( container );
}

/* Render the list */
renderTemplate( "#peopleList", "#listItemTemplate", people );

function select( tmplItem ) {
    if ( selectedItem ) {
        $( selectedItem.nodes ).removeClass( "selected");
    }
    $( tmplItem.nodes ).addClass( "selected");
    selectedItem = tmplItem;

    /* Render the detail view for this data item */
    renderTemplate( "#personDetail", "#detailTemplate", tmplItem.data );
}

$("#addBtn").click( function () {
    /* Add a new item to the data array */
    people.push( { firstName: "first", lastName: "last" } );

    /* Render the template with the new data */
    renderTemplate( "#peopleList", "#listItemTemplate", people );

    /* Find the added template item */
    var addedTmplItem = $("#peopleList tr:last").tmplItem();
    
    /* Set selection on the added item */
    select ( addedTmplItem );
});

$("#peopleList")
    .delegate( "tr", "click", function () {
        /* Set selection on the clicked item */
        select ( $.tmplItem(this) );
    });

$("#personDetail")
    .delegate( "input", "change", function () {
        /* Set the data to the modified value */
        $.tmplItem(this).data[ this.name ] = this.value;
        
        /* Render the list, to show the updated data */ 
        renderTemplate( "#peopleList", "#listItemTemplate", people );
    });
]]></code>
<css><![CDATA[
  table {cursor:pointer;border-collapse:collapse;float:left;clear:both;} 
  table tr {border:1px solid blue;color:blue;height:25px;} 
  table tr:hover {color:red;}
  table, #personDetail > div {border:2px solid blue;width:230px;
                     margin:4px 0 4px 4px;
                     background-color:#f8f8f8;} 
  table td, #personDetail div div {padding:3px;margin:3px;}
  .selected {background-color:yellow;} 
  #personDetail input {float:right;width:125px;} 
  #personDetail {float:left;margin-left:10px;} 
  button {float:left;margin:4px;}
]]></css>
<html><![CDATA[
<tmpl id="listItemTemplate" type="text/x-jquery-tmpl"> 
    <tr><td>
        ${firstName} ${lastName} 
    </td></tr>
</tmpl>

<tmpl id="detailTemplate" type="text/x-jquery-tmpl"> 
    <div>
        <div>First Name: <input name="firstName" value="${firstName}"/></div>
        <div>Last Name: <input name="lastName" value="${lastName}"/></div>
    </div>
</tmpl>

<button id="addBtn">Add a person</button>

<table><tbody id="peopleList"></tbody></table>

<div id="personDetail"></div>
]]></html>
</example>
<category name="Templates"/>
</entry>

<entry type='method' name="template" return="function" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="name" type="String" optional="true">
<desc>A string naming the compiled template.</desc>
</argument>
</signature>
<desc>Compile the contents of the matched element as a reusable compiled template.</desc> 

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>
<p>
This method returns a compiled template, created from the content of the first matched element. If the <code>name</code> parameter is provided the compiled template is stored as a named template, and can be referenced using the specified string.
</p>
<p>See also <a href="http://api.jquery.com/jquery.template">jQuery.template()</a>.</p>
<p>
<strong>Example:</strong> Create a compiled template associated with the name "summaryTemplate" and then reference it by name for rendering:
</p>
<pre>
&lt;script id="titleTemplate" type="text/x-jquery-tmpl"&gt;
  &lt;li&gt;${Name}&lt;/li&gt;
&lt;/script&gt;
___________

// Compile the inline template as a named template
$( "#titleTemplate" ).template( "summaryTemplate" );

function renderList() {
  // Render the movies data using the named template: "summaryTemplate"
  $.tmpl( "summaryTemplate", movies ).appendTo( "#moviesList" );
}
</pre>

<p>
<strong>Example:</strong> Use the return value rather than the <code>name</code> string to reference the compiled template:
</p>

<pre>
&lt;script id="titleTemplate" type="text/x-jquery-tmpl"&gt;
  &lt;li&gt;${Name}&lt;/li&gt;
&lt;/script&gt;
___________

// Compile the inline template as a named template
var myTemplate = $( "#titleTemplate" ).template();

function renderList() {
  // Render movies data using the compiled template: myTemplate
  $.tmpl( myTemplate, movies ).appendTo( "#moviesList" );
}
</pre>
<p>
<strong>Example:</strong> Create a named template and reference it by name as a nested template: 
</p>
<pre>
&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt;
  {{tmpl "summaryTemplate"}}
  &lt;tr&gt;&lt;td&gt;Director: ${Director}&lt;/td&gt;&lt;/tr&gt;
&lt;/script&gt;

&lt;script id="titleTemplate" type="text/x-jquery-tmpl"&gt;
  &lt;tr&gt;&lt;td&gt;${Name}&lt;/td&gt;&lt;/tr&gt;
&lt;/script&gt;
___________

// Compile the titleTemplate template as a named template
// referenced by the {{tmpl}} tag
$( "#titleTemplate" ).template( "summaryTemplate" );

// Render the movies data using the named template as a nested template
$( "#movieTemplate" ).tmpl( movies ).appendTo( "#movieList" );
</pre>
<p>
<strong>Example:</strong> Switch the template item to a different template, using <code>.template()</code> to obtain compiled template:
</p>
<pre>
&lt;script id="summaryTemplate" type="text/x-jquery-tmpl"&gt;
  &lt;tr&gt;...&lt;/tr&gt;
&lt;/script&gt;

&lt;script id="detailTemplate" type="text/x-jquery-tmpl"&gt;
  &lt;tr&gt;...&lt;/tr&gt;
&lt;/script&gt;
___________

// Render the summaryTemplate with the "movies" data 
$( "#summaryTemplate" ).tmpl( movies ).appendTo( "#movieList" );

$( "tr" ).click( function () {
  // Switch the template for this template item to
  // a different named template, then update the rendered item
  var tmplItem = $.tmplItem(this);
  tmplItem.tmpl = $( "#detailTemplate" ).template();
  tmplItem.update();
});
</pre>


</longdesc>

<example>
<desc>Dynamic switching of templates, using .template() to obtain compiled template.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
  { Name: "The Red Violin", ReleaseYear: "1998", Director: "François Girard" },
  { Name: "Eyes Wide Shut", ReleaseYear: "1999", Director: "Stanley Kubrick" },
  { Name: "The Inheritance", ReleaseYear: "1976", Director: "Mauro Bolognini" }
];
var selectedItem = null;

/* Render the summaryTemplate with the "movies" data */ 
$( "#summaryTemplate" ).tmpl( movies ).appendTo( "#movieList" );

$("#movieList")
.delegate( ".movieSummary", "click", function () {
  if (selectedItem) {
    /* Switch previously selected item back to the summaryTemplate */ 
    selectedItem.tmpl = $( "#summaryTemplate" ).template();

    /* Update rendering of previous selected item */ 
    selectedItem.update();
  }

  /* Make this the selected item  */
  selectedItem = $.tmplItem(this);

  /* Switch this template item to the detailTemplate */ 
  selectedItem.tmpl = $( "#detailTemplate" ).template();

  /* Refresh rendering */ 
  selectedItem.update();
})
.delegate( ".movieDetail", "click", function () {
  /* Unselect - switch to the summaryTemplate */ 
  selectedItem.tmpl = $( "#summaryTemplate" ).template();

  /* Refresh rendering */ 
  selectedItem.update();

  selectedItem = null;
});
]]></code>
<css><![CDATA[
  table { cursor:pointer; border-collapse:collapse; border:2px solid blue; width:300px; margin:8px; }
  table tr { border:1px solid blue; color:blue; background-color:#f8f8f8; } 
  table td { padding:3px; } table tr:hover { color:red; }
  .movieDetail { background-color:yellow; } 
  .movieDetail.row1 { border-bottom:none; } .movieDetail.row2 { border-top:none; }
]]></css>
<html><![CDATA[
<tmpl id="summaryTemplate" type="text/x-jquery-tmpl">
  <tr class='movieSummary'><td colspan='2'>${Name}</td></tr>
</tmpl>

<tmpl id="detailTemplate" type="text/x-jquery-tmpl">
  <tr class='movieDetail row1'><td colspan='2'>${Name}</td></tr><tr class='movieDetail row2'><td>${ReleaseYear}</td><td>Director: ${Director}</td></tr>
</tmpl>

Click for details:
<table><tbody id="movieList"></tbody></table>
]]></html>
</example>
<category name="Templates"/>
</entry>
<entry type="template-tag" name="{{html fieldNameOrExpression}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="fieldNameOrExpression" type="String, Object, Function">
<desc>The name of a field on the current data item, or a JavaScript function or expression, returning HTML markup.</desc>
</argument>
</signature>
<desc>Used for insertion of HTML markup strings in the rendered template. Evaluates the specified field on the current data item, or the specified JavaScript function or expression.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{html}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the {{html}} Template Tag</h4>
<p>
The following example shows how to use <code>{{html}}</code> to insert markup from the <code>Synopsis</code> field of the data item into the rendered template.
</p>
<pre>&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt;
    &lt;h4&gt;${Name}&lt;/h4&gt;
    &lt;p&gt;{{html Synopsis}}&lt;/p&gt;
&lt;/script&gt;
</pre>

<h4>HTML encoding</h4>
<p>
Using <code>{{html fieldNameOrExpression}}</code> is equivalent to using <code>${fieldNameOrExpression}</code>, except that it renders unencoded text into the HTML DOM, whereas <code>${}</code> encodes values by default. 
</p>

<h4>Evaluating Expressions and Functions, Using Template Variables</h4>
<p>
<code>{{html expression}}</code> can be used in a similar way to <code>${expression}</code>, to render markup returned by an expression or a function call, as in the following example:</p>
<h6>Template:</h6>
<pre>
&lt;p&gt;{{html $item.getSynopsis(true)}&lt;/p&gt;
</pre>
<h6>Code:</h6>
<pre>
// Render the template with the movie data
$( "#movieTemplate" ).tmpl( movie, { 
    getSynopsis: function( short ) {
        //return short or long synopsis
        //...
    }
}).appendTo( "#movieContainer" );
</pre>
<p>
See <a href="http://api.jquery.com/template-tag-equal">${}</a> for more detailed documentation and examples of using template tags in association with expression evaluation, function calls, template variables, etc. 
</p>

</longdesc>

<example>
<desc>Using <code>{{html}}</code> to insert markup from data.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
/* The Synopsis data field contains HTML markup. */
var movie = { 
    Name: "Meet Joe Black", 
    Synopsis: "The <span class='role'>grim reaper</span> (<a href='http://www.netflix.com/RoleDisplay/Brad_Pitt/73919'>Brad Pitt</a>) visits <span class='role'>Bill Parrish</span> (<a href='http://www.netflix.com/RoleDisplay/Anthony_Hopkins/43014'>Anthony Hopkins</a>)..."
};

/* Render the template with the movie data.
   The template uses the {{html}} template tag
   to  insert the Synopsis HTML markup data. */
$( "#movieTemplate" ).tmpl( movie )
    .appendTo( "#movieContainer" );
]]></code>
<css><![CDATA[
.role {font-weight:bold;font-style: italic;} #movieContainer {padding-left: 8px;}
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <h4>${Name}</h4>
    <p>{{html Synopsis}}</p>
</tmpl>

<div id="movieContainer"></div>
]]></html>
</example>
<category name="Template Tags"/>
</entry>

<entry type="template-tag" name="${fieldNameOrExpression}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="fieldNameOrExpression" type="String, Object, Function">
<desc>The name of a field on the current data item, or a JavaScript function or expression to be evaluated.</desc>
</argument>
</signature>
<desc>Used for insertion of data values in the rendered template. Evaluates the specified field (property) on the current data item, or the specified JavaScript function or expression.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>${}</code> tag can used within jQuery templates in addition to text and HTML markup to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. <br/>Note: User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the ${} Template Tag</h4>
<p>
The following example shows how to use <code>${}</code> to insert the values of the data item fields: <code>Name</code> and <code>ReleaseYear</code>.
</p>
<pre>&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt;
    &lt;li&gt;&lt;b&gt;${Name}&lt;/b&gt; was released in ${ReleaseYear}.&lt;/li&gt;
&lt;/script&gt;

&lt;script type="text/javascript"&gt;
    var movies = [
        { Name: "The Red Violin", ReleaseYear: "1998" },
        { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
        { Name: "The Inheritance", ReleaseYear: "1976" }
    ];

    // Render the template with the movies data and insert
    // the rendered HTML under the "movieList" element
    $( "#movieTemplate" ).tmpl( movies )
        .appendTo( "#movieList" );
&lt;/script&gt;

&lt;ul id="movieList"&gt;&lt;/ul&gt;</pre>

<p>
The <code>${field}</code> syntax is a shortened form of the alternative syntax: <code>{{= field}}</code>. The following is equivalent to the template used in the example above:
</p>
<pre>&lt;li&gt;&lt;b&gt;{{= Name}}&lt;/b&gt; was released in {{= ReleaseYear}}.&lt;/li&gt;</pre>

<h4>Evaluating Expressions and Functions</h4>
<p>
In the following example <code>${expression}</code> is used to evaluate a simple expression:
</p>
<h6>Template:</h6>
<pre>
&lt;tr&gt;&lt;td&gt;${Languages.length}&lt;/td&gt;&lt;/tr&gt;
</pre>
<h6>Data:</h6> 
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: ["English", "French"] },
    { Name: "The Mighty", Languages: ["English"] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
</pre>

<p>
For more complex expressions it is preferable to place the expression within a function, then use <code>${myFunction(a,b)}</code> to call the function, as in:
</p>
<h6>Template:</h6>
<pre>
&lt;tr&gt;&lt;td&gt;${getLanguages(Languages, " - ")}&lt;/td&gt;&lt;/tr&gt;
</pre>
<h6>Code:</h6>
<pre>
function getLanguages( data, separator ) {
    return data.join( separator );
}
</pre>

<p>
The above example requires the function <code>getLanguages</code> to be available in global scope. An alternative approach which does not require a global variable is to add the function to the template item, by passing it in with the <code>options</code> parameter of <code>.tmpl()</code>:
</p>
<h6>Template:</h6>
<pre>
&lt;tr&gt;&lt;td&gt;${$item.getLanguages(" - ")}&lt;/td&gt;&lt;/tr&gt;
</pre>
<h6>Code:</h6>
<pre>
// Render the template with the movies data
$( "#movieTemplate" ).tmpl( movies, { 
    getLanguages: function( separator ) {
        return this.data.Languages.join( separator );
    }
}).appendTo( "#movieList" );
</pre>
<p>
Note the use of the <code>$item</code> template variable, above (see the next section), which corresponds to the template item. In the call to <code>$item.getLanguages()</code>, the <code>this</code> pointer within the function is therefore the template item, and provides access to <code>this.data</code> etc.
</p>

<h4>The $item and $data Template Variables</h4>
<p>
The following variables are exposed to expression evaluation within templates:
</p>
<ul>
    <li><code>$</code>: The jQuery object.</li>
    <li><code>$item</code>: The current template item - which allows access to <code>$item.data</code>, <code>$item.parent</code>, etc. as well as any user-defined values or methods passed in with the options map.</li>
    <li><code>$data</code>: The current data item (equivalent to <code>$item.data</code>).</li>
    <li>Note: A template tag with content such as <code>{{each}}...{{/each}}</code> may expose additional variables to template evaluation within the content. In the case of <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, for example, the additional template variables <code>$value</code> and <code>$index</code> are provided within the content of the <code>{{each}}</code> tag.</li>
</ul>

<h4>HTML encoding</h4>
<p>
The values rendered by <code>${}</code> are evaluated as strings, and are HTML encoded. Any embedded markup will therefore be encoded. To insert the unencoded markup in the rendered template, use instead the <a href="http://api.jquery.com/template-tag-html">{{html}}</a> template tag.
</p>


</longdesc>

<example>
<desc>Using <code>${}</code> to render values of data item fields.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "The Red Violin", ReleaseYear: "1998" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
    { Name: "The Inheritance", ReleaseYear: "1976" }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li><b>${Name}</b> was released in ${ReleaseYear}.</li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Using <code>${}</code> to evaluate an expression or call a function.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: ["English", "French"] },
    { Name: "The Mighty", Languages: ["English"] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies, { 
    getLanguages: function( separator ) {
        return this.data.Languages.join( separator );
    }
}).appendTo( "#movieList" );
]]></code>
<css><![CDATA[
table { border-collapse:collapse; width:400px; background-color:#f8f8f8; margin:10px; } table td { border:1px solid blue; padding:3px; } 
table th { font-weight:bold; border:2px solid blue; padding:1px; } table tbody { border:2px solid blue; }
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <tr>
        <td>${Name}</td>
        <td>${Languages.length}</td>
        <td>${$item.getLanguages(" - ")}</td>
    </tr>
</tmpl>

<table><tbody><tr><th>Title</th><th>Versions</th><th>Languages</th></tr></tbody>
<tbody id="movieList"></tbody></table>
]]></html>
</example>
<category name="Template Tags"/>
</entry>
<entry type='method' name="unlink" return="jQuery"  plugin="jQuery Datalink">
<download>
<p>This documentation topic concerns the <em> jQuery Datalink</em> plugin (jquery-datalink), which can be downloaded from: <a href="http://github.com/jquery/jquery-datalink">http://github.com/jquery/jquery-datalink</a>.</p>
</download>
  <signature>
    <added>1.4.3</added>
    <argument name="target" type="Element, Object">
      <desc>An object to unlink.</desc>
    </argument>
  </signature>
  <desc>Remove a previously created link.</desc>
  <longdesc><p>Links created with <code>.link()</code> can be removed with <code>.unlink()</code>.</p>
<pre>
var person = {};
$("form").link(person);
$("[name=firstName]").val("aValue");
person.firstName; // aValue
$("form").unlink(person);
$("[name=firstName]").val("aNewValue");
person.firstName; // still "aValue"
</pre>
<p>If the original link matched multiple elements, <code>.unlink()</code> may also be used to remove the link on a subset of the elements. The following example shows how to link all input elements to an object, and then how to unlink input elements that have a specified CSS class:</p>
<pre>
var person = {};
$("input").link(person);
$(".nolink").unlink(person);
</pre>
<p>
<code>.unlink()</code> can unlink elements that were part of the original link, but note that <code>.link()</code> also responds to bubbled-up change events from the selected elements' descendants. <code>.unlink()</code> will only unlink elements that were explicitly matched by the original link, not descendants of those elements.
</p>
</longdesc>
<example>
    <desc>Link all input elements of a form to an object, then remove the link.</desc>
    <js src="http://github.com/nje/jquery-datalink/raw/e3e3be4312c9b224a8d9b25031f4ac876e4f70fd/jquery.js"/>
    <js src="http://github.com/nje/jquery-datalink/raw/master/jQuery.datalink.js"/>
    <code><![CDATA[
var person = { };
$("form").link(person);

// Chain link the person object to these elements to show the results
$("#objFirst").link(person, {
    firstName: {
        name: "objFirst",
        convertBack: function(value, source, target) {
            $(target).text(value);
        }
    }
});
$("#objLast").link(person, {
    lastName: {
        name: "objLast",
        convertBack: function(value, source, target) {
            $(target).text(value);
        }
    }
});

// remove link
$("#unlink").click(function() {
	$("form").unlink(person);
});
]]></code>
<css><![CDATA[
  ]]></css>
<html><![CDATA[
    <form>
      <div>
        First Name:
        <input type="text" name="firstName" />
      </div>
      <div>
        Last Name:
        <input type="text" name="lastName" />
      </div>
      <div>
      <input id="unlink" type="button" value="unlink" />
      </div>
    </form>
    Object.firstName: <span id="objFirst"></span><br/>
    Object.lastName <span id="objLast"></span>
  ]]></html>
  </example>
<category name="Data Link"/>
</entry>

<entry type='method' name="link" return="jQuery" plugin="jQuery Datalink">
<download>
<p>This documentation topic concerns the <em> jQuery Datalink</em> plugin (jquery-datalink), which can be downloaded from: <a href="http://github.com/jquery/jquery-datalink">http://github.com/jquery/jquery-datalink</a>.</p>
</download>
  <signature>
    <added>1.4.3</added>
    <argument name="target" type="Element, Object">
      <desc>An object to link changes to.</desc>
    </argument>
    <argument name="settings" optional="true" type="Object">
      <desc>A map describing the fields to link.</desc>
    </argument>
  </signature>
  <desc>Link changes to the matched elements to an object.</desc>
  <longdesc><p>The <code>.link()</code> method links form fields to an object. Any changes to the form field values are automatically represented in the object. For example, when an input element whose name attribute is "firstName" is changed, the firstName property of the target is set to the new value:</p>
<pre>
var person = {};
$("form").link(person);
$("[name=firstName]").val("NewValue"); // Set firstName to a value.
person.firstName; // NewValue

// User types a value into the form field.
person.firstName; // firstName now contains the user-ented value.
</pre>

<p>By default, links are two-way, meaning changes to the object are also automatically changed in the corresponding form field. For example, if the firstName of the target is changed using the <code>.data()</code> method, the value of input element named "firstName" is set to the new value.</p>
<pre>
// Set the object property.
$(person).data("firstName", "NewValue");
// The change is automatically pushed to the input element.
$("[name=firstName]").val(); // The value is now "NewValue"
</pre>
<h4>Customizing the Mapping Between Elements and Objects</h4>
<p>
By default, all change events that occur for (or bubble up to) the selected element or elements are processed, and the changes are made to the property whose name corresponds to the name of the element that changed. By providing a mapping object, you can explicitly choose which elements participate in linking behavior, and what target properties they set.
</p>
<pre>
var person = {};
$("form").link(person, {
    firstName: "first-name",
    lastName: "last-name"
});
</pre>
<p>
The preceeding example shows how to link only the input element named "first-name" to person.firstName, and the input element named "last-name" to person.lastName. Changes in other input elements and changes to other fields of the person object are ignored (by this link).
</p>
<h4>Specifying One-Way Linking</h4>
<p>
You can disable two-way linking for individual fields with the <code>twoWay</code> field in the custom mapping. The following example shows how to create a link from the form field named "firstName" to the firstName property of a person object, but not the other way around.
</p>
<pre>
var person = {};
$("form").link(person, {
    firstName: {
      twoWay: false
    }
});
$(person).data("firstName", "NewValue");
$("[name=firstName]").val(); // unchanged
</pre>
<h4>Converting Values</h4>
<p>
By default, any changed value is assigned as-is to the target object. Often times, it is necessary to modify the value, as converting null to "None", formating or parsing a date, or parsing a string into a number. To perform these conversions, you can specify a <code>convert</code> field in the mapping that includes a conversion function, as shown in the following example:
</p>
<pre>
var person = {};
$("[name=age]")
  .link(person, {
      age: {
          convert: function(value) {
              return Math.round( parseFloat( value ) );
          }
      }
  })
  .val("7.5");
person.age; // 8
</pre>
The preceeding example shows how to specify that any value assigned to the age property of the person object (as a result of a change in the value of the input element named "age") first be parsed into a number (specifically, a floating-point number) and then rounded.
<p>
You can also define a converter using the <code>$.convertFn</code> object and refer to it by name instead:
</p>
<pre>
var person = {};
$.convertFn.round = function(value) {
    return Math.round( parseFloat( value ) );
}
$("[name=age]")
  .link(person, {
      age: {
          convert: "round"
      }
  })
  .val("7.5");
person.age; // 8
</pre>
<p>
You can customize the name in a custom mapping at the same time as a converter by specifying the name. The following example creates a link from the input element named "first-name" to the firstName property of the person object using a converter named "titleCase".
</p>
<pre>
$("form").link(person, {
    firstName: {
        name: "first-name"
        convert: "titleCase"
    }
});
</pre>
<p>
For two-way links, you can specify a converter for both directions using <code>convertBack</code> setting:
</p>
<pre>
$("form").link(obj, {
    field: {
        // converter1 and converter2 functions are defined elsewhere.
        convert: converter1,
        convertBack: converter2
    }
});
</pre>
<p>
Converters receive the value and you can optionally also get the source object and the target object as parameters. The source is where the  value comes from, and target is the object to set the value for. If the converter returns a value, it is assigned to the target automatically.</p>
<h4>Using Converters to Create Custom Linking Behavior</h4>
<p>If the converter does not return a value or if it returns "undefined", no automatic update occurs. You can use this feature to customize the behavior of a link by updating the source and target objects in your code directly and not returning a value.
The following example uses a converter that does not return a value, so no automatic update takes place. Instead, the converter code explicitly updates properties of the target object:
</p>
<pre>
var person = {};
$("[name=age]").link(person, {
    age: {
        convert: function(value, source, target) {
            var age = Math.round( parseFloat( value ) );
            target.age = age;
            target.canVote = age >= 18;
        }
    }
});
$("[name=age]").val("7.5");
person.age; // 8
person.canVote; // false
$("[name=age]").val("18");
person.canVote; // true
</pre>
<p>
You can also use this technique to establish links between any available DOM elements. This following example links the age property of the <code>person</code> object to the height of the target DOM element.
</p>
<pre>

var person = {};
$("#ageDiv").link(person, {
  age: {
    convertBack: function(value, source, target) {
      $(target).height(parseFloat(value * 2));
    }
  }
});
$(person).data("age", 21);
$("#ageDiv").height(); // 42
</pre>
</longdesc>
<example>
    <desc>Link all input elements of a form to an object.</desc>
    <js src="http://github.com/nje/jquery-datalink/raw/e3e3be4312c9b224a8d9b25031f4ac876e4f70fd/jquery.js"/>
    <js src="http://github.com/nje/jquery-datalink/raw/master/jQuery.datalink.js"/>
    <code><![CDATA[
var person = { };
$("form").link(person);

// Chain link the person object to these elements to show the results
$("#objFirst").link(person, {
    firstName: {
        name: "objFirst",
        convertBack: function(value, source, target) {
            $(target).text(value);
        }
    }
});
$("#objLast").link(person, {
    lastName: {
        name: "objLast",
        convertBack: function(value, source, target) {
            $(target).text(value);
        }
    }
});
]]></code>
<css><![CDATA[
  ]]></css>
<html><![CDATA[
    <form>
      <div>
        First Name:
        <input type="text" name="firstName" />
      </div>
      <div>
        Last Name:
        <input type="text" name="lastName" />
      </div>
    </form>
    Object.firstName: <span id="objFirst"></span><br/>
    Object.lastName: <span id="objLast"></span>
  ]]></html>
  </example>
<category name="Data Link"/>
</entry>

<entry type="template-tag" name="{{wrap( [data], [options] ) template}} content {{/wrap}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="template" type="String, Element, jQuery">
<desc>The HTML markup or text to use as a template.</desc>
</argument>
<argument name="data" type="Object" optional="true">
<desc>The data to render. This can be any JavaScript type, including Array or Object.</desc>
</argument>
<argument name="options" type="Options" optional="true">
<desc>An optional map of user-defined key-value pairs. Extends the <code>tmplItem</code> data structure, available to the template during rendering.</desc>
</argument>
</signature>
<desc>Used for composition of templates which incorporate wrapped HTML content. Rendered template items can combine wrapped HTML content with template markup.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{wrap}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a> and <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>The {{wrap}} and {{tmpl}} Template Tags</h4>

<p>The <code>{{wrap}}</code> template tag is similar to the {{tmpl}} template tag, except that it provides additional support for incorporating wrapped HTML content into the rendered output. The use of the <code>template</code>, <code>data</code> and <code>options</code> parameters is the same for both tags. (See <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> for additional information and examples).
</p>
<p>When using <code>{{wrap}}</code> the <code>template</code> parameter will usually correspond to template markup which uses the <code>$item.html()</code> feature to incorporate the wrapped markup. The <code>template</code> parameter can be any of the following: </p>
<ul>
<li>A string containing markup.</li>
<li>An HTML element (or jQuery object that wraps an element) whose content is to be used as the template.</li>
<li>A string corresponding to the name of a named template (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
<li>A compiled-template function (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
</ul>

<p>With <code>{{wrap}}</code>, the <code>data</code> parameter will often be unspecified, since the rendered output can be driven by the wrapped HTML rather than by data. If <code>data</code> is specified and is an array, the template is rendered once for each data item in the array. If <code>data</code> is an object, or if the <code>data</code> parameter is missing or null, a single template item is rendered.
</p>

<h4>Using the {{wrap}} Template Tag</h4>

<p>
The following example shows how to use <code>{{wrap}}</code> to render a nested template that incorporates the wrapped HTML. In this case the content of the <code>{{wrap}}</code> template tag is a set of <code>div</code> elements. The chosen template, <em>tableWrapper</em>, extracts each <code>div</code> and wraps it in a table cell.
</p>
<pre>
&lt;script id="myTmpl" type="text/x-jquery-tmpl"&gt;
    The following wraps some HTML content:
    {{wrap "#tableWrapper"}}
        &lt;div&gt;
            First &lt;b&gt;content&lt;/b&gt;
        &lt;/div&gt;
        &lt;div&gt;
            And &lt;em&gt;more&lt;/em&gt; &lt;b&gt;content&lt;/b&gt;...
        &lt;/div&gt;
    {{/wrap}}
&lt;/script&gt;

&lt;script id="tableWrapper" type="text/x-jquery-tmpl"&gt;
    &lt;table&gt;&lt;tbody&gt;
        &lt;tr&gt;
            {{each $item.html("div")}}
                &lt;td&gt;
                    {{html $value}}
                &lt;/td&gt;
            {{/each}}
        &lt;/tr&gt;
    &lt;/tbody&gt;&lt;/table&gt;
&lt;/script&gt;
</pre>

<h4>The $item.html() Method</h4>

<p>
Any HTML content between the opening and closing tags of <code>{{wrap}}</code> is made available to the template as a <code>$item.html( filter, textOnly )</code> method on the template item.
</p>
<p>
The return value of <code>$item.html()</code> is a filtered array of markup strings taken from the wrapped content:
</p>
<ul>
  <li>Use <code>$item.html()</code> without parameters to return all the top-level elements of the wrapped HTML content.</li>
  <li>Pass a selector string as <code>filter</code> parameter to return a filtered subset of the top-level elements. (The default value of <code>filter</code> is <code>"*"</code>).</li>
  <li>If <code>textOnly</code> is set to true <code>$item.html( filter, textOnly )</code> returns the inner text of the filtered subset of top-level elements.</li>
</ul>
<p>
The following example shows how to incorporate both HTML and text content into the rendered output.
</p>
<pre>
&lt;script id="myTmpl" type="text/x-jquery-tmpl"&gt;
    The following wraps and reorders some HTML content:
    {{wrap "#tableWrapper"}}
        &lt;h3&gt;One&lt;/h3&gt;
        &lt;div&gt;
            First &lt;b&gt;content&lt;/b&gt;
        &lt;/div&gt;
        &lt;h3&gt;Two&lt;/h3&gt;
        &lt;div&gt;
            And &lt;em&gt;more&lt;/em&gt; &lt;b&gt;content&lt;/b&gt;...
        &lt;/div&gt;
    {{/wrap}}
&lt;/script&gt;

&lt;script id="tableWrapper" type="text/x-jquery-tmpl"&gt;
    &lt;table&gt;&lt;tbody&gt;
        &lt;tr&gt;
            {{each $item.html("h3", true)}}
                &lt;td&gt;
                    ${$value}
                &lt;/td&gt;
            {{/each}}
        &lt;/tr&gt;
        &lt;tr&gt;
            {{each $item.html("div")}}
                &lt;td&gt;
                    {{html $value}}
                &lt;/td&gt;
            {{/each}}
        &lt;/tr&gt;
    &lt;/tbody&gt;&lt;/table&gt;
&lt;/script&gt;
</pre>

<h4>Including Template Tags in Wrapped Content</h4>

<p>
The HTML markup between the opening and closing tags of <code>{{wrap}}</code> can include other template tags. The following example uses nested <code>{{wrap}}</code>tags to created nested tab views:
</p>
<pre>
&lt;script id="myTmpl" type="text/x-jquery-tmpl"&gt;
    {{wrap "#tabsWrap"}}
        &lt;h3&gt;One&lt;/h3&gt;
        &lt;div&gt;
            First &lt;b&gt;tab&lt;/b&gt;
        &lt;/div&gt;
        &lt;h3&gt;Two&lt;/h3&gt;
        &lt;div&gt;
            &lt;b&gt;Second&lt;/b&gt; tab
            {{wrap "#tabsWrap"}}
                &lt;h3&gt;InnerOne&lt;/h3&gt;
                &lt;div&gt;
                    Inner first &lt;b&gt;tab&lt;/b&gt;
                &lt;/div&gt;
                &lt;h3&gt;InnerTwo&lt;/h3&gt;
                &lt;div&gt;
                    Inner &lt;b&gt;second&lt;/b&gt; tab
                &lt;/div&gt;
            {{/wrap}}
        &lt;/div&gt;
    {{/wrap}}
&lt;/script&gt;
</pre>

</longdesc>

<example>
<desc>Using <code>{{wrap}}</code> to wrap elements in table cells.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
$( "#myTmpl" ).tmpl()
    .appendTo( "#myWrappedView" );
]]></code>
<css><![CDATA[
table { border-collapse:collapse; width:380px; background-color:#f8f8f8; border:2px solid blue; margin:5px; } table td { border:1px solid blue; padding:3px; } 
]]></css>
<html height="200"><![CDATA[
<tmpl id="myTmpl" type="text/x-jquery-tmpl">
    The following wraps and reorders some HTML content:
    {{wrap "#tableWrapper"}}
        <h3>One</h3>
        <div>
            First <b>content</b>
        </div>
        <h3>Two</h3>
        <div>
            And <em>more</em> <b>content</b>...
        </div>
    {{/wrap}}

    And this wraps different HTML content:
    {{wrap "#tableWrapper"}}
        <div>
            First <b>div</b>
        </div>
        <div>
            Second <b>div</b>
        </div>
        <div>
            Third <b>div</b>
        </div>
        <h3>first h3</h3>
        <h3>second h3</h3>
        <h3>third h3</h3>
    {{/wrap}}
</tmpl>

<tmpl id="tableWrapper" type="text/x-jquery-tmpl">
    <table><tbody>
        <tr>
            {{each $item.html("h3", true)}}
                <td>
                    ${$value}
                </td>
            {{/each}}
        </tr>
        <tr>
            {{each $item.html("div")}}
                <td>
                    {{html $value}}
                </td>
            {{/each}}
        </tr>
    </tbody></table>
</tmpl>

<div id="myWrappedView"></div>
]]></html>
</example>

<example>
<desc>Using <code>{{wrap}}</code> to create a tabbed view.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
/* Track the selected tab index */
var state = { activeIndex: 1 };

/* Render tabs view */
$( "#tabsTmpl" ).tmpl( null, { state: state})
    .appendTo( "#tabsView" );

$( "#tabsView" )
    .delegate( ".tabsView th", "click", function() {
        var tmplItem = $.tmplItem( this );

        /* Set the selected tab index to this tab */
        tmplItem.state.activeIndex = $(this).index();

        /* update the rendering */
        tmplItem.update();
    });
]]></code>
<css><![CDATA[
.body {height:80px;background-color:#fff;} .body div {height:32px;vertical-align:middle;text-align:center;} .body h3 {text-align:center;} .tabsView td {border:solid 1px #0000A6;border-top:none;border-right:solid 2px #1E1ED2;}
.tabsView th {cursor:pointer;padding:2px;font-weight:normal;font-style:italic;color:#888;border:solid 1px #bbb;border-right:none;background-color:#f8f8f8;border-bottom:solid 1px #1E1ED2;} #tabsView > .tabsView {width:265px;} 
.tabsView {width:250px;border-collapse:collapse;border:none;margin:5px;} .tabsView tr {border-right:solid 1px #bbb;} th.header_true {font-weight:bold;border:solid 1px #0000A6;border-right:solid 2px #1E1ED2;border-bottom:solid 1px #eee;color:#0000A6;background-color:#fff;} 
]]></css>
<html><![CDATA[
<tmpl id="tabsTmpl" type="text/x-jquery-tmpl">
    {{wrap(null, {state: $item.state}) "#tabsWrap"}}
        <h3>One</h3>
        <div>
            First <b>tab</b>
        </div>
        <h3>Two</h3>
        <div>
            <b>Second</b> tab
        </div>
        <h3>Three</h3>
        <div>
            Third <em>tab</em> <br/> and more content...
        </div>
    {{/wrap}}
</tmpl>

<tmpl id="tabsWrap" type="text/x-jquery-tmpl">
    <table class="tabsView"><tbody>
        <tr>
            {{each $item.html("h3", true)}}
                <th class="header_${$index === $item.state.activeIndex}">
                    ${$value}
                </th>
            {{/each}}
        </tr>
        <tr><td colspan='${$item.html("h3").length}'>
            <div class="body">
                {{html $item.html("div")[$item.state.activeIndex]}}
            </div>
        </td></tr>
    </tbody></table>
</tmpl>

<div id="tabsView"></div>
]]></html>
</example>

<example>
<desc>Using <code>{{wrap}}</code> to create nested tabbed views.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
/* Track the selected tab index for inner and outer tab views */
var state = { activeIndex: 1, innerState: { activeIndex: 0 } };

function refresh() {
    $( "#tabsView" ).empty();
    $( "#tabsTmpl" ).tmpl( null, { state: state})
        .appendTo( "#tabsView" );
}

/* Render tabs view */
refresh();

$( "#tabsView" )
    .delegate( ".tabsView th", "click", function() {
        /* Set the selected tab index to this tab */
        $.tmplItem( this ).state.activeIndex = $(this).index();

        /* update the rendering */
        refresh();
    });
]]></code>
<css><![CDATA[
.body {height:85px;background-color:#fff;} .body div {height:30px;vertical-align:middle;text-align:center;} .body h3 {text-align:center;} .tabsView td {border:solid 1px #0000A6;border-top:none;border-right:solid 2px #1E1ED2;}
.tabsView th {cursor:pointer;padding:2px;font-weight:normal;font-style:italic;color:#888;border:solid 1px #bbb;border-right:none;background-color:#f8f8f8;border-bottom:solid 1px #1E1ED2;} #tabsView > .tabsView {width:265px;} 
.tabsView {width:250px;border-collapse:collapse;border:none;margin:5px;} .tabsView tr {border-right:solid 1px #bbb;} th.header_true {font-weight:bold;border:solid 1px #0000A6;border-right:solid 2px #1E1ED2;border-bottom:solid 1px #eee;color:#0000A6;background-color:#fff;} 
]]></css>
<html><![CDATA[
<tmpl id="tabsTmpl" type="text/x-jquery-tmpl">
    {{wrap(null, {state: $item.state}) "#tabsWrap"}}
        <h3>One</h3>
        <div>
            First <b>tab</b>
        </div>
        <h3>Two</h3>
        <div>
            <b>Second</b> tab
            {{wrap(null, {state: $item.state.innerState}) "#tabsWrap"}}
                <h3>InnerOne</h3>
                <div>
                    Inner first <b>tab</b>
                </div>
                <h3>InnerTwo</h3>
                <div>
                    Inner <b>second</b> tab
                </div>
            {{/wrap}}
        </div>
        <h3>Three</h3>
        <div>
        Third <em>tab</em> <br/> and more content...
        </div>
    {{/wrap}}
</tmpl>

<tmpl id="tabsWrap" type="text/x-jquery-tmpl">
    <table class="tabsView"><tbody>
        <tr>
            {{each $item.html("h3", true)}}
                <th class="header_${$index === $item.state.activeIndex}">
                    ${$value}
                </th>
            {{/each}}
        </tr>
        <tr><td colspan='${$item.html("h3").length}'>
            <div class="body">
                {{html $item.html("div")[$item.state.activeIndex]}}
            </div>
        </td></tr>
    </tbody></table>
</tmpl>

<div id="tabsView">..loading</div>
]]></html>
</example>
<category name="Template Tags"/>
</entry>
<entry type="template-tag" name="{{if fieldNameOrExpression}} content {{/if}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="fieldNameOrExpression" type="String, Object, Function">
<desc>The name of a field on the current data item, or a JavaScript function or expression to be evaluated.</desc>
</argument>
</signature>
<desc>Used for conditional insertion of content. Renders the content between the opening and closing template tags only if the specified data item field, JavaScript function or expression does not evaluate to false (or to zero, null or undefined).</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{if}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the {{if}} Template Tag</h4>
<p>
The following example shows how to use <code>{{if}}</code> to insert conditional content, depending on whether the <code>Languages</code> field of the data item is defined (and is not null).
</p>
<h6>Template:</h6>
<pre>
&lt;li&gt;
    Title: ${Name}.
    {{if Languages}}
        (Alternative languages: ${Languages}).
    {{/if}}
&lt;/li&gt;
</pre>
<h6>Data:</h6>
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: "French" },
    { Name: "The Mighty" },
    { Name: "City Hunter", Languages: "Mandarin and Cantonese" }
];
</pre>

<h4>Evaluating Expressions and Functions, Using Template Variables</h4>
<p>
<code>{{if expression}}</code> can be used in a similar way to <code>${expression}</code>, to render conditionally based on the value returned by an expression or a function call, as in the following example:</p>
<h6>Template:</h6>
<pre>
&lt;li&gt;
    Title: ${Name}.
    {{if Languages.length}}
        (Alternative languages: ${$item.getLanguages(" - ")}).
    {{/if}}
&lt;/li&gt;
</pre>
<h6>Data:</h6>
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: ["French"] },
    { Name: "The Mighty", Languages: [] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];
</pre>
<p>
See <a href="http://api.jquery.com/template-tag-equal">${}</a> for more detailed documentation and examples of using template tags in association with expression evaluation, function calls, template variables, etc. 
</p>

</longdesc>

<example>
<desc>Using <code>{{if}}</code> to render content conditionally, based on the value of an expression.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "Meet Joe Black", Languages: ["French"] },
    { Name: "The Mighty", Languages: [] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies, { 
    getLanguages: function( separator ) {
        return this.data.Languages.join( separator );
    }
}).appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li>
        Title: ${Name}.
        {{if Languages.length}}
            (Alternative languages: ${$item.getLanguages(" - ")}).
        {{/if}}
    </li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<category name="Template Tags"/>
</entry>
<entry type="template-tag" name="{{tmpl( [data], [options] ) template}} content {{/tmpl}}" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="template" type="String, Element, jQuery">
<desc>The HTML markup or text to use as a template.</desc>
</argument>
<argument name="data" type="Object" optional="true">
<desc>The data to render. This can be any JavaScript type, including Array or Object.</desc>
</argument>
<argument name="options" type="Options" optional="true">
<desc>An optional map of user-defined key-value pairs. Extends the <code>tmplItem</code> data structure, available to the template during rendering.</desc>
</argument>
</signature>
<desc>Used for composition of templates. Renders one or more nested template items within the rendered output of the parent template.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.
</p> 

<h4>Template Tags</h4>
<p>Template tags such as the <code>{{tmpl}}</code> tag can used within jQuery templates in addition to text and HTML markup, in order to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. 
</p>
<p>
Other available tags include: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. User-defined template tags can also be specified, by extending the <code>jQuery.tmpl.tag</code> map.</p> 

<h4>Using the {{tmpl}} Template Tag</h4>
<p>
The following example shows how to use <code>{{tmpl}}</code> to render a nested template.
</p>
<pre>
&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt; 
    {{tmpl "#titleTemplate"}}
    &lt;tr class="detail"&gt;&lt;td&gt;Director: ${Director}&lt;/td&gt;&lt;/tr&gt;
&lt;/script&gt;

&lt;script id="titleTemplate" type="text/x-jquery-tmpl"&gt; 
    &lt;tr class="title"&gt;&lt;td&gt;${Name}&lt;/td&gt;&lt;/tr&gt;
&lt;/script&gt;
</pre>

<p>The <code>template</code> parameter can be any of the following: </p>
<ul>
<li>A string containing markup.</li>
<li>An HTML element (or jQuery object that wraps an element) whose content is to be used as the template.</li>
<li>A string corresponding to the name of a named template (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
<li>A compiled-template function (see <a href="http://api.jquery.com/jquery.template">jQuery.template()</a> and <a href="http://api.jquery.com/template">.template()</a>).</li>
</ul>

<p>
If <code>data</code> is an array, the template is rendered once for each data item in the array. If <code>data</code> is an object, or if the <code>data</code> parameter is missing or null, a single template item is rendered.
</p>

<p>
The following example shows how to iterate over hierarchical data, by passing a <code>data</code> parameter to the a nested <code>{{tmpl}}</code> tag.
</p>
<h6>Templates:</h6>
<pre>
&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt; 
    &lt;tr&gt;
        &lt;td&gt;${Name}&lt;/td&gt;
        &lt;td&gt;{{tmpl(Languages) "#languageTemplate"}}&lt;/td&gt;
    &lt;/tr&gt;
&lt;/script&gt;

&lt;script id="languageTemplate" type="text/x-jquery-tmpl"&gt; 
    &lt;em&gt;${Name}&lt;/em&gt;
&lt;/script&gt;
</pre>
<h6>Data:</h6> 
<pre>
var movies = [
    { Name: "Meet Joe Black", Languages: ["English", "French"] },
    { Name: "The Mighty", Languages: ["English"] },
    { Name: "City Hunter", Languages: ["Mandarin", "Cantonese"] }
];</pre>

<h4>Recursive Nested {{tmpl}} Tags</h4>
<p>
A template may contain a <code>{{tmpl}}</code> or <code>{{wrap}}</code> tag referencing the same template. The following example uses a recursive template to create a tree view:
</p>
<h6>Templates:</h6>
<pre>
&lt;script id="folderTmpl" type="text/x-jquery-tmpl"&gt;
    &lt;li class="toggle"&gt;
        &lt;span class="expand"&gt;${expanderSymbol($item)}&lt;/span&gt;
        &lt;span&gt;${name}&lt;/span&gt;
    &lt;/li&gt;
    {{if expanded}}
        &lt;li&gt;
            &lt;ul&gt;{{tmpl(getFolderItems($item)) "#itemTmpl"}}&lt;/ul&gt;
            &lt;ul&gt;{{tmpl(getSubFolders($item)) "#folderTmpl"}}&lt;/ul&gt;
        &lt;/li&gt;
    {{/if}}
&lt;/script&gt;

&lt;script id="itemTmpl" type="text/x-jquery-tmpl"&gt;
    &lt;li class="folderItem"&gt;${name}&lt;/li&gt;
&lt;/script&gt;
</pre>
<h6>Data:</h6> 
<pre>
// Hierarchy of named folders 
var folders = {
    name: "Samples",
    folders: [
        { name: "API", folders: [
            { name: ".tmpl()"}
        ]},
        { name: "Template markup", folders: [
            { name: "Tags", folders: [
                { name: "{{wrap}}"}
            ]},
        ]},
    ]
};

// Array for the folder items. Each item can show up in one or more folders
var samples = [
    { name: "Template in script block", 
        folders: [ ".tmpl()" ], 
        description: "Rendering a template declared in script block" },
    { name: "Tab View", 
        folders: [ "{{wrap}}", ".tmpl()" ], 
        description: "A tab view, using {{wrap}}" }
];
</pre>

</longdesc>

<example>
<desc>Using {{tmpl}} to render a nested template.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "The Red Violin", Director: "François Girard" },
    { Name: "Eyes Wide Shut", Director: "Stanley Kubrick" },
    { Name: "The Inheritance", Director: "Mauro Bolognini" }
];

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies ).appendTo( "#movieList" );
]]></code>
<css><![CDATA[
table { border-collapse:collapse; border:2px solid blue; margin:5px; background-color:#f8f8f8; }
table tr { border:1px solid blue; } table td { padding:2px; }
.title { border-bottom:none; } .detail { border-top:none; }
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    {{tmpl "#titleTemplate"}}
    <tr class="detail"><td>Director: ${Director}</td></tr>
</tmpl>

<tmpl id="titleTemplate" type="text/x-jquery-tmpl"> 
    <tr class="title"><td>${Name}</td></tr>
</tmpl>

<table><tbody id="movieList"></tbody></table>
]]></html>
</example>

<example>
<desc>Using <code>{{tmpl}}</code> to render hierarchical data.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
function getMovies( genre, skip, top ) {
    $.ajax({
        dataType: "jsonp",
        url: "http://odata.netflix.com/Catalog/Genres('" + genre
            + "')/Titles?$format=json&$expand=Languages&$skip="
            + skip + "&$top=" + top,
        jsonp: "$callback",
        success: function( data ) {
            /* Get the movies array from the data */
            var movies = data.d.results;

            /* Remove current set of movie template items */
            $( "#movieList" ).empty();
            
            /* Render the template with the movies data and insert
               the rendered HTML under the "movieList" element */
            $( "#movieTemplate" ).tmpl( movies )
                .appendTo( "#movieList" );
        }
    });
}

$( "#foreignBtn" ).click( function() {
    getMovies( "Foreign", 0, 4 );
});

$( "#dramaBtn" ).click( function() {
    getMovies( "Drama", 0, 4 );
});
]]></code>
<css><![CDATA[
table {float:left;clear:right;border-collapse:collapse;width:370px;background-color:#f8f8f8;margin:4px;} table td {border:1px solid blue;padding:3px;}
table th {font-weight:bold;border:2px solid blue;padding:1px;} table tbody {border:2px solid blue;} button {float:left;margin:4px;width:70px;}
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <tr>
        <td>${Name}</td>
        <td>{{tmpl(Languages.results) "#languageTemplate"}}</td>
    </tr>
</tmpl>

<tmpl id="languageTemplate" type="text/x-jquery-tmpl"> 
    <em>${Name} </em>
</tmpl>

<table><tbody><tr><th>Title</th><th>Languages</th></tr></tbody>
<tbody id="movieList"></tbody></table>
<button id="foreignBtn">Foreign</button>
<button id="dramaBtn">Drama</button>
]]></html>
</example>

<example>
<desc>Using the <code>options</code> parameter of the <code>{{tmpl}}</code> tag to provide a <code>showLanguage</code> method.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
function getMovies( genre, skip, top ) {
    $.ajax({
        dataType: "jsonp",
        url: "http://odata.netflix.com/Catalog/Genres('" + genre
            + "')/Titles?$format=json&$expand=Languages&$skip="
            + skip + "&$top=" + top,
        jsonp: "$callback",
        success: function( data ) {
            /* Get the movies array from the data */
            var movies = data.d.results;

            /* Remove current set of movie template items */
            $( "#movieList" ).empty();

            /* Render the template items for each movie.
               Pass in the languageOptions map which will be used as
               options parameter on the nested "languageTemplate" template.
               The 'showLanguage' method will be called by the nested template. */
            $( "#movieTemplate" ).tmpl( movies, {
                languageOptions: {
                    showLanguage: function showLanguage( name ) {
                        return name.toUpperCase();
                    }
                }
            }).appendTo( "#movieList" );
        }
    });
}

$( "#foreignBtn" ).click( function() {
    getMovies( "Foreign", 0, 4 );
});

$( "#dramaBtn" ).click( function() {
    getMovies( "Drama", 0, 4 );
});
]]></code>
<css><![CDATA[
table {float:left;clear:right;border-collapse:collapse;width:370px;background-color:#f8f8f8;margin:4px;} table td {border:1px solid blue;padding:3px;}
table th {font-weight:bold;border:2px solid blue;padding:1px;} table tbody {border:2px solid blue;} button {float:left;margin:4px;width:70px;}
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <tr>
        <td>${Name}</td>
        <td>{{tmpl(Languages.results, $item.languageOptions) "#languageTemplate"}}</td>
    </tr>
</tmpl>

<tmpl id="languageTemplate" type="text/x-jquery-tmpl"> 
    <em>${$item.showLanguage(Name)} </em>
</tmpl>

<table><tbody><tr><th>Title</th><th>Languages</th></tr></tbody>
<tbody id="movieList"></tbody></table>
<button id="foreignBtn">Foreign</button>
<button id="dramaBtn">Drama</button>
]]></html>
</example>

<example>
<desc>A tree view, using recursive nested {{tmpl}} tags.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
 /* Hierarchy of named folders */ 
var folders = {
    name: "Samples",
    folders: [
        { name: "API", folders: [
            { name: ".tmpl()"}
        ]},
        { name: "Template markup", folders: [
            { name: "Tags", folders: [
                { name: "{{wrap}}"}
            ]},
        ]},
    ]
};

/* Array for the folder items. Each item can show up in one or more folders */
var samples = [
    { name: "Template in script block", 
        folders: [ ".tmpl()" ], 
        description: "Rendering a template declared in script block" },
    { name: "Template as string", 
        folders: [ ".tmpl()" ], 
        description:"Rendering a template passed as a string" },
    { name: "Render remote data", 
        folders: [ "API" ], 
        description: "Rendering remote data using templates" },
    { name: "Tab View", 
        folders: [ "{{wrap}}", ".tmpl()" ], 
        description: "A tab view, using {{wrap}}" }
];

/* Declare the functions for getting the items and subfolders, etc. 
   These could be simple global functions. 
   (Here we are adding them to the window object, which is equivalent). */
$.extend( window, { 
    getFolderItems: function( tmplItem ) {
        return $.map( samples, function( sample ) {
            return $.inArray( tmplItem.data.name, sample.folders ) > -1 ? sample : null;
        });
    }, 
    getSubFolders: function( tmplItem ) {
        return tmplItem.data.folders || [];
    }, 
    expanderSymbol: function( tmplItem ) {
        return tmplItem.data.expanded ? "-" : "+";
    }
});

$( "#folderTmpl" ).tmpl( folders ).appendTo( "#samplesList" );

$( "#samplesList" )
    .delegate( ".toggle", "click", function() {
        /* Toggle expanded property on data, then update rendering */
        var tmplItem = $.tmplItem( this );
        tmplItem.data.expanded = !tmplItem.data.expanded;
        tmplItem.update();
    })
    .delegate( ".folderItem", "click", function() {
        alert( $.tmplItem( this ).data.description );
    });
]]></code>
<css><![CDATA[
.treeView li li {margin-left:18px;} .expand {vertical-align:middle;margin-right:7px;display:inline-block;border:1px solid #555;text-align:center;height:12px;width:12px;line-height:11px;background-color:#f8f8f8;color:Blue;} 
.treeView, .treeView ul {padding:0;margin:0;} .treeView li {margin-left:8px;list-style-type:none;padding:2px;cursor:pointer;} .treeView li.folderItem {color:Blue;text-decoration:underline;font-style:italic;margin-bottom:4px;}
]]></css>
<html><![CDATA[
<tmpl id="folderTmpl" type="text/x-jquery-tmpl">
    <li class="toggle">
        <span class="expand">${expanderSymbol($item)}</span>
        <span>${name}</span>
    </li>
    {{if expanded}}
        <li>
            <ul>{{tmpl(getFolderItems($item)) "#itemTmpl"}}</ul>
            <ul>{{tmpl(getSubFolders($item)) "#folderTmpl"}}</ul>
        </li>
    {{/if}}
</tmpl>

<tmpl id="itemTmpl" type="text/x-jquery-tmpl">
    <li class="folderItem">${name}</li>
</tmpl>

<ul id="samplesList" class="treeView"><li></li></ul>
]]></html>
</example>
<category name="Template Tags"/>
</entry>
<entry type='method' name="jQuery.tmplItem" return="tmplItem" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em>jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="element" type="Element, jQuery">
<desc>An HTML element (or jQuery object that wraps an element)</desc>
</argument>
</signature>
<desc>Return the <code>tmplItem</code> data structure for the rendered template that the specified element is part of.</desc>

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>
<p>
<code>$.tmplItem( element )</code> provides access to the rendered template item which the element is part of.
</p>
<p>See also <a href="http://api.jquery.com/tmplitem">tmplItem()</a>.</p>
<p>
Typically the element parameter passed to <code>tmplItem()</code>is the <code>this</code> element within an event handler. 
The return value of <code>tmplItem()</code> is a <code>tmplItem</code> data structure providing access to:</p>
<ul>
<li>The HTML elements that the template item is made up of.</li>
<li>The associated data item.</li>
<li>The parent template item, if the template is nested.</li>
<li>The template that was used to render the template item.</li>
<li>User defined parameters or methods, such as any values that were set on the <code>options</code> map, passed to <code>tmpl()</code> when the template was rendered.</li>
</ul>

<p>
The following example shows how to use <code>$.tmplItem()</code> to get information about the rendered template:</p>
<pre>
function myClickHandler() {
    var tmplItem = $.tmplItem( this );
    alert( "Description: " + tmplItem.data.description );
}
</pre>
<h4>Building Interactive Ajax Applications</h4>
<p>
<code>.tmplItem()</code> and <code>jQuery.tmplItem()</code> make it easy to use templates in scenarios beyond simple string concatenation and read-only rendering. They let you create fully-fledged interactive client-side Ajax applications in which the code needs to perform actions like the following:</p>
<ul>
<li>Accessing the associated data item.</li>
<li>Modifying the data item.</li>
<li>Accessing HTML elements that make up the rendered template item.</li>
<li>Updating (re-rendering) the template item, with modified data, modified user-defined parameters, or using a different template</li>
</ul>
<p><strong>Example:</strong> Dynamically switching templates for a template item.:</p>
<pre>
// Get the compiled detail template
var detailTemplate = $( "#detailTemplate" ).template();

// Add an onclick handler for template items currently 
// using the summary template
$(".movieSummary").live( "click", function () {
    // Get the data structure for the template item 
    // which this clicked element belongs to
    var tmplItem = $.tmplItem(this);

    // Set the template on this item to the detail template
    tmplItem.tmpl = detailTemplate;

    // re-render
    tmplItem.update();
})
</pre>

</longdesc>

<example>
<desc>Access the data, and set selection on the item.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "The Red Violin", ReleaseYear: "1998" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
    { Name: "The Inheritance", ReleaseYear: "1976" }
];
var selectedItem =  null;

/* Render the template with the movies data */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );

/* Add an onclick handler for the movie template items */
$( ".movieName" ).live( "click", function() {

    if ( selectedItem ) {
        $( selectedItem.nodes ).css( "backgroundColor", "#f8f8f8" );
    }

    /* Get the data structure for the template item 
       which this clicked element belongs to */
    selectedItem = $.tmplItem( this );

    $( selectedItem.nodes ).css( "backgroundColor", "yellow" );

    alert( "'" + selectedItem.data.Name + "' was released in " 
        + selectedItem.data.ReleaseYear + "." ); 
});
]]></code>
<css><![CDATA[
#movieList { cursor:pointer; color:blue; margin:8px; background-color:#f8f8f8; }
#movieList li:hover { color:red; }
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li><b class="movieName">${Name}</b></li>
</tmpl>

Click for details:
<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Master detail view.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var people = [
    { firstName: "Peter", lastName: "Jones" },
    { firstName: "Eva", lastName: "Smolinski" }
];

var selectedItem = null;

function renderTemplate( container, template, data ) {
    $( container ).empty();
    $( template ).tmpl( data ).appendTo( container );
}

/* Render the list */
renderTemplate( "#peopleList", "#listItemTemplate", people );

$("#peopleList")
    .delegate( "tr", "click", function () {

        if ( selectedItem ) {
            $( selectedItem.nodes ).removeClass( "selected");
        }

        /* Set selection on the clicked item */
        selectedItem = $.tmplItem(this);
        $( selectedItem.nodes ).addClass( "selected");

        /* Render the detail view for this data item */
        renderTemplate( "#personDetail", "#detailTemplate", selectedItem.data );
    });
]]></code>
<css><![CDATA[
table { cursor:pointer; border-collapse:collapse; float: left; clear: both; } table tr { border:1px solid blue; color:blue; height:25px; } table tr:hover { color:red; }
table, #personDetail > div { border:2px solid blue; width:220px; margin:8px 0 4px 0; background-color:#f8f8f8; } table td, #personDetail div div { padding:3px; margin:3px; }
.selected { background-color:yellow; } #personDetail input { float:right; width:125px; } #personDetail { float:left; margin-left:10px; }
]]></css>
<html><![CDATA[
<tmpl id="listItemTemplate" type="text/x-jquery-tmpl"> 
    <tr><td>
        ${firstName} ${lastName} 
    </td></tr>
</tmpl>

<tmpl id="detailTemplate" type="text/x-jquery-tmpl"> 
    <div>
        <div>First Name: <em>${firstName}</em></div>
        <div>Last Name: <em>${lastName}</em></div>
    </div>
</tmpl>

<div style="float:left;">Click for details:<div>
<table><tbody id="peopleList"></tbody></table>

<div id="personDetail"></div>
]]></html>
</example>

<example>
<desc>Dynamic switching of templates.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "The Red Violin", ReleaseYear: "1998", Director: "François Girard" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999", Director: "Stanley Kubrick" },
    { Name: "The Inheritance", ReleaseYear: "1976", Director: "Mauro Bolognini" }
];
var selectedItem = null;

/* Render the summaryTemplate with the "movies" data */
$( "#summaryTemplate" ).tmpl( movies ).appendTo( "#movieList" );

/* Add onclick handlers for movie template items
   using the summary or details template */
$("#movieList")
.delegate( ".movieSummary", "click", function () {
    if (selectedItem) {
        // Set the template on the previously selected item
        // back to the summary template
        selectedItem.tmpl = $( "#summaryTemplate" ).template();
        selectedItem.update();
    }
    /* Get the data structure for the template item 
       which this clicked element belongs to, and make
       it the selected item */
    selectedItem = $.tmplItem(this);

    /* Set the template on this item to the detail template */
    selectedItem.tmpl = $( "#detailTemplate" ).template();
    selectedItem.update();
})
.delegate( ".movieDetail", "click", function () {
    /* Set the template on this item to the summary template */
    selectedItem.tmpl = $( "#summaryTemplate" ).template();
    selectedItem.update();
    selectedItem = null;
});
]]></code>
<css><![CDATA[
table { cursor:pointer; border-collapse:collapse; border:2px solid blue; width:300px; margin:8px; }
table tr { border:1px solid blue; color:blue; background-color:#f8f8f8; } table td { padding:3px; } table tr:hover { color:red; }
.movieDetail { background-color:yellow; } .movieDetail.row1 { border-bottom:none; } .movieDetail.row2 { border-top:none; }
]]></css>
<html><![CDATA[
<tmpl id="summaryTemplate" type="text/x-jquery-tmpl">
    <tr class='movieSummary'><td colspan='2'>${Name}</td></tr>
</tmpl>

<tmpl id="detailTemplate" type="text/x-jquery-tmpl">
    <tr class='movieDetail row1'><td colspan='2'>${Name}</td></tr><tr class='movieDetail row2'><td>${ReleaseYear}</td><td>Director: ${Director}</td></tr>
</tmpl>

Click for details:
<table><tbody id="movieList"></tbody></table>
]]></html>
</example>
<category name="Templates"/>
</entry>

<entry type='method' name="jQuery.template" return="function" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="name" type="String">
    <desc>A string naming the compiled template.</desc>
</argument>
<argument name="template" type="String, Element, jQuery">
    <desc>The HTML markup and/or text to be used as template. Can be a string, or an HTML element (or jQuery object wrapping an element) whose content is to be used as template</desc>
</argument>
</signature>
<desc>Create a reusable named template (compiled from markup).</desc> 

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>

<p>This method compiles the markup in the <code>template</code> parameter as a named template, which can be referenced using the string specified in the <code>name</code> parameter.
</p>
<p>
The return value is the compiled-template function. 
</p>
<p>See also <a href="http://api.jquery.com/template">template()</a>.</p>

<blockquote>
  <p>Note: The named template is added to the <code>$.templates</code> map.</p>
  <ul>
    <li>To determine if a string <code>"someName"</code> is the name of a named template, test whether <code>$.template["someName"]</code> is defined.</li>
    <li>To remove a previously created named template, use<br/> <code>delete $.template["someName"];</code></li>
  </ul>
</blockquote>
<p>
<strong>Example:</strong> Create a compiled template associated with the name "summaryTemplate" and then reference it by name for rendering: 
</p>
<pre>
// Convert the markup string into a named template
$.template( "summaryTemplate", "&lt;li&gt;${Name}&lt;/li&gt;" );

function renderList() {
    // Render the movies data using the named template: "summaryTemplate"
    $.tmpl( "summaryTemplate", movies ).appendTo( "#moviesList" );
}
</pre>
<p>
<strong>Example:</strong> Use the return value rather than the <code>name</code> string to reference the compiled template:
</p>
<pre>
// Convert the markup string into a compiled template
var myTemplate = $.template( null, "&lt;li&gt;${Name}&lt;/li&gt;" ); 

function renderList() {
    // Render movies data using the compiled template: myTemplate
    $.tmpl( myTemplate, movies ).appendTo( "#moviesList" );
}
</pre>
<p>
<strong>Example:</strong> Create a named template and reference it by name as a nested template: 
</p>
<pre>
&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt;
    {{tmpl "summaryTemplate"}}
    &lt;tr&gt;&lt;td&gt;Director: ${Director}&lt;/td&gt;&lt;/tr&gt;
&lt;/script&gt;
___________

// Convert the markup string into a named template,
// referenced by the {{tmpl}} tag
$.template( "summaryTemplate", "&lt;tr&gt;&lt;td&gt;${Name}&lt;/td&gt;&lt;/tr&gt;" );

// Render the movies data, using the named template as a nested template
$( "#movieTemplate" ).tmpl( movies ).appendTo( "#movieList" );
</pre>

<h4 id="optimizing-template-rendering">Optimizing Template Rendering</h4>
<p>
When a template is rendered, using <a href="http://api.jquery.com/tmpl">.tmpl()</a> or <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>, the markup is first converted into a compiled-template function. In the case of markup obtained from a string, the use of <code>.template()</code> as in the above examples ensures that the conversion from markup to a compiled-template function only happens once. 
</p>
<p>
On the other hand, passing a markup string template directly to <code>.tmpl()</code> or to <code>{{tmpl}}</code> for rendering will not be optimal from a performance point of view, since the markup will be re-compiled every time:
</p>
<pre>
var markup = "&lt;li&gt;${Name}&lt;/li&gt;";

function renderList() {
  // Sub-optimal: the markup string will be
  // recompiled each time renderList is called
  $.tmpl( markup, movies ).appendTo( "#moviesList" );
}
</pre>
<p>
Note: In the case of inline templates declared within a script block, caching occurs automatically, so the following example <em>does</em> correspond to best practice:
</p>
<p>
<strong>Example:</strong> Rendering an inline template directly without compiling as a named template.
</p>
<pre>
&lt;script id="summaryTemplate" type="text/x-jquery-tmpl"&gt;
    &lt;li&gt;${Name}&lt;/li&gt;
&lt;/script&gt;
___________

function renderList() {
  // The template will be compiled only once,
  // so this is approach can be optimal.
  $( "#summaryTemplate" ).tmpl( movies ).appendTo( "#moviesList" );
}
</pre>

</longdesc>

<example>
<desc>Render template obtained from a markup string.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
  var movies = [
  { Name: "The Red Violin", ReleaseYear: "1998", Director: "François Girard" },
  { Name: "Eyes Wide Shut", ReleaseYear: "1999", Director: "Stanley Kubrick" },
  { Name: "The Inheritance", ReleaseYear: "1976", Director: "Mauro Bolognini" }
  ];

var markup = "<tr><td colspan='2'>${Name}</td><td>Released: ${ReleaseYear}</td><td>Director: ${Director}</td></tr>"

/* Compile markup string as a named template */
$.template( "movieTemplate", markup );

/* Render the named template */
$( "#showBtn" ).click( function() {
  $( "#movieList" ).empty();
  $.tmpl( "movieTemplate", movies ).appendTo( "#movieList" );
});
]]></code>
<css><![CDATA[
table { border-collapse:collapse; margin:8px; background-color:#f8f8f8; }
table td { border:1px solid blue; padding:3px; }
]]></css>
<html><![CDATA[
<button id="showBtn">Show movies</button><br/>
<table><tbody id="movieList"></tbody></table>
]]></html>
</example>

<example>
<desc>Switch between templates obtained from markup strings.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
  { Name: "The Red Violin", ReleaseYear: "1998", Director: "François Girard" },
  { Name: "Eyes Wide Shut", ReleaseYear: "1999", Director: "Stanley Kubrick" },
  { Name: "The Inheritance", ReleaseYear: "1976", Director: "Mauro Bolognini" }
];

function renderTemplate( container, template, data ) {
  $( container ).empty();
  $.tmpl( template, data ).appendTo( container );
}

/* Compile markup as named templates */
$.template(
  "titleTemplate",
  "<tr><td>${Name}</td></tr>"
);
$.template(
  "detailTemplate",
  "<tr><td colspan='2'>${Name}</td><td>Released: ${ReleaseYear}</td><td>Director: ${Director}</td></tr>"
);

var details = false;

$( "#switchBtn" ).click( function() {
  details = !details;
  $(this).text( details ? "Show titles" : "Show full details" );
  /* Render using the other named template */
  renderTemplate( "#movieList", (details ? "detailTemplate" : "titleTemplate"), movies );
});

renderTemplate( "#movieList", "titleTemplate", movies );
]]></code>
<css><![CDATA[
table { border-collapse:collapse; margin:8px; background-color:#f8f8f8; }
table td { border:1px solid blue; padding:3px; }
]]></css>
<html><![CDATA[
<button id="switchBtn">Show full details</button><br/>
<table><tbody id="movieList"></tbody></table>
]]></html>
</example>

<example height="340">
<desc>Use a markup string as a nested template.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
  { Name: "The Red Violin", Director: "François Girard" },
  { Name: "Eyes Wide Shut", Director: "Stanley Kubrick" },
  { Name: "The Inheritance", Director: "Mauro Bolognini" }
];

/* Convert the markup string into a named template,
   referenced by the {{tmpl}} tag */
$.template( "titleTemplate", "<tr class='title'><td>${Name}</td></tr>" );

/* Render the movies data, using the named template as a nested template */
$( "#movieTemplate" ).tmpl( movies ).appendTo( "#movieList" );
]]></code>
<css><![CDATA[
table { border-collapse:collapse; border:2px solid blue; margin:8px; background-color:#f8f8f8; }
table tr { border:1px solid blue; } table td { padding:2px; }
.title { border-bottom:none; } .detail { border-top:none; }
]]></css>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
  {{tmpl "titleTemplate"}}
  <tr class="detail"><td>Director: ${Director}</td></tr>
</tmpl>

<table><tbody id="movieList"></tbody></table>
]]></html>
</example>
<category name="Templates"/>
</entry>

<entry type='method' name="jQuery.template" return="function" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="template" type="String">
<desc>The template markup to be compiled, or a string corresponding to a named template.</desc>
</argument>
</signature>
<desc>Returns a compiled-template function.</desc> 

<longdesc>
<p>Note: For information about how to render templates, see <a href="http://api.jquery.com/tmpl">.tmpl()</a> and <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>
<p>
If the <code>template</code> parameter is the name string for a named template created using <code>$.template( name, template )</code>, this method returns the compiled template for the named template (equivalent to <code>$.template[name]</code>).
</p>
<p>
Otherwise, if the <code>template</code> parameter is a string containing HTML markup, then this method will return a compiled template for the markup provided.
</p>
<p>
If the <code>template</code> parameter is a string containing pure text (no HTML tags), then the string is treated as a selector for an inline template, whose content will be used as markup. Similarly if <code>template</code> is an HTML element (or jQuery object wrapping an element), then the content will be used as markup for the returned compiled template.
</p>
<p>
<strong>Example:</strong> Switch the template item to a different template, using $.template( name ), : 
<pre><![CDATA[
// Create the compiled templates
$.template( "summaryTemplate", "<tr>...</tr>" );
$.template( "detailTemplate", "<tr>...</tr>" );

// Render the summaryTemplate with the "movies" data 
$.tmpl( "summaryTemplate", movies ).appendTo( "#movieList" );

$( "tr" ).click( function () {
    // Switch the template for this template item to
    // a different named template, then update the rendered item
    var tmplItem = $.tmplItem(this);
    tmplItem.tmpl = $.template( "detailTemplate" );
    tmplItem.update();
});
]]></pre>
</p>

</longdesc>

<example>
<desc>Dynamic switching of templates, using $.template() to obtain compiled template.</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
  { Name: "The Red Violin", ReleaseYear: "1998", Director: "François Girard" },
  { Name: "Eyes Wide Shut", ReleaseYear: "1999", Director: "Stanley Kubrick" },
  { Name: "The Inheritance", ReleaseYear: "1976", Director: "Mauro Bolognini" }
];

var selectedItem = null;

/* Create the compiled templates */
$.template(
  "summaryTemplate",
  "<tr class='movieSummary'><td colspan='2'>${Name}</td></tr>"
);
$.template(
  "detailTemplate",
  "<tr class='movieDetail row1'><td colspan='2'>${Name}</td></tr><tr class='movieDetail row2'><td>${ReleaseYear}</td><td>Director: ${Director}</td></tr>"
);

/* Render the summaryTemplate with the "movies" data */ 
$.tmpl( "summaryTemplate", movies ).appendTo( "#movieList" );

$( "#movieList" )
.delegate( ".movieSummary", "click", function () {
  if (selectedItem) {
    /* Switch the template for this template item to
    the named template, then update the rendered item */
    selectedItem.tmpl = $.template( "summaryTemplate" );
    selectedItem.update();
  }
  selectedItem = $.tmplItem(this);
  /* Switch the template for this template item */
  selectedItem.tmpl = $.template( "detailTemplate" );
  selectedItem.update();
})
.delegate( ".movieDetail", "click", function () {
  /* Switch the template for this template item */
  selectedItem.tmpl = $.template( "summaryTemplate" );
  selectedItem.update();
  selectedItem = null;
});
]]></code>
<css><![CDATA[
  table { cursor:pointer; border-collapse:collapse; 
        border:2px solid blue; width:300px; margin:8px; }
  table tr { border:1px solid blue; color:blue; background-color:#f8f8f8; } 
  table td { padding:3px; } table tr:hover { color:red; }
  .movieDetail { background-color:yellow; } 
  .movieDetail.row1 { border-bottom:none; } 
  .movieDetail.row2 { border-top:none; }
]]></css>
<html><![CDATA[
Click for details:
<table><tbody id="movieList"></tbody></table>
]]></html>
</example>
<category name="Templates"/>
</entry>

<entry type='method' name=".tmpl" return="jQuery" plugin="jQuery Templates">
<download>
<p>This documentation topic concerns the <em> jQuery Templates</em> plugin (jquery-tmpl), which can be downloaded from: <a href="http://github.com/jquery/jquery-tmpl">http://github.com/jquery/jquery-tmpl</a>.</p>
</download>
<signature>
<added>1.4.3</added>
<argument name="data" type="Object" optional="true">
<desc>The data to render. This can be any JavaScript type, including Array or Object.</desc>
</argument>
<argument name="options" type="Options" optional="true">
<desc>An optional map of user-defined key-value pairs. Extends the <code>tmplItem</code> data structure, available to the template during rendering.</desc>
</argument>
</signature>
<desc>Take the first element in the matched set and render its content as a template, using the specified data.</desc>

<longdesc>
<p>Example:</p> 
<pre>$( "#myTemplate" ).tmpl( myData )</pre>
<p>
If <code>data</code> is an array, the template is rendered once for each data item in the array. If <code>data</code> is an object, or if the <code>data</code> parameter is missing or null, a single template item is rendered.
</p>
<p>
The return value is a jQuery collection of elements made up of the rendered template items (one for each data item in the array). If the template contains only one top-level element, then there will be one element for each data item in the array.
</p>
<p>You can insert the template items into the HTML DOM using <code>.appendTo</code>, <code>.prependTo</code>, <code>.insertAfter</code> or <code>.insertBefore</code>, as in the following example:</p>
<pre>$( "#myTemplate" ).tmpl( myData ).appendTo( "#target" );</pre>

<p>See also <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>.</p>
<p>The following example shows how to use <code>.tmpl()</code> to render local data using an inline template.</p>
<pre>&lt;script id="movieTemplate" type="text/x-jquery-tmpl"&gt;
    &lt;li&gt;&lt;b&gt;${Name}&lt;/b&gt; (${ReleaseYear})&lt;/li&gt;
&lt;/script&gt;

&lt;script type="text/javascript"&gt;
    var movies = [
        { Name: "The Red Violin", ReleaseYear: "1998" },
        { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
        { Name: "The Inheritance", ReleaseYear: "1976" }
    ];

    // Render the template with the movies data and insert
    // the rendered HTML under the "movieList" element
    $( "#movieTemplate" ).tmpl( movies )
        .appendTo( "#movieList" );
&lt;/script&gt;

&lt;ul id="movieList"&gt;&lt;/ul&gt;
</pre>

<h4>Using Remote Data</h4>
<p>
Typically the data is not local and is instead obtained using an Ajax request to a remote service or page, as in the following example: 
</p>
<pre>
$.ajax({
    dataType: "jsonp",
    url: moviesServiceUrl,
    jsonp: "$callback",
    success: showMovies
});

// Within the callback, use .tmpl() to render the data.
function showMovies( data ) {
    // Render the template with the "movies" data and insert
    // the rendered HTML under the &#39;movieList&#39; element
    $( "#movieTemplate" ).tmpl( data )
        .appendTo( "#movieList" );
}
</pre>

<h4>The Container Element for the Template</h4>
<p>
You can get the markup for the template from inline markup in the page, or from a string (possibly computed, or obtained remotely). For an example of how to get the markup from a string, see <a href="http://api.jquery.com/jquery.tmpl">jQuery.tmpl()</a>. 
</p>
<p>
If a template is defined inline in the page, you can use  <code>$( selector ).tmpl( data )</code>, where <code>selector</code> is a selector referencing the container element that wraps the markup. The container can be any element, such as a <code>&lt;div&gt;</code> element whose style attribute includes <code>display:none</code>. However, this can result in invalid HTML or lead to side effects as a result of the browser parsing the markup and loading it into the DOM. Therefore, a preferred approach is to use a script tag such as <code>&lt;script id="myContainer" type="text/x-jquery-tmpl"&gt;</code> to wrap the markup. For the browser, the content will then be treated simply as text.  
</p>

<h4>Caching the Template</h4>
<p>
When a template is rendered, the markup is first converted into a compiled-template function. In the case of inline markup, calling <code>$( "#myContainer" ).tmpl( myData )</code> automatically causes the compiled template to be cached. (The cached template is associated with the DOM element that wraps the markup, using the jQuery <code>.data()</code> feature). 
</p>
<p>
For convenience, you can also use <code>$( "#myContainer" ).template( name )</code> so that you can reference the cached template by name. (See <a href="http://api.jquery.com/template">.template()</a> for examples).
</p>

<h4>Template Tags, Expressions, and Template Variables</h4>
<p>Template tags such as the <code>${}</code> tag can used within jQuery templates in addition to text and HTML markup to enable a number of scenarios such as composition of templates, iteration over hierarchical data, parameterization of template rendering, etc. Template tags can render content based on the values of data item fields or template variables such as <code>$item</code> (corresponding to the template item), as well as expressions and function calls. See the documentation topics for each template tag: <a href="http://api.jquery.com/template-tag-equal">${}</a>, <a href="http://api.jquery.com/template-tag-each">{{each}}</a>, <a href="http://api.jquery.com/template-tag-if">{{if}}</a>, <a href="http://api.jquery.com/template-tag-else">{{else}}</a>, <a href="http://api.jquery.com/template-tag-html">{{html}}</a>, <a href="http://api.jquery.com/template-tag-tmpl">{{tmpl}}</a> and <a href="http://api.jquery.com/template-tag-wrap">{{wrap}}</a>. </p>

<h4>The <code>options</code> Parameter, and Template Items</h4>
<p>Each template item (the result of rendering a data item with the template) is associated with a <code>tmplItem</code> data structure, which can be accessed using <a href="http://api.jquery.com/jquery.tmplitem">jQuery.tmplItem()</a> and <a href="http://api.jquery.com/tmplitem">.tmplItem()</a>, or the <code>$item</code> template variable. Any fields or anonomyous methods passed in with the <code>options</code> parameter of <code>.tmpl()</code> will extend the <code>tmplItem</code> data structure, and so be available to the template as in the following example:</p>
<h6>Code:</h6>
<pre>
// Render the template with the movies data
$( "#movieTemplate" ).tmpl( movies,
    { 
        myValue: "somevalue",
        myMethod: function() { 
            return "something";
        } 
    } 
).appendTo( "#movieList" );
]]&gt;&lt;/pre&gt;
&lt;h6&gt;Template:&lt;/h6&gt;
&lt;pre&gt;&lt;![CDATA[
&lt;li&gt;
    Some content: ${$item.myMethod()}.&lt;br/&gt;
    More content: ${$item.myValue}.
&lt;/li&gt;
</pre>

</longdesc>

<example>
<desc>Render local data using .tmpl().</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
var movies = [
    { Name: "The Red Violin", ReleaseYear: "1998" },
    { Name: "Eyes Wide Shut", ReleaseYear: "1999" },
    { Name: "The Inheritance", ReleaseYear: "1976" }
];

/* Render the template with the movies data and insert
   the rendered HTML under the "movieList" element */
$( "#movieTemplate" ).tmpl( movies )
    .appendTo( "#movieList" );
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li><b>${Name}</b> (${ReleaseYear})</li>
</tmpl>

<ul id="movieList"></ul>
]]></html>
</example>

<example>
<desc>Render data from a remote service using .tmpl().</desc>
<js src="http://code.jquery.com/jquery-latest.min.js" /> 
<js src="http://nje.github.com/jquery-tmpl/jquery.tmpl.js" /> 
<code><![CDATA[
function getMovies( genre, skip, top ) {
    $.ajax({
        dataType: "jsonp",
        url: "http://odata.netflix.com/Catalog/Genres('" + genre
            + "')/Titles?$format=json&$skip="
            + skip + "&$top=" + top,
        jsonp: "$callback",
        success: function( data ) {
            /* Get the movies array from the data */
            var movies = data.d;
                    
            /* Remove current set of movie template items */
            $( "#movieList" ).empty();
            
            /* Render the template with the movies data and insert
               the rendered HTML under the "movieList" element */
            $( "#movieTemplate" ).tmpl( movies )
                .appendTo( "#movieList" );
        }
    });
}

$( "#cartoonsBtn" ).click( function() {
    getMovies( "Cartoons", 0, 6 );
});

$( "#dramaBtn" ).click( function() {
    getMovies( "Drama", 0, 6 );
});
]]></code>
<html><![CDATA[
<tmpl id="movieTemplate" type="text/x-jquery-tmpl"> 
    <li><b>${Name}</b> (${ReleaseYear})</li>
</tmpl>

<button id="cartoonsBtn">Cartoons</button>
<button id="dramaBtn">Drama</button>

<ul id="movieList"></ul>
]]></html>
</example>
<category name="Templates"/>
</entry>
  </plugins>
  </api>

<!-- Performance optimized by W3 Total Cache. Learn more: http://www.w3-edge.com/wordpress-plugins/

Minified using disk
Page Caching using disk (enhanced)
Database Caching 16/28 queries in 0.083 seconds using disk

Served from: api.jquery.com @ 2010-11-28 07:49:51 -->