entries/jQuery.parseHTML.xml

<?xml version="1.0"?>
<entry type="method" name="jQuery.parseHTML" return="Array">
  <title>jQuery.parseHTML()</title>
  <desc>Parses a string into an array of DOM nodes.</desc>
  <signature>
    <added>1.8</added>
    <argument name="data" type="String">
      <desc>HTML string to be parsed</desc>
    </argument>
    <argument name="context" type="Element" optional="true" default="document">
      <desc>Document element to serve as the context in which the HTML fragment will be created</desc>
    </argument>
    <argument name="keepScripts" type="Boolean" optional="true" default="false">
      <desc>A Boolean indicating whether to include scripts passed in the HTML string</desc>
    </argument>
  </signature>
  <longdesc>
    <p><code>jQuery.parseHTML</code> uses native methods to convert the string to a set of DOM nodes, which can then be inserted into the document. These methods do render all trailing or leading text (even if that's just whitespace). To prevent trailing/leading whitespace from being converted to text nodes you can pass the HTML string through <a href="/jQuery.trim/"><code>jQuery.trim</code></a>.</p>
    <p>By default, the <code>context</code> is the current <code>document</code> if not specified or given as <code>null</code> or <code>undefined</code>. If the HTML was to be used in another document such as an iframe, that frame's document could be used.</p>
    <p>As of 3.0 the default behavior is changed. If the <code>context</code> is not specified or given as <code>null</code> or <code>undefined</code>, a new <code>document</code> is used. This can potentially improve security because inline events will not execute when the HTML is parsed. Once the parsed HTML is injected into a document it does execute, but this gives tools a chance to traverse the created DOM and remove anything deemed unsafe. This improvement does not apply to internal uses of <code>jQuery.parseHTML</code> as they usually pass in the current <code>document</code>. Therefore, a statement like <code>$( "#log" ).append( $( htmlString ) )</code> is still subject to the injection of malicious code.</p>
  <h2>Security Considerations</h2>
  <p>Most jQuery APIs that accept HTML strings will run scripts that are included in the HTML. <code>jQuery.parseHTML</code> does not run scripts in the parsed HTML unless <code>keepScripts</code> is explicitly <code>true</code>. However, it is still possible in most environments to execute scripts indirectly, for example via the <code>&lt;img onerror&gt;</code> attribute. The caller should be aware of this and guard against it by cleaning or escaping any untrusted inputs from sources such as the URL or cookies. For future compatibility, callers should not depend on the ability to run <em>any</em> script content when <code>keepScripts</code> is unspecified or <code>false</code>.</p>
  </longdesc>
  <example>
    <desc>Create an array of DOM nodes using an HTML string and insert it into a div.</desc>
    <html><![CDATA[
<div id="log">
  <h3>Content:</h3>
</div>
]]></html>
    <code><![CDATA[
var $log = $( "#log" ),
  str = "hello, <b>my name is</b> jQuery.",
  html = $.parseHTML( str ),
  nodeNames = [];

// Append the parsed HTML
$log.append( html );

// Gather the parsed HTML's node names
$.each( html, function( i, el ) {
  nodeNames[ i ] = "<li>" + el.nodeName + "</li>";
});

// Insert the node names
$log.append( "<h3>Node Names:</h3>" );
$( "<ol></ol>" )
  .append( nodeNames.join( "" ) )
  .appendTo( $log );
]]></code>
  </example>
  <category slug="utilities"/>
  <category slug="version/1.8"/>
</entry>