HTML5 Imports: Import HTML Files Into HTML Files

The „link“ element is a blessing. It allows for easy embedding of stylesheets and JavaScripts needed in multiple documents. It didn’t allow the embedding of HTML files, though. To achieve that we were limited to the „iframes“ element or the JavaScript method „XMLHttpRequest()“. Thanks to the new HTML5 Imports, we can now use the „“ element to load one HTML file into another.

Simple Markup in the Header

Embedding an HTML file is simple. All we need to do is use the common „<link>“ element. Then we add the value „import“ to the „rel“ attribute. Using „href“ we attach the URL of the HTML file, just like we are used to when it comes to stylesheets and scripts.

<link href="extern.html" rel="import" />

Should the file to be imported contain further „style“ or „script“ elements, these will be imported as well. It does not matter whether these elements are marked up in the head or the body of the document. One use case for HTML5 Imports could well be, to collect all the stylesheets and scripts needed in a given project and add to one single HTML file, which then gets imported into all the other project files. This largely simplifies the maintenance of bigger projects.

While the imported document contains stylesheets, these will be directly apllied. Previously defined stylesheets of the parent document will be overwritten. To make sure this doesn’t happen, take care of the position of the import link in the parent document. The same is true for JavaScripts. Even externally referenced elements from the imported document will be loaded into the parent document.

Accessing Contents of the Import File

Other content from the imported document will be loaded, but not displayed. All the texts, images and other media will not be visible as they are not part of the DOM tree of the parent document. You can still access them via JavaScript, though.

var extern = document.getElementsByTagName("link")[0].import;

Our example assumes that the first „link“ element loads an HTML file. Using the JavaScript property „import“ we write the complete tree structure of the imported file to a variable. From there we are able to access the individual nodes via JavaScript.

var absatz = extern.getElementsByTagName("p")[0];

From here we can access and read all nodes using the common JavaScript methods such as „getElementsByTagName()“. Now we are able to add them comfortably to the DOM tree of the parent document. In a more radical approach we could as well replace the „body“ element completely with the contents of the imported file.

window.addEventListener("load", function() {
document.getElementsByTagName("html")[0].replaceChild(extern.getElementsByTagName("body")[0], document.getElementsByTagName("body")[0]);
}, false);

Our example replaces the content of the „body“ element using „replaceChild()“. To make sure the replacement doesn’t start before all elements are loaded, the function is bound to an event listener added via „addEventListener()“.

Browser Support

At the time of this writing only Chrome supports HTML5 Imports. Also you have to enable the functionality manually. Call „chrome://flags“ from the address bar, which gives you access to the experimental features. Look for „Activate HTML Imports“ and – well – activate it. After a fresh start of your Chrome HTML5 Imports will be available.

Use the following function to check whether a given browser supports HTML5 Imports.

if ("import" in document.createElement("link")) {
// HTML5 Imports are supported.
}

Older browsers can make use of a polyfill, which emulates HTML5 Imports in unsupported browsers. That way there is no need to go without HTML5 Imports in modern web projects.

(dpe)