<html-import>

**Custom HTML element for importing HTML documents (or parts of documents) into
other HTML documents on the fly!** First install the package:

``shell
npm install @sirpepe/html-import
`

Then either load the module or the minified bundle and then use
in your HTML:

`html





This text gets replaced when the content of the body element from
content.html once it has loaded. If the browser does not support custom
elements, this text is rendered as a fallback.


This text gets replaced by elements matching .foo (that are not nested
inside something matching .foo themselves) in content.html when it has
loaded. Note that the selector's scope is not limited to the body, so you
can import elements from a document's head as well.

This text gets replaced by whatever the src property is set to if and when
it gets set to something. This way the element works kindof like an iframe.

`

Notable features:

* Import whatever you like: plain HTML elements, style and link elements and even script elements work. Non-blocking scripts (script elements with async, defer or type="module") in imported HTML files work as expected. Blocking scripts will execute asynchronously, and thus may cause unintended effects.
* Nest imports as much as needed (as long as no circular imports exist)
* Optionally filter imported elements by selector with an attribute: . Fragments also work: .
* Reactive imports: updating the src or selector attributes replaces already imported content with new content as specified by the attributes
* No frameworks, libraries or build tools required! You can use the ESM version of this component with your favorite build tool or just drop the minified version right into your web project.
* Easy to customize through subclassing, monkey patching or events handlers.

Guide

$3

To use the element in HTML you have to import the main script somewhere. The
custom element will register itself automatically and upgrade any
already-existing instances of . Any new instances will initialize
in an upgraded state.

The element has two important HTML attributes:

* src defines the source HTML document for an import element. You can omit, remove or update the attribute at any time and the element will (if necessary) reload the source file and update itself. Both relative and absolute URLs work.
selector defines a selector for specific elements to import from the source document. Any CSS selector that your target browsers support is valid. You can omit, remove or update the attribute at any time and the element will (if necessary) reload the source file and update itself with the new elements. If the selector attribute is missing or empty and the src attribute is set, the import element will import all content* from the target document's element (including text nodes). If the selector attribute is set, it selects elements from the entire target document (not just the ).

If the selector attribute is defined and if the src attribute contains a URL
with a fragment identifier, the element will import only the fragment target
if it also matches the selector. In summary:

* no selector, no fragment in URL = entire body contents
* selector, no fragment in URL = all elements matching the selector
* no selector, fragment in URL = first element matching the fragment
* selector and fragment in URL = first element matching the fragment if it that also matches selector

The element performs fetch() requests under the hood. Once such a request has
finished, the element's contents get replaced by whatever the result HTML
(optionally filtered by the selector). The content between an
element's tags thus serves as both its initial content and its fallback content
in case some scripts break or an ancient browser without support for custom
elements comes along.

$3

The JS API for consists of a constructor function, four events,
two method, and three DOM properties (plus attributes for event handlers).

#### Constructor

You can construct instances of the element by using the HTMLImportElement
constructor:

`javascript
import HTMLImportElement from "html-import";

let myImportElement = new HTMLImportElement(
"/optional/initial/src/value",
"#optionalSelector"
);

document.body.append(myImportElement);
`

If you don't use ESM modules, you can always get access to the constructor via
the custom elements registry:

`javascript
window.customElements.whenDefined("html-import").then(() => {
let HTMLImportElement = window.customElements.get("html-import");
});
`

#### Events

HTMLImportElement can fire four events:

* importstart: Fires when the element starts to load content, eg. after a change to the attributes src or selector or after calling reload()
* importdone: Fires when the element has imported content
* importfail Fires when importing content has failed (eg. due to 404). The event object implements a property detail that contains the reason for the failure.
* importabort Fires when the element was about to import content, but got interrupted (eg. by a new src value) before it could finish

All four events bubble and aren't cancelable. Note that you can use old-school
attribute event handlers a la in addition to
addEventListener().

#### Methods

HTMLImportElement implements two DOM methods:

* reload() causes a re-load without the need to change any attributes or properties. The method takes no arguments and returns a promise that resolves to an array of imported elements and the imported document's titles (just like the promise returned by done as described below).
* done() returns a promise for that resolves when the element's target document has been loaded (or has failed to load due to an error).

The promises returned by reload() and done() resolve to an array of data
about what was imported:

`javascript
let element = document.querySelector("html-import");
element.done.then( (data) => {
// data[0] = { element: affectedImportElement; title: "Imported document's title"; }
// data[1] = { element: firstNestedImportElement; title: "Nested imported document's title"; }
// etc.
});
`

#### Properties

HTMLImportElement implements eight DOM properties:

* src reflects the src content attribute. Can be used as a setter to change the src value. As a getter, it always returns absolute URLs, even when the HTML attribute is relative (just like a element's href attribute). Returns the empty string when there's no src set.
* selector reflects the selector content attribute. Can be used as a setter to change the selector value.
* state returns one of "loading", "done", "fail" and "ready", indicating the element's loading state
* onstart, ondone, onfail and onabort event handlers

Note that the internal loading mechanism for batches attribute
updates and cleanly terminates any ongoing request if a change to src or
selector occurs. You don't have to concern yourself with efficiency, just set
whatever attributes or DOM properties you want to change!

$3

Any change to the attributes src or selector causes the imported content to
update. The old nodes get removed and replaced by the newly imported content.
This means that it is easy to "ajaxify" any old collection of static HTML
documents:

1. Just wrap every page's main content in (a minimal change to your project's main template)
2. Add a bit of javascript to intercept navigation events and manage the history (you can use your favorite routing library or just write a few lines yourself)

``html








Demo site




• Start


• About


• Contact

Welcome to the demo's start page

`

Clicks on the navigation links update the element's src
attribute, which causes it to load the respective page, extract the content from
the element from there and dump it into this page's
element. Add a little extra JS for routing and your whole page
suddenly feels like a SPA - when all you needed to do was to wrap every page's
main content in and write about 50 lines of JavaScript to
intercept clicks and manage the navigation history. If something breaks or an
ancient browser comes along, your project will still work via traditional page
loads.

Check out demo/staticsite/index.html to see this principle in action.

$3

You can easily customize the element's behavior by subclassing or monkey
patching HTMLImportElement. Three methods on the HTMLImportElement class
are hooks for extensions:

* public async fetch(url: string, signal: AbortSignal): Promise downloads the text content from a URL
* public beforeReplaceContent(content: DocumentFragment): DocumentFragment modifies the content before it is used
* replaceContent(newContent: DocumentFragment): void controls the actual replacing of the old content

The following HTMLImportMarkdownElement illustrates how you can easily build
on top of :

`javascript
import marked from "marked";
import HTMLImportElement from "html-import";

export default class HTMLImportMarkdownElement extends HTMLImportElement {
get [Symbol.toStringTag]() {
return "HTMLMarkdownImportElement";
}

beforeReplaceContent(content) {
const contentContainer = this.ownerDocument.createElement("template");
let html = "";
for (const node of content.childNodes) {
if (node.nodeType === Node.TEXT_NODE) {
html += node.textContent;
} else if (node instanceof HTMLElement) {
html += node.innerText;
}
}
contentContainer.innerHTML = marked(html);
return contentContainer.content;
}
}

window.customElements.define("markdown-import", HTMLImportMarkdownElement);
`

Instead of subclassing, you can always monkey patch the prototype. If, for
example, you'd like to place the imported content in a shadow tree, just
overwrite replaceContent() like this:

`javascript
HTMLImportElement.prototype.replaceContent = function(newContent) {
if (!this.shadowRoot) {
this.shadowRoot = this.attachShadow({ mode: "open" });
} else {
this.shadowRoot.innerHTML = "";
}
this.shadowRoot.append(newContent);
}
`

Try demo/monkeypatch/index.html to see this hack in action!

To run code on newly imported content each time the content changes, you can
also add a listener to the importdone event and modify the event's target
content (that is, the content that has just been inserted into the
element in question) as needed:

`javascript
window.addEventListener("importdone", (evt) => doStuff(evt.target.children));
`

$3

* 3.0.0: Remove verbose property, turn done from a getter into a method, simplify rules for promise resolution, replace CustomEvent with proper event subclasses, remove OnEventMixin, switch license to MIT, update toolchain
* 2.1.0: Add verbose` property
* 2.0.1: Fix a bug that prevented scripts that were nested in other elements from being imported properly
* 2.0.0: Complete rewrite

$3

* Because I'm a lazy linux-using slob this element has so far only been tested in Chrome and Firefox on Ubuntu.

License

MIT