HTML Imports are a way to include and reuse HTML documents in other HTML documents.
+
Status of This Document
+
+
+
+
+ This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
+
+
+
+
+
+
+
+
+ This document was published by the Web Platform Working Group as a Working Draft.
+
+ This document is intended to become a W3C Recommendation.
+
+
+ If you wish to make comments regarding this document, please send them to
+ public-webapps@w3.org
+ (subscribe,
+ archives).
+
+
+
+
+
+
+ All comments are welcome.
+
+
+
+
+
+
+
+
+ Publication as a Working Draft does not imply endorsement by the W3C
+ Membership. This is a draft document and may be updated, replaced or obsoleted by other
+ documents at any time. It is inappropriate to cite this document as other than work in
+ progress.
+
All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.
+
+
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.
+
+
Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementers, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.
+
+
+
+
2. Dependencies
+
+
This document relies on the following specifications:
To track requested imports, each document has an import link list. Each of its item consists of link, a link element and location, a URL.
+Also, the item is optionally marked as branch.
+The list is initially empty, and items are added to it as specified by the import request algorithm.
The import link list and the import dependent constrains the order of script execution in imports. It is intend to give a deterministic order of script execution which is defined by the order of link element in each import. The edges of each node is ordered in terms of import link list. The import predecessors selection is aware of the order.
+
+
The linking structure of import link lists forms a directed graph. Each node of the graph is a document and its edge is a link. Branches are intended to form a spanning tree of the graph. This tree gives the deterministic order of the script execution.
+
+
+
+ Fig. 1
+ An example of import link lists.
+
+
+
+
+In the figure,
+
+
+
The document A has an import link list which contains a link to B and another link to C.
+
The document D has a couple of import ancestors that are A and B.
+
As B is a import ancestor of D, one of D's list item that points B is not marked as a branch.
+
Even though the document D is linked from two documents B and C, its import parent is B because B has a link to D which is marked as a branch.
+
Look at E:
+
+
E doesn't have any import predecessors. The link to D from C is not marked as branch, and the link to G isn't located before one to E.
Here's how one could access the imported document, mentioned in the previous example:
+
+var link = document.querySelector('link[rel=import]');
+var heart = link.import;
+// Access DOM of the document in /imports/heart.html
+var pulse = heart.querySelector('div.pulse');
+
+Giving up an import before it loads, even if the import eventually does still load, means that the script might end up operating with incorrect information. For example, if an import registers a custom element and a script relies on the availability of this element, the script will find that this element is unavailable if the user agent gives up early. Implementers have to balance the likelihood of a script using incorrect information with the performance impact of doing nothing while waiting for a slow network request to finish.
+
The state of "has an import that is blocking scripts" can change each time an existing import is completely loaded or new import loading is started. HTML parser has changes to unblock it for each of such timings.
+
+
+
+
+
6. Extensions to Document Interface
+
+
Additions to document.open() method
+
+
Add following step as the first step of the definition:
+
+
+
+
+All of loaded imports and imports under loading are in the import link list, thus every import which is linked from imports in the list will also be loaded using the import fetching algorithm, with LOCATION be the import location of the import.
+
+
+
+The loading attempt must be considered successful if IMPORT is not null on the algorithm completion, and failed otherwise.
+
+
+The currentScript attribute, on getting,
+must return the value to which it was most recently initialized in the document or the import map of the document.
+When the Document is created, the currentScript must be initialized to null.
+If the Document is an imported document, its currentScript is always null.
+
+
+
+
+
+
+
A set of imports that are associated with a master document forms an import link tree, a tree structure. Following import link tree forming algorithm, being applied with null as PARENT, master document as TREE and all of its imports as POOL, defines the import link tree:
+
+
+
+
+The import link tree algorithm defines a order of imports using a depth first traversal. This import link tree is different from the one formed by import link list. The former is based on the document tree of each import. The later is built through import loading process and isn'taffected by document tree mutation.
+
+
+
+
+
+
When an event handler content attribute is set, if the element is owned by a Document that is in a browsing context or
+in an import map, ...
+
+
+
+
+
+
+
A. Acknowledgements
+
+
David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of behavior attachment and greatly influenced this specification.
+
+
Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of behavior attachment and how it can be applied practically on the Web.
+
+
Dominic Cooney and Roland Steiner worked tirelessly to scope the problem within the confines of the Web platform and provided a solid foundation for this document.
+
+
The editor would also like to thank Alex Komoroske, Angelina Fabbro, Anne van Kesteren, Boris Zbarsky, Brian Kardell, Daniel Buchner, Edward O'Connor, Eric Bidelman, Erik Arvidsson, Elliott Sprehn, Gabor Krizsanits, Hayato Ito, James Simonsen, Jonas Sicking, Ken Shirriff, Neel Goyal, Olli Pettay, Rafael Weinstein, Scott Miles, Steve Orvell, Tab Atkins, William Chan, and William Chen for their comments and contributions to this specification.
+
+
This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.
This specification describes the method for enabling the author to define and use new types of DOM elements in a document. It will eventually be upstreamed into [[!WHATWG-DOM]], [[!HTML]], and [[!WEBIDL]]. Sections which explicitly modify existing parts of these specifications are denoted with "DOM+", "HTML+", or "Web IDL+" in their titles.
This specification describes the method for enabling the author to define and use new types of DOM elements in a document.
+
Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.
-
Status of This Document
+
The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification [[!WEBIDL]].
+
-
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This section should be inserted into the section The elements of HTML, probably as a subsection following "Scripting" and before "Common idioms without dedicated elements".
-
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Custom elements provide a way for authors to build their own fully-featured DOM elements. Although authors could always use non-standard tag names in their documents, with application-specific behavior added after the fact by scripting or similar, such elements have historically been non-conforming and not very functional. By defining a custom element, authors can inform the parser how to properly construct an element and how elements of that class should react to changes.
Custom elements are part of a larger effort to "rationalize the platform," by explaining existing platform features (like the elements of HTML) in terms of lower-level author-exposed extensibility points (like custom element registration). Although today there are many limitations on the capabilities of custom elements—both functionally and semantically—that prevent them from fully explaining the behaviors of HTML's existing elements, we hope to shrink this gap over time.
For the purposes of illustrating how to create a custom tag, 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:
+
+
+<flag-icon country="nl"></flag-icon>
+
+
To do this, we first declare a class for the custom element, extending HTMLElement:
+
+
+class FlagIcon extends HTMLElement {
+ constructor() {
+ super()
+ this._countryCode = null
+ }
+
+ static get observedAttributes() { return ["country"]; }
+
+ attributeChangedCallback(name, newValue) {
+ // name will always be "country" due to observedAttributes
+ this._countryCode = newValue
+ this._updateRendering()
+ }
+ connectedCallback() {
+ this._updateRendering()
+ }
+
+ get country() {
+ return this._countryCode
+ }
+ set country(v) {
+ this.setAttribute("country", v)
+ }
+
+ _updateRendering() {
+ // Left as an exercise for the reader. But, you'll probably want to
+ // check this.ownerDocument.defaultView to see if we've been
+ // inserted into a document with a browsing context, and avoid
+ // doing any work if not.
+ }
+}
+
+
We then need to use this class to define the element:
+
+
+customElements.define("flag-icon", FlagIcon);
+
+
At this point, our above code will work! The parser, whenever it sees the flag-icon tag, will construct a new instance of our FlagIcon class, and tell our code about its new country attribute, which we then use to set the element's internal state and update its rendering (when appropriate).
+
+
You can also create flag-icon elements directly, using the DOM API:
Finally, we can also use the custom element constructor itself. That is, the above code is equivalent to:
+
+
+const flagIcon = new FlagIcon()
+flagIcon.country = "jp"
+document.body.appendChild(flagIcon)
-
+
+
Creating a type extension
+
+
Type extensions are a distinct kind of custom element, which are registered slightly differently and used very differently. They exist to allow reuse of behaviors from the existing elements of HTML, by extending those elements with new custom functionality. This is important since many of the existing behaviors of HTML elements can unfortunately not be duplicated by using purely custom tags. Instead, type extensions allow the installation of custom construction behavior, lifecycle hooks, and prototype chain onto onto existing elements, essentially "mixing in" these capabilities on top of the already-existing element.
+
+
Type extensions require a distinct syntax from custom tags because user agents and other software key off an element's local name in order to identify the element's basic nature. That is, the concept of type extensions building on top of existing behavior depends crucially on the extended elements retaining their original local name.
+
+
In this example, we'll be creating a type extension named plastic-button, 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 HTMLButtonElement instead of HTMLElement:
In general, the name of the element being extended cannot be determined simply by looking at what element interface it extends, as many elements share the same interface (such as q and blockquote both sharing HTMLQuoteElement).
+
+
To use our type extension, we use the is attribute on a button element:
-
About this Document
+
+<button is="plastic-button">Click Me!</button>
-
All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.
+
Trying to use a type extension as a custom tag will not work; that is, <plastic-button>Click me?</plastic-button> will simply create a HTMLUnknownElement with no special behavior.
-
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.
+
If you need to create a type extension programmatically, you can use the following form of createElement:
-
Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.
This document relies on the following specifications:
+
+const plasticButton2 = new PlasticButton()
+console.log(plasticButton2.localName); // will output "button"
+console.log(plasticButton2.getAttribute("is")); // will output "plastic-button"
+
+
Notably, all the of the ways in which button is special apply to such "plastic buttons" as well: their focus behavior, ability to participate in form submission, the disabled attribute, and so on.
A parameter-less call to super() must be the first statement in the constructor body, to establish the correct prototype chain and this value before any further code is run.
+
A return statement must not appear anywhere inside the constructor body, unless it is a simple early-return (return or return this).
+
The element's attributes and children must not be inspected, as in the non-upgrade case none will be present, and relying on upgrades makes the element less usable.
+
The element must not gain any attributes or children, as this violates the expectations of consumers who use the createElement or createElementNS methods.
+
In general, work should be deferred to connectedCallback as much as possible—especially work involving fetching resources or rendering. However, note that connectedCallback can be called more than once, so any initialization work that is truly one-time will need a guard to prevent it from running twice.
+
In general, the constructor should be used to set up initial state and default values, and to set up event listeners.
-
+
Core concepts
+
+
Formally, a custom element is an element whose constructor and prototype are defined by the author, instead of by the user agent. The developer-supplied constructor function is called the custom element constructor.
There are two motivations that fueled the development of this specification:
-
Provide a way for Web developers to build their own, fully-featured DOM elements. Though it was long possible to create DOM elements with any tag names in HTML, these elements weren't very functional. By giving Web developers the means to both inform the parser on how to properly construct an element and to react to lifecycle changes of an element, the specification eliminates the need for DOM-as-a-render-view scaffolding that has to exist today in most web frameworks or libraries.
-
Rationalize the platform. The specification ensures that all of its new features and abilities are in concert with how the relevant bits of the Web platform work today, so that these new features could be used to explain the functionality of existing Web platform features, such as HTML elements.
+
A custom tag, which is registered with no extends option. These types of custom elements have local name equal to their registered name.
+
A type extension, which is registered with an extends option. These types of custom elements have local name equal to the value passed in their extends option, and their registered name is used as the value of the isattribute.
-
Most of the effort went into finding the right balance between the two motivations, driven by the hope that these motivations do not run counter to each other, but are rather complementary parts of the same larger story. For example, though the scope of the spec is currently limited to only creating custom elements by authors, it is designed to shorten the distance to a much more ambitious goal of rationalizing all HTML, SVG, and MathML elements into one coherent system.
A valid custom element name is a sequence of characters name that meets all of the following requirements:
-
The custom element type identifies a custom elementinterface and is a sequence of characters that must match the NCName production, must contain a U+002D HYPHEN-MINUS character, and must not contain any uppercase ASCII letters. The custom element typemust not be one of the following values:
This uses the EBNF notation from the XML specification. [[!XML]]
+
+
+
name must not be any of the following:
+
+
annotation-xml
+
color-profile
+
font-face
+
font-face-src
+
font-face-uri
+
font-face-format
+
font-face-name
+
missing-glyph
+
+
The list of names above is the summary of all hyphen-containing element names from the applicable specifications, namely SVG and MathML. [[SVG11]] [[MathML]]
+
-
-The list of names above is the summary of all hyphen-containing element names from the applicable specifications, namely SVG and MathML.
+
They start with a lowercase ASCII letter, ensuring that the HTML parser will treat them as tags instead of as text.
+
They do not contain any uppercase ASCII letters, ensuring that the user agent can always treat HTML elements ASCII-case-insensitively.
+
They contain a hyphen, used for namespacing and to ensure forward compatibility (since no elements will be added to HTML, SVG, or MathML with hyphen-containing tag names in the future).
-Effectively, the registry is consulted whenever a new DOM element is created, whether imperatively or by a parser. Whenever a matching element definition is found in the registry, the information in this definition is used to create a new instance of a custom element.
-
+
Each Window object is associated with a unique instance of a CustomElementsRegistry object, allocated when the Window object is created.
Various callbacks can be invoked when a custom element goes through some of these changes. These callbacks are stored internally as a collection of key-value pairs and called lifecycle callbacks.
Defines a new custom element, mapping the given name to the given constructor as a type extension for the supplied base tag.
+
-
Enqueuing and Invoking Callbacks
+
Every CustomElementsRegistry has a set of custom element definitions, initially empty. In general, algorithms in this specification look up elements in the registry by any of name, local name, or constructor.
A CustomElementsRegistry's list of defined local names is the list containing all of the local names of the custom element definitions in the registry.
-
Each custom element has an associated callback queue and an element is being created flag. The flag is initially set to false and the callback queue is initially empty. Each item in the queue consists of the callback itself and zero or more string values that are used as callback arguments.
To invoke callbacks in an element queue, the user agent must run these steps or their equivalent:
+
Element definition is a process of adding a custom element definition to the CustomElementsRegistry. This is accomplished by the define method. When invoked, the define(name, constructor, options) method must run these steps:
As described, these actions wrap every user agent-implemented method or property accessor. The intended effect is that any lifecycle callbacks, enqueued as a result of running these methods or accessors are invoked prior to returning control back to script. If a method or accessor is known to never enqueue a lifecycle callback, the user agent could choose not to wrap it as a performance optimization.
If observedAttributesIterable is undefined, let observedAttributes be an empty sequence<DOMString>. Otherwise, let observedAttributes be the result of convertingobservedAttributesIterable to a sequence<DOMString>. Rethrow any exceptions.
-
The document custom element order is a numerical value, associated with every custom element. This value is as a result of custom element's document keeping a numerical value that is incremented and assigned to custom element as its custom element order whenever the following occurs:
Let connectedCallback be Get(prototype, "connectedCallback"). Rethrow any exceptions.
-
-
Because imports load asynchronously, we need to divide a sorted element queue into the part where things have settled down (all imports have loaded), and the part where the loading is still happening, and thus the actual sorting order is not yet determined. For example, suppose you have the following document structure:
+
If connectedCallback is not undefined, and IsCallable(connectedCallback) is false, throw a TypeError exception.
Let disconnectedCallback be Get(prototype, "disconnectedCallback"). Rethrow any exceptions.
-import.html:
-<me-first></me-first>
+
If disconnectedCallback is not undefined, and IsCallable(disconnectedCallback) is false, throw a TypeError exception.
-
+
Let attributeChangedCallback be Get(prototype, "attributeChangedCallback"). Rethrow any exceptions.
-
The order of custom elements in the flattened import link tree is me-first (1), me-second (2). However, it's very likely that the parser will find out about me-second sooner than me-first, since the latter requires loading the import.html. While the network stack is doing its job, the highest stable order stays at the beginning position. When import.html is ready, the order jumps all the way to me-second (2).
+
If attributeChangedCallback is not undefined, and IsCallable(attributeChangedCallback) is false, throw a TypeError exception.
Set the value of the entry in map whose key is name to an empty sorted element queue.
+
+
+
Because element definition can occur at any time, a non-custom element could be created that might in the future become a custom element after an appropriate definition is registered. Such elements are called undefined potentially-custom elements. If such a definition is ever registered, the element will be upgraded, becoming a custom element.
If constructResult is an abrupt completion, return constructResult (i.e., re-throw the exception).
+
+
+
If SameValue(constructResult.[[\value]], element) is false, throw a InvalidStateError and terminate these steps.
+
+
This can occur if C constructs another instance of the same custom element before calling super(), or if C uses JavaScript's return-override feature to return an arbitrary object from the constructor.
As is conventional for HTML, the actual definition of this property is elsewhere in the specification (cf. location and history). We have it above in the section "The CustomElementsRegistry interface".
+
+
+
+
HTML+: Element interfaces
+
+
HTML currently does not do a great job of defining DOM's element interface concept. There is a definition hidden inside the parser, but it isn't explicit that this also covers other element creation cases. We should create a section that is more explicit, and it should roughly contain the following (including the note afterward):
This callback is invoked after custom element instance is created and its definition is registered. The actual timing of this callback is defined further in this specification.
For the duration of this callback invocation, the element is being created flag must be set to true. In all other cases, the flag must be set to false.
-
If the created callback exists for an element, all other callbacks must not be enqueued until after this created callback's invocation had started.
Unless specified otherwise, this callback must be enqueued whenever custom element's attribute is added, changed or removed. Depending on the type of attribute modification, the following additional strings are added to the queue item:
-
To set custom element prototype on a custom element, a conforming user agent must run the following steps or their equivalent:
+
+
DOM+: Elements
+
+
The Element interface section will need to be modified as follows. The paragraph listing the values associated with an element should be modified to read as follows, including the note afterward:
+
+
Elements have an associated namespace, namespace prefix, local name, and defined flag. When an element is created, all of these values are set. An element whose defined flag is set is said to be defined.
+
+
+ As detailed elsewhere in this specification, all elements that are not custom elements are already defined upon their creation. Custom elements become defined once their constructor has been called, either synchronously or during the upgrade process.
+
+
+
Additionally, after the talk about qualified names but before the discussion of attributes, the following algorithm should be inserted:
+
+
To create an element, given a document, localName, prefix, namespace, typeExtension, an optional synchronous custom elements flag, and an optional auto-upgrade custom elements flag, run the following steps:
Otherwise, if registry is not null, namespace is the HTML namespace, and registry contains an entry with local namelocalName, let definition be that entry, and perform the following substeps:
Let result be Construct(C). Rethrow any exceptions.
+
+
+
If result does not implement the HTMLElement interface, throw a TypeError exception and abort these steps.
+
+
This is meant to be a brand check to ensure that the object was allocated by the HTMLElement constructor. Eventually Web IDL may give us a more precise way to do brand checks.
The clone a node algorithm will need to be modified as follows. A new case, separate from the main switch, will be needed to generate copy for Elements. It should use create an element, given document, node's local name, node's namespace prefix, node's namespace, and the value of node's is attribute (if present). The synchronous custom elements flag and auto-upgrade custom elements flag should both be unset.
Various callbacks can be invoked when a custom element goes through some of these changes. These callbacks are stored internally as a collection of lifecycle callbacks. They can be looked up by name, which is one of connectedCallback, disconnectedCallback, or attributeChangedCallback.
A callback action, which will call a lifecycle callback, and contains a callback function as well as a list of arguments.
-
-The effect of this statement is that any HTML (or SVG) element with the local name that is a valid custom element type will have HTMLElement (or SVGElement) as element interface, rather than HTMLUnknownElement.
-
+
To enqueue a custom element callback action, given a custom elementelement, a callback name callbackName, and a list of arguments args, run the following steps:
As described, these actions wrap every user agent-implemented method or property accessor. The intended effect is that any lifecycle callbacks, enqueued as a result of running these methods or accessors are invoked prior to returning control back to script. If a method or accessor is known to never enqueue a custom element action, the user agent could choose not to wrap it as a performance optimization.
+
+
Custom elements have an associated element is being created flag, initially false.
The custom element order is a numerical value, associated with every custom element. This value is assigned as a result of custom element's document keeping a numerical value that is incremented and assigned to custom element as its custom element order whenever the following occurs:
ElementRegistrationOptions is an abstraction that enables using function objects and ES6 classes as the second argument of document.registerElement method.
-
+
Modify the remove algorithm as follows. Replace step 9 with:
-
-
In order to register a custom element with a prototype, other than HTMLElement or SVGElement, the caller of document.registerElement has to first build a proper prototype object that inherits from HTMLElement. Here's a simple example of how one could do this:
Note the use of extends option to specify that the element is being registered as a type extension -- that is, this element does not introduce a new tag (like the custom tag elements do), but rather extends an existing element of type HTMLParagraphElement. Here's how one could instantiate this element:
Elements with SVGElement prototype deserve a special mention: using custom tag approach results in ignored elements in SVG. Thus, your SVG-based custom elements would almost always be type extensions.
All custom elementsmust be constructable with a function object, called custom element constructor. This constructor must be created with the custom element constructor generation algorithm, which must be equivalent to running these steps:
Once the ECMAScript Standard Edition 6 is released, this section will be integrated into the respective areas of this specification. Until then, here is an overview of how ECMAScript 6 and Custom Elements integrate.
If the user agent implements the @@create method, this specification would stop treating the ElementRegistrationOptions options argument in registerElement as a dictionary, and instead view it as a the custom element constructor.
+
This occurs when author script constructs a new custom element directly, e.g. via new MyCustomElement().
+
-
Instead of generating a constructor, the user agent will now mutate this argument to have a new @@create method that creates a new element object.
Since the registerElement's second argument is now a constructor function, the element definition should change to hold that constructor function, rather than the custom element prototype.
This step is normally reached when upgrading a custom element; the existing element is returned, so that the super() call inside the custom element constructor assigns that existing element to this.
Let typeExtension be the value of the is member of options, or null if no such member exists.
+
+
Return the result of creating an element given the context object, localName, null, the HTML namespace, typeExtension, with the synchronous custom elements flag set, and with the auto-upgrade custom elements flag set if the upgrade member of options is true. Rethrow any exceptions.
-
-
-
The steps run when calling registerElement will change to:
-
+The createElementNS(namespace, qualifiedName, options) method, when invoked, must run these steps:
-
Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract. Rethrow any exceptions.
+
+
Let typeExtension be the value of the is member of options, or null if no such member exists.
+
+
Return the result of creating an element given the context object, localName, prefix, namespace, typeExtension, with the synchronous custom elements flag set, and with the auto-upgrade custom elements flag set if the upgrade member of options is true. Rethrow any exceptions.
The create an element for a token algorithm should be adjusted by replacing step 1 with the following steps, and adjusting further steps to refer to element instead of "the element" or "the newly created element".
Let element be the result of creating an element given document, localName, null, given namespace, and typeExtension. If will execute script is true, set the synchronous custom elements flag and the auto-upgrade custom elements flag; otherwise, leave them unset.
The default semantics of a custom element is dependent upon the form in which it is instantiated:
+
+
+
+
HTML+: Parsing XHTML documents
+
+
It turns out there's not actually a spec for the XML parser. Awesome! (Not actually awesome.) The HTML Standard has a nice vague paragraph about "This Document must then be populated with DOM nodes that represent the tree structure of the input passed..." which should get something like the following inserted (probably by inserting it after the first sentence, then splitting the mutation events/observers prose into a new paragraph).
+
+
When creating DOM nodes representing elements, the create an element for a token algorithm or some equivalent that operates on appropriate XML datastructures must be used, to ensure the proper element interfaces are created and that custom elements are set up correctly.
+
+
+
+
+
+
+
Additions to CSS
+
+
The following should be added to some relevant CSS specification. Or maybe it would belong in HTML? It looks like it's mostly a collaboration so far?
The ':defined' pseudo-class applies to elements that are defined.
+
+
+The ':defined' pseudo-class can be used to mitigate the flash of unstyled content [[FOUC]] issues with custom elements.
+
+
+
+
+
+
Custom Element Semantics
+
The default semantics of a custom element is dependent upon the form in which it is instantiated:
-
by default a custom tag has no special meaning at all. It represents its children.
-
by default a type extension inherits the semantics of the element type it extends.
+
by default a custom tag has no special meaning at all. It represents its children.
+
by default a type extension inherits the semantics of the element type it extends.
-
Custom Tag Example
+
+
Custom Tag Example
For example, a custom tag could be named taco-button, but the name alone does not express the semantics of a HTML button element simply due to its name. As instantiated a custom tag conveys a similar amount of semantics as an HTML div or span element:
-
<!-- taco-button represents a span with a fancy name -->
-<taco-button></taco-button>
+
<!-- taco-button represents a span with a fancy name -->
+<taco-button></taco-button>
The addition of visual styling and scripted events to the taco-button could provide hints as to its semantics and expected interaction behaviours — for some users — but for the semantics to be formally expressed developers must convey the semantics using ARIA roles, states and properties.
The addition of a tabindex attribute to the custom element provides interaction (the element is included in the focus order) and property/state semantics (it exposes information that it is focusable and if it currently has focus).
-
+
<!-- taco-button represents a focusable span with a fancy name -->
-<taco-button tabindex="0">Eat Me</taco-button>
+<taco-button tabindex="0">Eat Me</taco-button>
-
The addition of a label, using aria-label, to the custom element provides an Accessible Name for the element.
-
+
The addition of a label, using aria-label, to the custom element provides an Accessible Name for the element.
+
<!-- taco-button represents a focusable span with a fancy name and a text label -->
-<taco-button tabindex="0" aria-label="Eat Me">Eat Me</taco-button>
The addition of keyboard event handlers to the custom element provides the means for keyboard users to operate the control, but does not convey the presence of the functionality.
-
-<!-- taco-button represents focusable span with a fancy name, a text label and button like event handling -->
+
+<!-- taco-button represents focusable span with a fancy name,
+ a text label and button like event handling -->
<taco-button tabindex="0" onclick="alert('tasty eh?');"
-onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
The addition of inline event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all. This example demonstrates one method for developers to ensure that a custom control is operable for keyboard users and meets the WCAG 2.0 criteria "All functionality of the content is operable through a keyboard interface".
+
The addition of inline event handlers are for demonstration purposes only. The event handlers could be added by the lifecycle callbacks imperatively, or maybe even not used at all. This example demonstrates one method for developers to ensure that a custom control is operable for keyboard users and meets the WCAG 2.0 [[WCAG20]] criteria "All functionality of the content is operable through a keyboard interface".
The addition of an ARIA role="button" conveys the custom element's role semantics, which enables users to successfully interact with the control using the expected button interaction behaviours (pressing the space or enter keys to activate).
-
-<!-- taco-button represents a focusable button with a text label and button like event handling -->
+
+<!-- taco-button represents a focusable button with a text label
+ and button like event handling -->
<taco-button role="button" tabindex="0" onclick="alert('tasty eh?');"
-onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
The developer may provide a disabled state for the custom element. This could be implemented by removing the tabindex attribute so the element is no longer included in the focus order and removing the functionality so that interacting with the element does nothing. Also the visual styling may also be modified to visually indicate it the element is disabled.
-
-<!-- grayed out non focusable taco-button with functionality removed, to indicate the button is in a disabled state -->
+
+<!-- grayed out non focusable taco-button with functionality removed,
+ to indicate the button is in a disabled state -->
<taco-button role="button" tabindex="0"onclick="alert('tasty eh?');"
-onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};">Eat Me</taco-button>
Removing the focusability and functionality of the custom element and modifying its style does not unambiguously express that it is in a disabled state. To unambiguously express the disabled state add aria-disabled="true".
A disabled attribute would not work here as the custom tag is not based on an HTML element that supports its use.
-
-<!-- taco-button represents a focusable button with a text label and button like event handling -->
+
+<!-- taco-button represents a focusable button with a text label
+ and button like event handling -->
<taco-button role="button" tabindex="0"onclick="alert('tasty eh?');"
-onkeypress="if(event.keyCode==32||event.keyCode==13){alert('tasty eh?');};" aria-disabled="true">Eat Me</taco-button>
A type extension, for example could extend the HTML button element. As instantiated it would inherit the button element's name, role, states and properties, built in focus and keyboard interaction behaviours.
-
<!-- tequila-button represents a button with an accessible name of "Drink Me!" -->
-<button is="tequila-button">Drink Me!</button>
+
<!-- tequila-button represents a button with an accessible name of "Drink Me!" -->
+<button is="tequila-button">Drink Me!</button>
To implement the desired tequila-button feature, all that is required is the addition of an event handler. The rest of the semantics and interaction behaviour are provided by the browser as part of its implementation of the button element.
<!-- tequila-button represents a button -->
+<button is="tequila-button" onclick="alert('smooth!');">Drink Me!</button>
To implement the disabled state on the tequila-button, all that is required is the addition of the HTML disabled attribute. The semantics, style and interaction behaviour are implemented by the browser.
The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours that developers can use as a foundation.
The simplest and most robust method to create custom elements that are usable and accessible is to implement custom elements as type extensions. This method provides a custom element with built in semantics and interaction behaviours that developers can use as a foundation.
To help navigate through various parts of the spec and their interactions, here is a diagram that attempts to put all algorithms actions that trigger them in one space. Click on each box to go to the corresponding algorithm or action.
-
-
-
- Fig. All algorithms in one diagram
-
-
-
-
+
+
-
Acknowledgements
+
Acknowledgments
David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of behavior attachment and greatly influenced this specification.
Alex Russell and his considerable forethought triggered a new wave of enthusiasm around the subject of behavior attachment and how it can be applied practically on the Web.
Dominic Cooney, Hajime Morrita, and Roland Steiner worked tirelessly to scope the problem within the confines of the Web platform and provided a solid foundation for this document.
The editor would also like to thank Alex Komoroske, Anne van Kesteren, Boris Zbarsky, Daniel Buchner, Edward O'Connor, Erik Arvidsson, Elliott Sprehn, Hayato Ito, Jonas Sicking, Olli Pettay, Rafael Weinstein, Scott Miles, Simon Pieters, Steve Orvell, Tab Atkins, and William Chen for their comments and contributions to this specification.
+
The editor would also like to thank
+Alex Komoroske,
+Andres Rios,
+Anne van Kesteren,
+Boris Zbarsky,
+Daniel Buchner,
+Edward O'Connor,
+Erik Arvidsson,
+Elliott Sprehn,
+Hayato Ito,
+Jan Miksovsky,
+Jonas Sicking,
+Olli Pettay,
+Rafael Weinstein,
+Ryosuke Niwa,
+Scott Miles,
+Simon Pieters,
+Steve Orvell,
+Tab Atkins,
+and
+William Chen
+
+for their comments and contributions to this specification.
This list is too short. There's a lot of work left to do. Please contribute by reviewing and filing bugs—and don't forget to ask the editor to add your name into this section.
HTML Imports are a way to include and reuse HTML documents in other HTML documents.
-
-
Status of This Document
-
-
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
HTML Imports are a way to include and reuse HTML documents in other HTML documents [[!HTML]].
-
-
About this Document
-
-
All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.
-
-
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.
-
-
Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementers, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.
-
-
Dependencies
+
+
-
This document relies on the following specifications:
Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementers, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.
To track requested imports, each document has an import link list. Each of its item consists of link, a link element and location, a URL.
+
To track requested imports, each document has an import link list. Each of its item consists of link, a link element and location, a URL.
Also, the item is optionally marked as branch.
-The list is initially empty, and items are added to it as specified by the import request algorithm.
+The list is initially empty, and items are added to it as specified by the import request algorithm.
-
Each imported document also has one or more import ancestors: Document A is an import ancestor of another document B if A is import parent of B. Being an import ancestor is transitive: If A is an import parent of B and B is an import parent of C, A is an import parent of C as well.
+
The import link list and the import dependent constrains the order of script execution in imports. It is intend to give a deterministic order of script execution which is defined by the order of link element in each import. The edges of each node is ordered in terms of import link list. The import predecessors selection is aware of the order.
+
The import link list and the import dependent constrains the order of script execution in imports. It is intend to give a deterministic order of script execution which is defined by the order of link element in each import. The edges of each node is ordered in terms of import link list. The import predecessors selection is aware of the order.
-
The linking structure of import link lists forms a directed graph. Each node of the graph is a document and its edge is a link. Branches are intended to form a spanning tree of the graph. This tree gives the deterministic order of the script execution.
+
The linking structure of import link lists forms a directed graph. Each node of the graph is a document and its edge is a link. Branches are intended to form a spanning tree of the graph. This tree gives the deterministic order of the script execution.
-
-
- An example of import link lists.
-
+
+ An example of import link lists
-In the figure,
+In ,
-
The document A has an import link list which contains a link to B and another link to C.
-
The document D has a couple of import ancestors that are A and B.
-
As B is a import ancestor of D, one of D's list item that points B is not marked as a branch.
-
Even though the document D is linked from two documents B and C, its import parent is B because B has a link to D which is marked as a branch.
+
The document A has an import link list which contains a link to B and another link to C.
+
The document D has a couple of import ancestors that are A and B.
+
As B is a import ancestor of D, one of D's list item that points B is not marked as a branch.
+
Even though the document D is linked from two documents B and C, its import parent is B because B has a link to D which is marked as a branch.
Look at E:
-
E doesn't have any import predecessors. The link to D from C is not marked as branch, and the link to G isn't located before one to E.
Giving up an import before it loads, even if the import eventually does still load, means that the script might end up operating with incorrect information. For example, if an import registers a custom element and a script relies on the availability of this element, the script will find that this element is unavailable if the user agent gives up early. Implementers have to balance the likelihood of a script using incorrect information with the performance impact of doing nothing while waiting for a slow network request to finish.
The state of "has an import that is blocking scripts" can change each time an existing import is completely loaded or new import loading is started. HTML parser has changes to unblock it for each of such timings.
-
+
The state of "has an import that is blocking scripts" can change each time an existing import is completely loaded or new import loading is started. HTML parser has changes to unblock it for each of such timings.
+
+
-
Extensions to Document Interface
+
+
Extensions to Document Interface
-
Additions to document.open() method
+
+
Additions to document.open() method
Add following step as the first step of the definition:
-All of loaded imports and imports under loading are in the import link list, thus every import which is linked from imports in the list will also be loaded using the import fetching algorithm, with LOCATION be the import location of the import.
-
+
+All of loaded imports and imports under loading are in the import link list, thus every import which is linked from imports in the list will also be loaded using the import fetching algorithm, with LOCATION be the import location of the import.
+
-The loading attempt must be considered successful if IMPORT is not null on the algorithm completion, and failed otherwise.
+The loading attempt MUST be considered successful if IMPORT is not null on the algorithm completion, and failed otherwise.
-The currentScript attribute, on getting,
-must return the value to which it was most recently initialized in the document or the import map of the document.
-When the Document is created, the currentScript must be initialized to null.
-If the Document is an imported document, its currentScript is always null.
-
+
+The currentScript attribute, on getting,
+MUST return the value to which it was most recently initialized in the document or the import map of the document.
+When the Document is created, the currentScript MUST be initialized to null.
+If the Document is an imported document, its currentScript is always null.
+
-
A set of imports that are associated with a master document forms an import link tree, a tree structure. Following import link tree forming algorithm, being applied with null as PARENT, master document as TREE and all of its imports as POOL, defines the import link tree:
+
+
Import Link Tree
-
+
A set of imports that are associated with a master document forms an import link tree, a tree structure. Following import link tree forming algorithm, being applied with null as PARENT, master document as TREE and all of its imports as POOL, defines the import link tree:
-The import link tree algorithm defines a order of imports using a depth first traversal. This import link tree is different from the one formed by import link list. The former is based on the document tree of each import. The later is built through import loading process and isn'taffected by document tree mutation.
-
+
+The import link tree algorithm defines a order of imports using a depth first traversal. This import link tree is different from the one formed by import link list. The former is based on the document tree of each import. The later is built through import loading process and isn't affected by document tree mutation.
+
When an event handler content attribute is set, if the element is owned by a Document that is in a browsing context or
-in an import map, ...
+
When an event handler content attribute is set, if the element is owned by a Document that is in a browsing context or
+in an import map, …
-
Acknowledgements
+
+
+
+
+
Custom Element Processing
+
+
This specification redefines custom element order to be the sum of [[!CUSTOM-ELEMENTS]]'s custom element order and import tree order, in which the import tree order is scaled so that its lowest value is always larger than the highest possible value of [[!CUSTOM-ELEMENTS]]'s custom element order.
Because imports load asynchronously, we need to divide a sorted element queue into the part where things have settled down (all imports have loaded), and the part where the loading is still happening, and thus the actual sorting order is not yet determined. For example, suppose you have the following document structure:
The order of custom elements in the flattened import link tree is me-first (1), me-second (2). However, it's very likely that the parser will find out about me-second sooner than me-first, since the latter requires loading the import.html. While the network stack is doing its job, the highest stable order stays at the beginning position. When import.html is ready, the order jumps all the way to me-second (2).
+
+
+
+
+
+
+
Acknowledgments
David Hyatt developed XBL 1.0, and Ian Hickson co-wrote XBL 2.0. These documents provided tremendous insight into the problem of behavior attachment and greatly influenced this specification.
+ 
-