HTML Imports

HTML Imports (or simply imports) is one of the piece from Web Components model, which allows you to load full external html document into your web page and that too without ajax. Imports provide convention for bundling HTML/CSS/JS into single deliverable component. Using imports you can create custom elements and then use them as new tags in your master document.

HTML Imports are a way to include and reuse HTML documents in other HTML documents.

We will learn how to use HTML imports in projects, and also how we can use them with <template> to create dynamic web pages.

Table of Content

  1. The Lowdown
  2. Using the Content
  3. Imports and Templates
  4. Browser Support


1. The Lowdown

Include an import in your document using <link rel="import">. Yes, it is a just link tag, with new value for rel attribute.

1
2
3

<head>
    <link rel="import" href="path/to/import.html">
</head>

The referred url to imported document is an import location. For security reasons HTML imports adhere to same-origin policy. The import from another domain, the import location needs to be CORS set up correctly.

1
2

<!-- Cross domain resources must be set up properly. -->
<link rel="import" href="http://example.com/elements.html">


2. Using the content

Importing external html doesn’t pop the content of external document in the current document, it just fetches the content, parses it and makes it available for use. You have to use the content by writing script, and you can access the content by examining the import property of corresponding link element.

1

  var content = document.querySelector( 'link[rel="import"]' ).import;

Now as you have imported the external document, you can grab a specific portion of imported document and clone it to your page. Here is a Demo.

1
2
3
4
5

var content = document.querySelector( 'link[rel="import"]' ).import;

var el = content.querySelector( ".warning" );

document.body.appendChild( el.cloneNode(true) );

3. Imports and Templates

Now you understand how to import external document and access its content, now lets look at how you can use this technology with <template> element.

Let’s say that we are building a todo app and want a component that displays a todo item with a small description. Let’s create a template that is responsible for displaying a todo item. Store this template in separate HTML file - template.html.

1
2
3
4
5
6

<template id="todo-item-template">
  <div class="todo-item">
    <h2 class="title">{{ title }}</h2>
    <p class="description">{{ description }}</p>
  </div>
</template>

I am using underscore.js for templating. Also I have changed the interpolate setting using _.templateSettings.

Next we need to import this template into our main document - index.html. Just add an <link> tag with rel="import" attribute and href pointing to template.html. Lets also add and id attribute to tag this element that will help us to reference the element using JavaScript.

1
2
3

  <head>
    <link rel="import" href="template.html" id="import-template">
  </head>

Now is the time write some script and stamp out the todo template.

First of all, get the import link element and then use import property on that element to access the content of imported document.

1
2

  var templatesImport = document.querySelector( "#import-template" );
  var importContent = templatesImport.import;

Next find the template element and then access the content that we need to clone, i.e. .todo-item element.

1
2

  var template = importContent.querySelector( "#todo-item-template" );
  var todoItem = template.content.querySelector( ".todo-item" );

Now let’s use underscore.js to compile our template with JSON and then append the newly create dom element into main document.

1
2
3
4
5
6
7

  var json = {"title": "Todo Title", "description": "Todo Description"};

  var _template = _.template( content.outerHTML );
  var _dom = _template( json );

  var todoItems = document.querySelector( "#todo-items" );
  todoItems.appendChild( _dom.toDOM() );

_template is function that underscore return after compiling html template. _dom is actual html snippet that we will render in main document. _toDOM is function on String which converts the string into dom element so that you can append it as child. Here is Demo.

See the Pen HTML Imports by Shridhar Deshmukh (@shree33) on CodePen.

That’s it! You got your first todo item and now you also know how to use HTML imports and template together to create dynamic pages.

4. Browser Support

Browser support is still in the early days. Before using the feature, you can check to see if the user’s browser supports HTML imports by looking for the import property on <link> element.

1
2
3
4
5
6
7
8
9

  function supportsImports() {
    return 'import' in document.createElement( 'link' );
  }

  if ( supportsImports() ) {
    // Good to go!
  } else {
    // Use other libraries/require systems to load files.
  }

You can also keep checking caniuse.com for browser support.

Comments