Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

126 lines (124 sloc) 6.692 kb
<?xml version="1.0"?>
<entries>
<entry type="method" name="html" return="String">
<title>.html()</title>
<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, <code>.html()</code> can be used to get the contents of any element. If the selector expression matches more than one element, only the first match will have its HTML content returned. Consider this code:</p>
<pre><code>$('div.demo-container').html();</code></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><code>&lt;div class="demo-container"&gt;
&lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>The result would look like this:</p>
<pre><code>&lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;</code></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 slug="attributes"/>
<category slug="manipulation/dom-insertion-inside"/>
<category slug="version/1.0"/>
<category slug="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.
Within the function, <code>this</code> refers to the current element in the set.</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 <code>.html()</code> is used to set an element's content,
any content that was in that element is completely replaced by the new content.
Additionally, jQuery removes other constructs such as data and event
handlers from child elements before replacing those elements with the new content.</p>
<p>Consider the following HTML:</p>
<pre><code>&lt;div class="demo-container"&gt;
&lt;div class="demo-box"&gt;Demonstration Box&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>The content of <code>&lt;div class="demo-container"&gt;</code> can be set like this:</p>
<pre><code>$('div.demo-container')
.html('&lt;p&gt;All new content. &lt;em&gt;You bet!&lt;/em&gt;&lt;/p&gt;');</code></pre>
<p>That line of code will replace everything inside <code>&lt;div class="demo-container"&gt;</code>:</p>
<pre><code>&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;</code></pre>
<p>As of jQuery 1.4, the <code>.html()</code> method allows the HTML content to be set by passing in a function.</p>
<pre><code>$('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;';
});</code></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>
<p><strong>Note:</strong> In Internet Explorer up to and including version 9, setting the text content of an HTML element may corrupt the text nodes of its children that are being removed from the document as a result of the operation. If you are keeping references to these DOM elements and need them to be unchanged, use <code>.empty().html(string)</code> instead of <code>.html(string)</code> so that the elements are removed from the document before the new string is assigned to the element.</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 slug="attributes"/>
<category slug="manipulation/dom-insertion-inside"/>
<category slug="version/1.0"/>
<category slug="version/1.4"/>
</entry>
</entries>
Jump to Line
Something went wrong with that request. Please try again.