Skip to content

Commit

Permalink
Rename the types of custom elements
Browse files Browse the repository at this point in the history 
"custom tag" becomes "autonomous custom element", and "type extension"
becomes "customized built-in element".

Fixes WICG/webcomponents#434.
  • Loading branch information
@domenic
domenic committed Apr 13, 2016
1 parent 6e7eaa4 commit 7858636
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 61 deletions.
4 changes: 2 additions & 2 deletions images/content-venn.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
126 changes: 67 additions & 59 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9927,7 +9927,7 @@ interface <dfn>HTMLUnknownElement</dfn> : <span>HTMLElement</span> { };</pre>
<li><code>var</code></li>
<li><code>video</code></li>
<li><code>wbr</code></li>
<li><span data-x="custom tag">custom tags</span></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">Text</span></li>
</ul>

Expand Down Expand Up @@ -10035,7 +10035,7 @@ interface <dfn>HTMLUnknownElement</dfn> : <span>HTMLElement</span> { };</pre>
<li><code>var</code></li>
<li><code>video</code></li>
<li><code>wbr</code></li>
<li><span data-x="custom tag">custom tags</span></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">Text</span></li>
</ul>

Expand Down Expand Up @@ -10232,7 +10232,7 @@ http://software.hixie.ch/utilities/js/live-dom-viewer/?%3C%21DOCTYPE%20HTML%3E%0
<li><code>ul</code> (if the element's children include at least one <code>li</code> element)</li>
<li><code>var</code></li>
<li><code>video</code></li>
<li><span data-x="custom tag">custom tags</span></li>
<li><span data-x="autonomous custom element">autonomous custom elements</span></li>
<li><span data-x="text content">Text</span> that is not <span>inter-element whitespace</span></li>
</ul>

Expand Down Expand Up @@ -66610,13 +66610,13 @@ dictionary <dfn>ImageBitmapRenderingContextSettings</dfn> {
fully explaining the behaviours of HTML's existing elements, we hope to shrink this gap over
time.</p>

<h5 id="custom-elements-custom-tag-example">Creating a custom tag</h5>
<h5 id="custom-elements-autonomous-example">Creating an autonomous custom element</h5>

<!-- NON-NORMATIVE SECTION -->

<p>For the purposes of illustrating how to create a <span>custom tag</span>, let's define a
custom element that encapsulates rendering a small icon for a country flag. Our goal is to be
able to use it like so:</p>
<p>For the purposes of illustrating how to create an <span>autonomous custom element</span>, let's
define a custom element that encapsulates rendering a small icon for a country flag. Our goal is
to be able to use it like so:</p>

<pre>&lt;flag-icon country="nl">&lt;/flag-icon></pre>

Expand Down Expand Up @@ -66678,27 +66678,29 @@ document.body.appendChild(flagIcon)</pre>
flagIcon.country = "jp"
document.body.appendChild(flagIcon)</pre>

<h5 id="custom-elements-type-extension-example">Creating a type extension</h5>
<h5 id="custom-elements-customized-builtin-example">Creating a customized built-in element</h5>

<!-- NON-NORMATIVE SECTION -->

<p><span data-x="type extension">Type extensions</span> are a distinct kind of <span>custom
element</span>, which are defined slightly differently and used very differently compared to
<span data-x="custom tag">custom tags</span>. They exist to allow reuse of behaviours from the
existing elements of HTML, by extending those elements with new custom functionality. This is
important since many of the existing behaviours of HTML elements can unfortunately not be
duplicated by using purely <span data-x="custom tag">custom tags</span>. Instead, <span
data-x="type extension">type extensions</span> allow the installation of custom construction
behaviour, lifecycle hooks, and prototype chain onto onto existing elements, essentially "mixing
in" these capabilities on top of the already-existing element.</p>

<p><span data-x="type extension">Type extensions</span> require a distinct syntax from <span
data-x="custom tag">custom tags</span> because user agents and other software key off an element's
local name in order to identify the element's semantics and behaviour. That is, the concept of
<span data-x="type extension">type extensions</span> building on top of existing behaviour depends
<p><span data-x="customized built-in element">Customized built-in elements</span> are a distinct
kind of <span>custom element</span>, which are defined slightly differently and used very
differently compared to <span data-x="autonomous custom element">autonomous custom
elements</span>. They exist to allow reuse of behaviours from the existing elements of HTML, by
extending those elements with new custom functionality. This is important since many of the
existing behaviours of HTML elements can unfortunately not be duplicated by using purely <span
data-x="autonomous custom element">autonomous custom elements</span>. Instead, <span
data-x="customized built-in element">customized built-in elements</span> allow the installation of
custom construction behaviour, lifecycle hooks, and prototype chain onto onto existing elements,
essentially "mixing in" these capabilities on top of the already-existing element.</p>

<p><span data-x="customized built-in element">Customized built-in elements</span> require a
distinct syntax from <span data-x="autonomous custom element">autonomous custom elements</span>
because user agents and other software key off an element's local name in order to identify the
element's semantics and behaviour. That is, the concept of <span data-x="customized built-in
element">customized built-in elements</span> building on top of existing behaviour depends
crucially on the extended elements retaining their original local name.</p>

<p>In this example, we'll be creating a type extension named <code
<p>In this example, we'll be creating a <span>customized built-in element</span> named <code
data-x="">plastic-button</code>, which behaves like a normal button but gets fancy animation
effects added whenever you click on it. We start by defining a class, just like before, although
this time we extend <code>HTMLButtonElement</code> instead of <code>HTMLElement</code>:</p>
Expand All @@ -66722,14 +66724,15 @@ document.body.appendChild(flagIcon)</pre>
what element interface it extends, as many elements share the same interface (such as
<code>q</code> and <code>blockquote</code> both sharing <code>HTMLQuoteElement</code>).</p>

<p>To use our type extension, we use the <code data-x="attr-is">is</code> attribute on a
<code>button</code> element:</p>
<p>To use our <span>customized built-in element</span>, we use the <code
data-x="attr-is">is</code> attribute on a <code>button</code> element:</p>

<pre>&lt;button is="plastic-button">Click Me!&lt;/button></pre>

<p>Trying to use a <span>type extension</span> as a <span>custom tag</span> will <em>not</em>
work; that is, <code data-x="">&lt;plastic-button>Click me?&lt;/plastic-button></code> will simply
create an <code>HTMLUnknownElement</code> with no special behaviour.</p>
<p>Trying to use a <span>customized built-in element</span> as an <span>autonomous custom
element</span> will <em>not</em> work; that is, <code data-x="">&lt;plastic-button>Click
me?&lt;/plastic-button></code> will simply create an <code>HTMLElement</code> with no special
behaviour.</p>

<p>If you need to create a type-extended element programmatically, you can use the following form
of <code data-x="dom-Document-createElement">createElement()</code>:</p>
Expand All @@ -66748,7 +66751,7 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<
data-x="concept-form-submit">form submission</span>, the <code
data-x="attr-fe-disabled">disabled</code> attribute, and so on.</p>

<h5 id="custom-elements-custom-tags-drawbacks">Drawbacks of custom tags</h5>
<h5 id="custom-elements-autonomous-drawbacks">Drawbacks of autonomous custom elements</h5>

<!-- NON-NORMATIVE SECTION -->

Expand All @@ -66758,8 +66761,8 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<
or accessibility technology will not automatically treat the resulting element as a button just
based on its defined name.</p>

<p>To convey the desired button semantics to a variety of users, while still using a <span>custom
tag</span>, a number of techniques would need to be employed:</p>
<p>To convey the desired button semantics to a variety of users, while still using an
<span>autonomous custom element</span>, a number of techniques would need to be employed:</p>

<ul>
<li><p>The addition of the <code data-x="attr-tabindex">tabindex</code> attribute would make the
Expand Down Expand Up @@ -66869,11 +66872,12 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<
forcing the use of these attributes to do so (even though they are usually reserved for allowing
the consumer to override default behaviour).</p>

<p>In contrast, a simple <span>type extension</span>, as shown in the previous section, would
automatically inherit the semantics and behaviour of the <code>button</code> element, with no need
to implement these behaviours manually. In general, for any elements with nontrivial behaviour and
semantics that build on top of existing elements of HTML, <span data-x="type extension">type
extensions</span> will be easier to develop, maintain, and consume.</p>
<p>In contrast, a simple <span>customized built-in element</span>, as shown in the previous
section, would automatically inherit the semantics and behaviour of the <code>button</code>
element, with no need to implement these behaviours manually. In general, for any elements with
nontrivial behaviour and semantics that build on top of existing elements of HTML, <span
data-x="customized built-in element">customized built-in elements</span> will be easier to
develop, maintain, and consume.</p>

<h5 id="custom-elements-upgrades-examples">Upgrading elements after their creation</h5>

Expand Down Expand Up @@ -66991,11 +66995,11 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<

<ol>

<li><p>A <dfn>custom tag</dfn>, which is defined with no <code data-x="">extends</code> option.
These types of custom elements have a local name equal to their <span
data-x="concept-custom-element-definition-name">defined name</span>.</p></li>
<li><p>An <dfn data-export="">autonomous custom element</dfn>, which is defined with no <code
data-x="">extends</code> option. These types of custom elements have a local name equal to their
<span data-x="concept-custom-element-definition-name">defined name</span>.</p></li>

<li><p>A <dfn data-export="">type extension</dfn>, which is defined with an <code
<li><p>A <dfn data-export="">customized built-in element</dfn>, which is defined with an <code
data-x="">extends</code> option. These types of custom elements have local name equal to the
value passed in their <code data-x="">extends</code> option, and their <span
data-x="concept-custom-element-definition-name">defined name</span> is used as the value of the
Expand All @@ -67007,7 +67011,8 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<
changing the value of the <code data-x="attr-is">is</code> attribute does not
change the element's behaviour.</p>

<p><span data-x="custom tag">Custom tags</span> have the following element definition:</p>
<p><span data-x="autonomous custom element">Autonomous custom elements</span> have the following
element definition:</p>

<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
Expand All @@ -67025,18 +67030,21 @@ console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"<
<dd>Supplied by the element's author (inherits from <code>HTMLElement</code>)</dd>
</dl>

<p>A <span>custom tag</span> does not have any special meaning: it <span>represents</span> its
children. A <span>type extension</span> inherits the semantics of the element that it extends.</p>

<p>An <span>autonomous custom element</span> does not have any special meaning: it
<span>represents</span> its children. A <span>customized built-in element</span> inherits the
semantics of the element that it extends.</p>

<p>Any namespace-less attribute that is relevant to the element's functioning, as determined by
the element's author, may be specified on a <span>custom tag</span>, so long as the attribute name
is <span>XML-compatible</span> and contains no <span>uppercase ASCII letters</span>. The exception
is the <code data-x="attr-is">is</code> attribute, which must not be specified on a <span>custom
tag</span> (and which will have no effect if it is).</p>
the element's author, may be specified on an <span>autonomous custom element</span>, so long as
the attribute name is <span>XML-compatible</span> and contains no <span>uppercase ASCII
letters</span>. The exception is the <code data-x="attr-is">is</code> attribute, which must not
be specified on an <span>autonomous custom element</span> (and which will have no effect if it
is).</p>

<p><span data-x="type extension">Type extensions</span> follow the normal requirements for
attributes, based on the elements they extend. To add custom attribute-based behavior, use <code
data-x="attr-data-*">data-*</code> attributes.</p>
<p><span data-x="customized built-in element">Customized built-in elements</span> follow the
normal requirements for attributes, based on the elements they extend. To add custom
attribute-based behavior, use <code data-x="attr-data-*">data-*</code> attributes.</p>

<hr>

Expand Down Expand Up @@ -67212,15 +67220,15 @@ dictionary <dfn>ElementRegistrationOptions</dfn> {
<var>constructor</var>)</dt>

<dd>Defines a new <span>custom element</span>, mapping the given name to the given constructor as
a <span>custom tag</span>.</dd>
an <span>autonomous custom element</span>.</dd>


<dt><var>window</var> . <code data-x="dom-window-customElements">customElements</code> . <code
data-x="dom-CustomElementsRegistry-define">define</code>(<var>name</var>, <var>constructor</var>,
{ extends: <var>baseLocalName</var> })</dt>

<dd>Defines a new <span>custom element</span>, mapping the given name to the given constructor as
a <span>type extension</span> for the <span>element type</span> identified by the supplied
a <span>customized built-in element</span> for the <span>element type</span> identified by the supplied
<var>baseLocalName</var>. A <code>NotSupportedError</code> will be thrown upon trying to extend a
<span>custom element</span> or an unknown element.</dd>
</dl>
Expand Down Expand Up @@ -103121,7 +103129,7 @@ dictionary <dfn>StorageEventInit</dfn> : <span>EventInit</span> {
step).</p>

<p class="note">Even though the <code data-x="attr-is">is</code> attribute governs the <span
data-x="create an element">creation</span> of a <span>type extension</span>, it is not present
data-x="create an element">creation</span> of a <span>customized built-in element</span>, it is not present
during the execution of the relevant <span>custom element constructor</span>; it is appended in
this step, along with all other attributes.</p>
</li>
Expand Down Expand Up @@ -115534,7 +115542,7 @@ if (s = prompt('What is your name?')) {
</tr>

<tr>
<th><span data-x="custom tag">custom tags</span></th>
<th><span data-x="autonomous custom element">autonomous custom elements</span></th>
<td>Author-defined elements</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Phrasing content">phrasing</span>;
Expand Down Expand Up @@ -115674,7 +115682,7 @@ if (s = prompt('What is your name?')) {
<code>var</code>;
<code>video</code>;
<code>wbr</code>;
<span data-x="custom tag">custom tags</span>;
<span data-x="autonomous custom element">autonomous custom elements</span>;
<span data-x="text content">Text</span>
<td>
<code>area</code> (if it is a descendant of a <code>map</code> element);
Expand Down Expand Up @@ -115761,7 +115769,7 @@ if (s = prompt('What is your name?')) {
<code>var</code>;
<code>video</code>;
<code>wbr</code>;
<span data-x="custom tag">custom tags</span>;
<span data-x="autonomous custom element">autonomous custom elements</span>;
<span data-x="text content">Text</span>
<td>
<code>area</code> (if it is a descendant of a <code>map</code> element);
Expand Down Expand Up @@ -115968,7 +115976,7 @@ if (s = prompt('What is your name?')) {
<code>u</code>;
<code>var</code>;
<code>video</code>;
<span data-x="custom tag">custom tags</span>
<span data-x="autonomous custom element">autonomous custom elements</span>
<td>
<code>audio</code> (if the <code data-x="attr-media-controls">controls</code> attribute is present);
<code>dl</code> (if the element's children include at least one name-value group);
Expand Down Expand Up @@ -116383,8 +116391,8 @@ if (s = prompt('What is your name?')) {
<tr>
<th> <code data-x="">is</code>
<td> <span data-x="attr-is">HTML elements</span>
<td> Creates a <span>type extension</span>
<td> <span>Valid custom element name</span> of a defined <span>type extension</span>
<td> Creates a <span>customized built-in element</span>
<td> <span>Valid custom element name</span> of a defined <span>customized built-in element</span>
<tr>
<th> <code data-x="">ismap</code>
<td> <code data-x="attr-img-ismap">img</code>
Expand Down

0 comments on commit 7858636

Please sign in to comment.