ht-include attribute

`ht-include` attribute reference

Overview

The ht-include attribute replaces target HTML elements with elements from an external source (a local or remote file). The ht-include attribute is one of the most powerful tools in the HyperTemplates toolbox, making it possible to compose complex layouts from reusable components.

Example

This example shows the ht-include attribute being used to template the <header> element.

layout.html

 1<!DOCTYPE html>
 2<html>
 3    <head>
 4        <meta charset='utf-8'>
 5        <title>Introducing: Template Includes</title>
 6    </head>
 7    <body>
 8        <header ht-include='partials/header.html' id='hero'></header>
 9        <article>
10            <h2>Hello, world</h2>
11            <p>Lorem ipsum, hipsters get some.</p>
12        </article>
13    </body>
14</html>

The ht-include attribute in this example will replace the placeholder <header> element with the contents of the referenced include source (partials/header.html), which contains an HTML DocumentFragment.

Specification

Supported elements

The ht-include attribute can be used with any HTML element.

1<a href='/'>
2    <svg ht-include='img/logo.svg'></svg>
3</a>

A BRIEF ASIDE: Discovering that we could use ht-include to template SVG images was one of the major "aha" moments we experienced early on in the development of HyperTemplates. This was a delightful side effect of the "pure-HTML" philosophy behind HyperTemplates. We suspect there are yet other unexpected but delightful side effects that we haven't yet discovered. If you encounter any such deligtful surprises, please let us know!

Attribute syntax

The ht-include attribute provides templating instructions, expressed as a comma-separated list of include URIs, where each URI contains an include source.

1<header ht-include='partials/hero'></header>

Placeholder elements

An HTML element with an ht-include attribute is called a "placeholder element". If the template data property referenced by a given ht-include attribute exists, the placeholder element is replaced by the include source.

1<button ht-include='path/to/source.html'></button>

In this example, the <button> element is a placeholder element.

Attribute forwarding

When the tag name of a placeholder element matches the tag name of the first element in the include source, HyperTemplates will copy HTML attributes from the placeholder element to the first element in the include source. Attribute templating occurs before include source elements are inserted into the template.

1<nav>
2    <a href='/'>
3        <svg ht-include='static/img/logo.svg' height='120' width='auto'></svg>
4    </a>
5</nav>

In this example the height and width attributes will be copied to the <svg> element in static/img/logo.svg before it is inserted into the temlpate.

NOTE: The ht-include attribute is excluded from attribute forwarding.

Include URIs

HyperTemplates ht-include attributes contain URIs that reference files containing DOM elements. These URIs are referred to as "include URIs". The contents of the include URI files are include sources.

1<button ht-include='path/to/source.html'></button>

In this example, path/to/source.html is an include URI.

PROTIP: because HyperTemplates is the pure-HTML templating system, it assumes that same-origin include URIs are references to HTML documents with .html file extensions.

An include URI of /path/to/source is the same as /path/to/source.html.

Include sources

An include source is an HTML DocumentFragment referenced by a ht-include attribute.

What is a DocumentFragment? An HTML DocumentFragment is a collection of one or more HTML elements, not a complete HTML Document containing a root <html> element with child <head> and <body> elements.