HTML Imports

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 implementors, 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:

Terminology

HTML Imports, or just imports from here on, are HTML documents that are linked as external resources from another HTML document. The document that links to an import is called a master document.

The document that represents an import is called the imported document, and the URL of the imported document is called the import location.

Link Type "`import`"

To enable declaring imports in HTML, a new link type is added to HTML link types:

The import keyword may be used with link elements. This keyword creates an external resource link to a import.

The default type for resources given by the import keyword is text/html.

The appropriate time to obtain the resource is when the external resource link is created or when its element is inserted into a document, whichever happens last.

The following document has one import, located at /imports/heart.html:


<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Human Being</title>
        <link rel="import" href="/imports/heart.html">
    </head>
    <body>
        <p>What is a body without a heart?</p>
    </body>
</html>

Interface `Import`

The Import interface represents an import in a master document:


interface Import {
    readonly attribute DOMString? href;
    readonly attribute Node ownerNode;
    readonly attribute Document content;
};

The href attribute must return the import location or null if none.

The ownerNode attribute must return the node that links master document to the import.

The content attribute must return the imported document.

The LinkImport interface provides access to a import from master document:


[NoInterfaceObject]
interface LinkImport {
    readonly attribute Import? import;
}

The import attribute must return the import for the node that implements this interface.

The link element implements LinkImport interface:


HTMLLinkElement implements LinkImport;

For link elements that do not represent imports, the import attribute of the LinkImport interface must return null. Similarly, if the user agent does not support imports, or whose resource is CORS-cross-origin, the import attribute of the LinkImport interface must return null.

Otherwise, the LinkImport interface's import attribute must return null if the corresponding element is not in a Document, and otherwise must return a Import object with the following properties:

import location: The import location must be the result of resolving the URL given by link element's href content attribute, relative to the element, or empty string if that fails.
owner node: The owner node value must be the the link element.

The same object must be returned each time.

imports have an import ready flag, which is initially unset. When an import is ready to be used, its import ready flag must be set.

A import in the context of the Document of an HTML parser or XML Parser is said to be an import that is blocking scripts if the element was created by that Document's parser, and the element is a link of type import when the element was created by the parser, and the element's import ready flag is not yet set, and, the last time the event loop has reached step 1, the element was in that Document, and the user agent hasn't given up on that import yet. A user agent may give up on a import at any time.

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. Implementors 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.

A Document has an import that is blocking scripts if there is either a an import that is blocking scripts in the context of that Document, or if that Document is in a browsing context that has a parent browsing context, and the active document of that parent browsing context itself has an import that is blocking scripts.

A Document has no import that is blocking scripts if it does not have an import that is blocking scripts as defined in the previous paragraph.

Loading Imports

The list of all imports that have been loaded by the master document is kept in the loaded import list, an ordered list of import location and imported document pairs. New items are added to the bottom of the list.

When a import is fetched, the user agent must run the import fetching algorithm, which must be equivalent to running these steps:

Input: LOCATION, the import location
Output: DOCUMENT, the imported document

If LOCATION is already in the loaded import list, let DOCUMENT be the imported document for LOCATION and stop.
Let DOCUMENT be a new Document that is an HTML document with no browsing context
Set DOCUMENT's content type to "text/html".
Set DOCUMENT's URL to LOCATION
Let PARSER be a new HTML parser, associated with DOCUMENT
Fetch a resource from LOCATION, with DOCUMENT as override referrer source and block cookies flag set:
1. For each task that the networking task source places on the task queue while fetching:
  1. Fill PARSER's input byte stream with the fetched bytes
  2. Let PARSER process the input byte stream
2. When no more bytes are available:
  1. Queue a task from the networking task source for PARSER to process implied EOF character
  2. Add LOCATION and DOCUMENT to the loaded import list
  3. Process sub-imports.

Each loaded import may also contain links to other imports, called sub-imports.

The sub-imports are discovered and processed with the sub-import processing algorithm, which must be equivalent to these steps:

Input: DOCUMENT the import document

For each link element in the import's document, in tree order:
1. Let LINK be this link element
2. If LINK's type is import:
  1. Obtain the import resources using LINK and import fetching algorithm

Parsing Imports

The parsing of imports is defined as a set of changes to the HTML Parsing.

Additions to Prepare A Script Algorithm

In step 15 of prepare a script algorithm, modify the last part of condition which begins with If element does not have a src attribute to read:

... and the Document of the HTML parser or XML parser that created the script element has a style sheet that is blocking scripts or has an import that is blocking scripts

Additions to Tree Construction Algorithm

In sub-condition named Otherwise of condition An end tag whose name is "script" in "text" insertion mode, modify step 3 to read:

If the parser's Document has a style sheet that is blocking scripts or has an import that is blocking scripts or the script's "ready to be parser-executed" flag is not set: spin the event loop until the parser's Document has no style sheet that is blocking scripts and has no import that is blocking scripts and the script's "ready to be parser-executed" flag is set.

Modify sub-step 1 of step 3 of the end to read:

Spin the event loop until the first script in the list of scripts that will execute when the document has finished parsing has its "ready to be parser-executed" flag set and the parser's Document has no style sheet that is blocking scripts and has has no import that is blocking scripts.

Additions to Parsing XHTML Documents

Modify step 3 of steps that run following preparing the script element to read:

Spin the event loop until the parser's Document has no style sheet that is blocking scripts and has no import that is blocking scripts and the pending parsing-blocking script's "ready to be parser-executed" flag is set.

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, 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, Angelina Fabbro, Anne van Kesteren, Boris Zbarsky, Brian Kardell, Daniel Buchner, Edward O'Connor, Eric Bidelman, Erik Arvidsson, Elliott Sprehn, Hayato Ito, James Simonsen, Jonas Sicking, 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.

HTML Imports

W3C First Public Working Draft 14 May 2013

Abstract

Status of This Document

Table of Contents

About this Document

Dependencies

Terminology

Link Type "`import`"

Interface `Import`

Loading Imports

Parsing Imports

Additions to Prepare A Script Algorithm

Additions to Tree Construction Algorithm

Additions to Parsing XHTML Documents

Acknowledgements

HTML Imports

W3C First Public Working Draft 14 May 2013

Abstract

Status of This Document

Table of Contents

About this Document

Dependencies

Terminology

Link Type "import"

Interface Import

Loading Imports

Parsing Imports

Additions to Prepare A Script Algorithm

Additions to Tree Construction Algorithm

Additions to Parsing XHTML Documents

Acknowledgements

Link Type "`import`"

Interface `Import`