Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Editorial: Upstream the insertAdjacentHTML method from DOM Parsing #10282

Merged
merged 2 commits into from
Apr 19, 2024
Merged

Editorial: Upstream the insertAdjacentHTML method from DOM Parsing #10282

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d244a1
Upstream the insertAdjacentHTML method from DOM Parsing and Serializa…
lukewarlow Apr 16, 2024
a144aa1
Fix missed rename
domenic Apr 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
134 changes: 134 additions & 0 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -112353,6 +112353,7 @@ document.body.appendChild(frame)</code></pre>

[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] <span data-x="tt-htmlstring">HTMLString</span> <span data-x="dom-Element-innerHTML">innerHTML</span>;
[<span>CEReactions</span>] attribute [<span>LegacyNullToEmptyString</span>] <span data-x="tt-htmlstring">HTMLString</span> <span data-x="dom-Element-outerHTML">outerHTML</span>;
[<span>CEReactions</span>] undefined <span data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML</span>(DOMString position, <span data-x="tt-htmlstring">HTMLString</span> string);
};

partial interface <span id="ShadowRoot-partial">ShadowRoot</span> {
Expand Down Expand Up @@ -112861,6 +112862,139 @@ enum <dfn enum>DOMParserSupportedType</dfn> {

</div>

<h4>The <code data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code> method</h4>

<p class="XXX">The <code data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code>
method has a number of outstanding issues in the <cite>DOM Parsing and Serialization</cite> <a
href="https://github.com/w3c/DOM-Parsing/issues">issue tracker</a>, documenting various problems
with its specification.</p>

<dl class="domintro">
<dt><code data-x=""><var>element</var>.<span subdfn data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML</span>(<var>position</var>, <var>string</var>)</code></dt>
<dd>
<p>Parses <var>string</var> as HTML or XML and inserts the resulting nodes into the tree in
the position given by the <var>position</var> argument, as follows:</p>

<dl>
<dt>"<code data-x="">beforebegin</code>"</dt>
<dd>Before the element itself (i.e., after <var>element</var>'s previous sibling)</dd>

<dt>"<code data-x="">afterbegin</code>"</dt>
<dd>Just inside the element, before its first child.</dd>

<dt>"<code data-x="">beforeend</code>"</dt>
<dd>Just inside the element, after its last child.</dd>

<dt>"<code data-x="">afterend</code>"</dt>
<dd>After the element itself (i.e., before <var>element</var>'s next sibling)</dd>
</dl>

<p>Throws a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code> if the arguments
have invalid values (e.g., in the case of an <span data-x="XML documents">XML document</span>,
if the given string is not well-formed).</p>

<p>Throws a <span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>
if the given position isn't possible (e.g. inserting elements after the root element of a
<code>Document</code>).</p>
</dd>
</dl>

<p class="warning">This method performs no sanitization to remove potentially-dangerous elements
and attributes like <code>script</code> or <span>event handler content attributes</span>.</p>

<div w-nodev>

<p><code>Element</code>'s <dfn method for="Element"><code
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML(<var>position</var>,
<var>string</var>)</code></dfn> method steps are:</p>

<ol>
<li><p>Let <var>context</var> be null.</p></li>

<li><p>Use the first matching item from this list:</p>
<dl class=switch>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforebegin</code>"</dt>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterend</code>"</dt>
<dd>
<ol>
lukewarlow marked this conversation as resolved.
Show resolved Hide resolved
<li><p>Set <var>context</var> to <span>this</span>'s <span
data-x="dom-parent">parent</span>.<p></li>

lukewarlow marked this conversation as resolved.
Show resolved Hide resolved
<li><p>If <var>context</var> is null or a <code>Document</code>, throw a
<span>"<code>NoModificationAllowedError</code>"</span> <code>DOMException</code>.<p></li>
lukewarlow marked this conversation as resolved.
Show resolved Hide resolved
</ol>
</dd>

<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterbegin</code>"</dt>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforeend</code>"</dt>
<dd>Set <var>context</var> to <span>this</span>.</dd>

<dt>Otherwise</dt>
<dd><p>Throw a <span>"<code>SyntaxError</code>"</span> <code>DOMException</code>.</p></dd>
</dl>
</li>

<li>
<p>If <var>context</var> is not an <code>Element</code> or all of the following are true:</p>
lukewarlow marked this conversation as resolved.
Show resolved Hide resolved

<ul>
<li><p><var>context</var>'s <span>node document</span> is an HTML document;</p></li>
<li><p><var>context</var>'s <span data-x="concept-element-local-name">local name</span> is
"<code>html</code>"; and</p></li>
<li><p><var>context</var>'s <span data-x="concept-element-namespace">namespace</span> is the
<span>HTML namespace</span>,</p></li>
</ul>

<p>set <var>context</var> to the result of <span data-x="create an element">creating an
element</span> given <span>this</span>'s <span>node document</span>, <code>body</code>, and
the <span>HTML namespace</span>.</p>
</li>

<li>
<p>Let <var>fragment</var> be the result of invoking the <span>fragment parsing algorithm
steps</span> with <var>context</var> and <var>string</var>.</p>
</li>

<li>Use the first matching item from this list:
<dl class=switch>
<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforebegin</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
<span>this</span>'s <span data-x="dom-parent">parent</span> before <span>this</span>.</p>
</dd>

<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterend</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
lukewarlow marked this conversation as resolved.
Show resolved Hide resolved
<span>this</span> before its <span>first child</span>.</p>
</dd>

<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">afterbegin</code>"</dt>
<dd>
<p><span data-x="concept-node-append">Append</span> <var>fragment</var> to
<span>this</span>.</p>
</dd>

<dt>If <var>position</var> is an <span>ASCII case-insensitive</span> match for the string "<code data-x="">beforeend</code>"</dt>
<dd>
<p><span data-x="concept-node-insert">Insert</span> <var>fragment</var> into
<span>this</span>'s <span data-x="dom-parent">parent</span> before <span>this</span>'s
<span>next sibling</span>.</p>
</dd>
</dl>
</li>
</ol>

<p class=note>As with other direct <code>Node</code>-manipulation APIs (and unlike <code
data-x="dom-Element-innerHTML">innerHTML</code>), <code
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</code> does not include any special
handling for <code>template</code> elements. In most cases you will want to use <code
data-x="">templateEl.<span data-x="dom-template-content">content</span>.<span
data-x="dom-Element-insertAdjacentHTML">insertAdjacentHTML()</span></code> instead of directly
manipulating the child nodes of a <code>template</code> element.</p>

</div>

<h3 split-filename="timers-and-user-prompts" id="timers">Timers</h3>

<p>The <code data-x="dom-setTimeout">setTimeout()</code> and <code
Expand Down