ht-include directive

`ht-include` directive reference

Overview

The ht-include directive replaces target HTML elements with elements from an external source (a local or remote file). The ht-include directive 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 directive 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='fragments/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 directive in this example will replace the placeholder <header> element with the contents of the referenced include source (fragments/header.html), which contains an HTML DocumentFragment.

Specification

Supported elements

The ht-include directive 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!

NOTE: ht-include directives are processed recursively, allowing components to be composed of other components.

Directive syntax

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

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

Placeholder elements

An HTML element with an ht-include directive is called a "placeholder element". If the fragment referenced by a given ht-include directive 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 placeholder elements contain additional HTML attributes, HyperTemplates will copy the HTML attributes from the placeholder element to the first element in the included fragment.

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 directive attribute is excluded from attribute forwarding.

Include URIs

HyperTemplates ht-include directives contain relative URIs that reference fragments. 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.

See fragments for more information.