ht-include directive

`ht-include` directive reference

Overview

The ht-include directive replaces target element with an HTML fragment from the configured theme. Includes are 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 except the <html>, <head>, and <body> elements.

Example

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

Even though ht-include doesn't support the <head> element itself, we strongly recommend using an ht-include directive inside the <head> element. This is an excellent way to ensure that certain <head> elements are included in every page across an entire website.

layouts/default.html

 1<!DOCTYPE html>
 2<html lang='en-US'>
 3    <head>
 4        <meta ht-include='fragments/head.html'></meta>
 5        <!-- other head elements -->
 6    </head>
 7    <body>
 8        <!-- page content -->
 9    </body>
10</html>

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 join the @hypertexting.community 💬 and let us know!

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

Directive syntax

An ht-include expression is one theme-relative fragment path. The .html extension is optional: fragments/header and fragments/header.html are equivalent.

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 and ht-block directive attributes are excluded from attribute forwarding.

Include sources

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

See fragments for more information.