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

fragments/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.

Limit and offset

The ht-limit and ht-offset attributes can be used to configure partial iterators. Use ht-limit to limit the number of elements generated by an ht-template iterator. Use ht-offset to skip the first n items in the ht-template template data.

The following example shows how to configure a feed page with three "featured posts", followed by any remaining posts. Both blocks are using the same page.feed.pages template data.

fragments/blog.html

 1<!-- Blog posts fragment -->
 2<section id='blog'>
 3    <style>
 4        featured-posts {
 5            display: grid;
 6            grid-auto-flow: column;
 7            grid-template-columns: 1fr 1fr 1fr;
 8        }
 9        recent-posts {
10            display: grid;
11            grid-auto-flow: row;
12            grid-template-columns: 1fr;
13        }
14    </style>
15    <featured-posts>
16        <a ht-template='post:page.feed.pages' ht-limit='3' ht-attr='href:post.href'>
17            <!-- Featured Post Layout -->
18        </a>
19    </featured-posts>
20    <recent-posts>
21        <a ht-template='post:page.feed.pages' ht-offset='3' ht-attr='href:post.href'>
22            <!-- Recent Post Layout -->
23        </a>
24    </recent-posts>
25</section>

If the recent posts block should be further constrained to show a limited number of items, the ht-limit attribute could be used alongside ht-offset.

1<recent-posts>
2    <a ht-template='post:page.feed.pages' ht-offset='3' ht-limit='6' ht-attr='href:post.href'>
3        <!-- Recent Post Layout -->
4    </a>
5</recent-posts>

NOTE: ht-limit is always applied as a count, not a range. The equivalent Javascript is an Array.slice() expression of arr.slice(offset, offset+limit). In the example above that would be arr.slice(3, 3+6) (up to 6 items), not arr.slice(3, 6) (up to 3 items).