ht-template attribute

`ht-template` attribute reference

Overview

The ht-template attribute repeat the target HTML element once per occurrence of some template data.

When combined with other HyperTemplates templating attributes such as ht-content, ht-attrs, ht-if, and ht-include, the ht-template attribute is a powerful building block for defining dynamic layouts that adapt to the contents of template data.

Example

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

layout.html

 1<html lang='en-US'>
 2    <head>
 3        <meta charset='utf-8'>
 4        <title>Hello, world</title>
 5        <meta name='description' content='ht-template attribute reference'>
 6    </head>
 7    <body>
 8        <header>
 9            <nav>
10                <menu>
11                    <a ht-template='link:data.nav' ht-attrs='href:link.href'>
12                        <span ht-content='text:link.title,link.label'></span>
13                    </a>
14                </menu>
15            </nav>
16            <h1>ht-template</h1>
17        </header>
18        <main>
19            <h2><code>ht-template</code> attribute reference</h2>
20            <p>...</p>
21        </main>
22    </body>
23</html>

Example output index.html

Let's see what happens when we process this template with the following template data.

 1{
 2    site: {
 3        nav: [
 4            { label: "Home", href: "/" },
 5            { label: "Features", href: "/features/" },
 6            { label: "Docs", href: "/docs/" },
 7            { label: "Blog", href: "/blog/" },
 8        ]
 9    }
10}

The placeholder template <a> element will be cloned once for each item in the data.nav template data property (an object array). The end result should be four (4) <a> elements dynamically generated by HyperTemplates.

 1<html lang='en-US'>
 2    <head>
 3        <meta charset='utf-8'>
 4        <title>Hello, world</title>
 5        <meta name='description' content='ht-template attribute reference'>
 6    </head>
 7    <body>
 8        <header>
 9            <nav>
10                <menu>
11                    <a href='/'>
12                        <span>Home</span>
13                    </a>
14                    <a href='/features/'>
15                        <span>Features</span>
16                    </a>
17                    <a href='/docs/'>
18                        <span>Docs</span>
19                    </a>
20                    <a href='/blog/'>
21                        <span>Blog</span>
22                    </a>
23                </menu>
24            </nav>
25            <h1>ht-template</h1>
26        </header>
27        <main>
28            <h2><code>ht-template</code> attribute reference</h2>
29            <p>...</p>
30        </main>
31    </body>
32</html>

Specification

Supported elements

The ht-template attribute can be used with any HTML element, including void elements.

1<meta ht-template='property:page.metadata' hyper-attrs='name:property.name;content:property.value' />

Attribute syntax

The ht-template attribute defines templating conditions expressed as a semicolon-separated list of variable:value pairs.

The variable is a name assigned to a template data property that will be passed into the nested template.

The value is a comma-separated list of dot-notation style references to one or more template data properties. If multiple properties are defined for a given template variable, the first non-empty property will be used.

1<a ht-template='link:site.nav;page:page' ht-attrs='href:link.href'>

In this example, two variables will be added to the template data that gets passed in to the nested <a> template: link and page.

NOTE: when multiple variables are defined in an ht-template attribute, the template is only processed once per iteration of the first variable (in this example, that would be the link variable).

Placeholder template

An HTML element with an ht-template attribute is called an "placeholder template". Placeholder and their child elements (if any) are cloned once per iteration of the referenced template data value(s).

partials/nav.html

1<nav>
2    <a ht-template='link:site.nav' ht-attrs='href:link.href'>
3        <span ht-content='link.label'></span>
4    </a>
5</nav>

In this example, the <a> element together with its child <span> element make up an iterator template.