diff options
Diffstat (limited to 'devdocs/html/element%2Ftemplate.html')
| -rw-r--r-- | devdocs/html/element%2Ftemplate.html | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/devdocs/html/element%2Ftemplate.html b/devdocs/html/element%2Ftemplate.html new file mode 100644 index 00000000..d851df81 --- /dev/null +++ b/devdocs/html/element%2Ftemplate.html @@ -0,0 +1,179 @@ +<header><h1><template>: The Content Template element</h1></header><div class="section-content"> +<p>The <code><template></code> <a href="../index">HTML</a> element is a mechanism for holding <a href="https://developer.mozilla.org/en-US/docs/Glossary/HTML">HTML</a> that is not to be rendered immediately when a page is loaded but may be instantiated subsequently during runtime using JavaScript.</p> <p>Think of a template as a content fragment that is being stored for subsequent use in the document. While the parser does process the contents of the <code><template></code> element while loading the page, it does so only to ensure that those contents are valid; the element's contents are not rendered, however.</p> +</div> +<h2 id="attributes">Attributes</h2> +<div class="section-content"> +<p>The only standard attributes that the <code><template></code> element supports are the <a href="../global_attributes">global attributes</a>.</p> <p>In Chromium-based browsers, the <code><template></code> element also supports a non-standard <a href="https://github.com/mfreed7/declarative-shadow-dom/blob/master/README.md#syntax" target="_blank"><code>shadowrootmode</code> attribute</a>, as part of an experimental <a href="https://developer.chrome.com/articles/declarative-shadow-dom/" target="_blank">"Declarative Shadow DOM"</a> proposal. In supporting browsers, a <code><template></code> element with the <code>shadowrootmode</code> attribute is detected by the HTML parser and immediately applied as the shadow root of its parent element. <code>shadowrootmode</code> can take a value of <code>open</code> or <code>closed</code>; these are equivalent to the <code>open</code> and <code>closed</code> values of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow"><code>Element.attachShadow()</code></a> <code>mode</code> option.</p> <p>Also, the corresponding <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement"><code>HTMLTemplateElement</code></a> interface includes a standard <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement/content"><code>content</code></a> property (without an equivalent content/markup attribute). This <code>content</code> property is read-only and holds a <a href="https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment"><code>DocumentFragment</code></a> that contains the DOM subtree represented by the template. Be careful when using the <code>content</code> property because the returned <code>DocumentFragment</code> can exhibit unexpected behavior. For more details, see the <a href="#avoiding_documentfragment_pitfalls">Avoiding DocumentFragment pitfalls</a> section below.</p> +</div> +<h2 id="examples">Examples</h2> +<div class="section-content"> +<p>First we start with the HTML portion of the example.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="I8s7uGl9d3MCpGhD4iu/aLbSxzvqaTgHK7jKRNxZOIE=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>table</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>producttable<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>thead</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>tr</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>td</span><span class="token punctuation">></span></span>UPC_Code<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>td</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>td</span><span class="token punctuation">></span></span>Product_Name<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>td</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>tr</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>thead</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>tbody</span><span class="token punctuation">></span></span> + <span class="token comment"><!-- existing data could optionally be included here --></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>tbody</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>table</span><span class="token punctuation">></span></span> + +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>template</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>productrow<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>tr</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>td</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>record<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>td</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>td</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>td</span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"></</span>tr</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>template</span><span class="token punctuation">></span></span> +</pre> +</div> <p>First, we have a table into which we will later insert content using JavaScript code. Then comes the template, which describes the structure of an HTML fragment representing a single table row.</p> <p>Now that the table has been created and the template defined, we use JavaScript to insert rows into the table, with each row being constructed using the template as its basis.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="fcTyqG2hfSPp31p+5ZaE2RIpOwoBDb569EosXX5oQh0=" data-language="js"><span class="token comment">// Test to see if the browser supports the HTML template element by checking</span> +<span class="token comment">// for the presence of the template element's content attribute.</span> +<span class="token keyword">if</span> <span class="token punctuation">(</span><span class="token string">"content"</span> <span class="token keyword">in</span> document<span class="token punctuation">.</span><span class="token function">createElement</span><span class="token punctuation">(</span><span class="token string">"template"</span><span class="token punctuation">)</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + <span class="token comment">// Instantiate the table with the existing HTML tbody</span> + <span class="token comment">// and the row with the template</span> + <span class="token keyword">const</span> tbody <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"tbody"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token keyword">const</span> template <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">querySelector</span><span class="token punctuation">(</span><span class="token string">"#productrow"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + + <span class="token comment">// Clone the new row and insert it into the table</span> + <span class="token keyword">const</span> clone <span class="token operator">=</span> template<span class="token punctuation">.</span>content<span class="token punctuation">.</span><span class="token function">cloneNode</span><span class="token punctuation">(</span><span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + <span class="token keyword">let</span> td <span class="token operator">=</span> clone<span class="token punctuation">.</span><span class="token function">querySelectorAll</span><span class="token punctuation">(</span><span class="token string">"td"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + td<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token string">"1235646565"</span><span class="token punctuation">;</span> + td<span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">]</span><span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token string">"Stuff"</span><span class="token punctuation">;</span> + + tbody<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>clone<span class="token punctuation">)</span><span class="token punctuation">;</span> + + <span class="token comment">// Clone the new row and insert it into the table</span> + <span class="token keyword">const</span> clone2 <span class="token operator">=</span> template<span class="token punctuation">.</span>content<span class="token punctuation">.</span><span class="token function">cloneNode</span><span class="token punctuation">(</span><span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + td <span class="token operator">=</span> clone2<span class="token punctuation">.</span><span class="token function">querySelectorAll</span><span class="token punctuation">(</span><span class="token string">"td"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + td<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token string">"0384928528"</span><span class="token punctuation">;</span> + td<span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">]</span><span class="token punctuation">.</span>textContent <span class="token operator">=</span> <span class="token string">"Acme Kidney Beans 2"</span><span class="token punctuation">;</span> + + tbody<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>clone2<span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span> + <span class="token comment">// Find another way to add the rows to the table because</span> + <span class="token comment">// the HTML template element is not supported.</span> +<span class="token punctuation">}</span> +</pre> +</div> <p>The result is the original HTML table, with two new rows appended to it via JavaScript:</p> +<div class="code-example" id="sect1"> + +<iframe class="sample-code-frame" title="Examples sample" id="frame_examples" width="500" height="120" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/template/runner.html?id=examples" loading="lazy"></iframe> +</div> +</div> +<h2 id="avoiding_documentfragment_pitfalls">Avoiding DocumentFragment pitfalls</h2> +<div class="section-content"> +<p>When a <a href="https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment"><code>DocumentFragment</code></a> value is passed, <a href="https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild"><code>Node.appendChild</code></a> and similar methods move only the <em>child nodes</em> of that value into the target node. Therefore, it is usually preferable to attach event handlers to the children of a <code>DocumentFragment</code>, rather than to the <code>DocumentFragment</code> itself.</p> <p>Consider the following HTML and JavaScript:</p> +</div> +<h3 id="html">HTML</h3> +<div class="section-content"><div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="uJr6GnUPUCUNWoTzSM8RJE9yZVY76XSniXQyhjBxK5g=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>container<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> + +<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>template</span> <span class="token attr-name">id</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>template<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>div</span><span class="token punctuation">></span></span>Click me<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>div</span><span class="token punctuation">></span></span> +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>template</span><span class="token punctuation">></span></span> +</pre> +</div></div> +<h3 id="javascript">JavaScript</h3> +<div class="section-content"><div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="C1NNEZsMKRq3qmZWfEeX0g/WzogXFxvvdfrh4TR57Ng=" data-language="js"><span class="token keyword">const</span> container <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">getElementById</span><span class="token punctuation">(</span><span class="token string">"container"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token keyword">const</span> template <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">getElementById</span><span class="token punctuation">(</span><span class="token string">"template"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token keyword">function</span> <span class="token function">clickHandler</span><span class="token punctuation">(</span><span class="token parameter">event</span><span class="token punctuation">)</span> <span class="token punctuation">{</span> + event<span class="token punctuation">.</span>target<span class="token punctuation">.</span><span class="token function">append</span><span class="token punctuation">(</span><span class="token string">" — Clicked this div"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +<span class="token punctuation">}</span> + +<span class="token keyword">const</span> firstClone <span class="token operator">=</span> template<span class="token punctuation">.</span>content<span class="token punctuation">.</span><span class="token function">cloneNode</span><span class="token punctuation">(</span><span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +firstClone<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> clickHandler<span class="token punctuation">)</span><span class="token punctuation">;</span> +container<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>firstClone<span class="token punctuation">)</span><span class="token punctuation">;</span> + +<span class="token keyword">const</span> secondClone <span class="token operator">=</span> template<span class="token punctuation">.</span>content<span class="token punctuation">.</span><span class="token function">cloneNode</span><span class="token punctuation">(</span><span class="token boolean">true</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +secondClone<span class="token punctuation">.</span>children<span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"click"</span><span class="token punctuation">,</span> clickHandler<span class="token punctuation">)</span><span class="token punctuation">;</span> +container<span class="token punctuation">.</span><span class="token function">appendChild</span><span class="token punctuation">(</span>secondClone<span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div></div> +<h3 id="result">Result</h3> +<div class="section-content"> +<p>Since <code>firstClone</code> is a <code>DocumentFragment</code>, only its children are added to <code>container</code> when <code>appendChild</code> is called; the event handlers of <code>firstClone</code> are not copied. In contrast, because an event handler is added to the first <em>child node</em> of <code>secondClone</code>, the event handler is copied when <code>appendChild</code> is called, and clicking on it works as one would expect.</p> +<div class="code-example" id="sect2"> + +<iframe class="sample-code-frame" title="Avoiding DocumentFragment pitfalls" id="frame_avoiding_documentfragment_pitfall" src="https://live.mdnplay.dev/en-US/docs/Web/HTML/Element/template/runner.html?id=avoiding_documentfragment_pitfall" loading="lazy"></iframe> +</div> +</div> +<h2 id="technical_summary">Technical summary</h2> +<div class="section-content"><figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td> <a href="../content_categories#metadata_content">Metadata content</a>, <a href="../content_categories#flow_content">flow content</a>, <a href="../content_categories#phrasing_content">phrasing content</a>, <a href="../content_categories#script-supporting_elements">script-supporting element</a> </td> </tr> <tr> <th scope="row">Permitted content</th> <td>No restrictions</td> </tr> <tr> <th scope="row">Tag omission</th> <td>None, both the starting and ending tag are mandatory.</td> </tr> <tr> <th scope="row">Permitted parents</th> <td> Any element that accepts <a href="../content_categories#metadata_content">metadata content</a>, <a href="../content_categories#phrasing_content">phrasing content</a>, or <a href="../content_categories#script-supporting_elements">script-supporting elements</a>. Also allowed as a child of a <a href="colgroup"><code><colgroup></code></a> element that does <em>not</em> have a <a href="colgroup#span"><code>span</code></a> attribute. </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" target="_blank">No corresponding role</a></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td>No <code>role</code> permitted</td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTemplateElement"><code>HTMLTemplateElement</code></a></td> </tr> </tbody> </table></div></figure></div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/scripting.html#the-template-element">HTML Standard <br><small># the-template-element</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody> +<tr> +<th><code>template</code></th> +<td class="bc-supports-yes">26</td> +<td class="bc-supports-yes">13</td> +<td class="bc-supports-yes">22</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">15</td> +<td class="bc-supports-yes">8</td> +<td class="bc-supports-yes">Yes</td> +<td class="bc-supports-yes">26</td> +<td class="bc-supports-yes">22</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">8</td> +<td class="bc-supports-yes">1.5</td> +</tr> +<tr> +<th><code>shadowrootmode</code></th> +<td class="bc-supports-yes">11190–111</td> +<td class="bc-supports-yes">11190–111</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">9776–97</td> +<td class="bc-supports-yes">16.4</td> +<td class="bc-supports-yes">11190–111</td> +<td class="bc-supports-yes">11190–111</td> +<td class="bc-supports-no">No</td> +<td class="bc-supports-yes">64</td> +<td class="bc-supports-yes">16.4</td> +<td class="bc-supports-yes">22.015.0–22.0</td> +</tr> +</tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li>Web components: <a href="slot"><code><slot></code></a> (and historical: <code><shadow></code>)</li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots">Using templates and slots</a></li> <li> +<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_scoping">CSS scoping</a> module</li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/template</a> + </p> +</div> |