Skip to content

Commit

Permalink
Clarify meaning of jQuery(html, ownerDocument). Close gh-151.
Browse files Browse the repository at this point in the history
  • Loading branch information
dmethvin committed May 19, 2013
1 parent 4664f1b commit 0fbabfe
Showing 1 changed file with 2 additions and 1 deletion.
3 changes: 2 additions & 1 deletion entries/jQuery.xml
Expand Up @@ -144,7 +144,7 @@ $( "div > p").css("border", "1px solid gray");
<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>
<desc>A document in which the new elements will be created.</desc>
</argument>
</signature>
<signature>
Expand All @@ -162,6 +162,7 @@ $( "div > p").css("border", "1px solid gray");
<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 starts with <code>&lt;tag ... &gt;</code>). 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. You can perform any of the usual jQuery methods on this object:</p>
<pre><code>$( "&lt;p id='test'&gt;My &lt;em&gt;new&lt;/em&gt; text&lt;/p&gt;" ).appendTo( "body" );</code></pre>
<p>For explicit parsing of a string to HTML, use the <a href="/jQuery.parseHTML/">$.parseHTML()</a> method.</p>
<p>By default, elements are created with an <code>ownerDocument</code> matching the document into which the jQuery library was loaded. Elements being injected into a different document should be created using that document, e.g., <code>$("&lt;p&gt;hello iframe&lt;/p&gt;", $("#myiframe").prop("contentWindow").document)</code>.</p>
<p>If 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. In most cases, 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 (with optional closing tag or quick-closing) — <code>$( "&lt;img&#xA0;/&gt;" )</code> or <code>$( "&lt;img&gt;" )</code>, <code>$( "&lt;a&gt;&lt;/a&gt;" )</code> or <code>$( "&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. As mentioned, jQuery uses the browser"s <code>.innerHTML</code> property to parse the passed HTML and insert it into the current document. During this process, some browsers filter out certain elements such as <code>&lt;html&gt;</code>, <code>&lt;title&gt;</code>, or <code>&lt;head&gt;</code> elements. As a result, the elements inserted may not be representative of the original string passed.</p>
<p>Filtering isn't, however, limited to these tags. For example, Internet Explorer prior to version 8 will also 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>
Expand Down

0 comments on commit 0fbabfe

Please sign in to comment.