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).

Template data

Two auto-generated template data properties are available during ht-template iteration:

ht.index a one-indexed integer representing the position in the loop
ht.count the count of items in the collection

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.