Introducing: ht-template

Template Iterators Tutorial

Goal

In this lesson we will learn how to implement repeating elements in a layout template using the ht-template attribute.

What is a template iterator?

Whether it's lists, or an image gallery, or any other repetitive content, there will eventually come a time when some portion of a layout template needs to be repeated based on the page content. Template iterators save time and make dymanic layouts possible by allowing us to reuse small portions of a layout template. By keeping our layout templates DRY we also reduce the likelihood of inconsistencies, improving the overall quality of our websites.

As with conditional if...else templating, this is another area where templating systems that are based on traditional programming languages excel by providing access to for...in and for...of style loops. The tradeoff is that these more advance templating features typically result in template code that can become difficult to reason about as you're blending HTML with something completely different from HTML in order to generate HTML.

Take this snippet from the Hugo range documentation for example:

{{ range $m }}
  <p>{{ .name }} is {{ .age }}</p>
{{ end }}

There's more Go code than HTML here!

Thankfully there are no such tradeoffs with HyperTemplates' namesake¹ attribute. Let's see how template iterators work in the following exercises.

Exercises

EXERCISE 1: Create a template iterator

Use the ht-template attribute to repeat some portion layout once per occurrence of a template data property.

Let's template those hard-coded <nav> links we added in the previous lesson so that we can more easily manage them from template data. To do that we'll need to modify the layout in partials/header.html as follows:

partials/header.html

 1<header ht-if='title'>
 2    <nav>
 3        <menu>
 4            <a ht-template='link:nav' ht-attrs='href:link.href,link.url'>
 5              <span ht-content='link.title,link.label,link.name,link.text'></span>
 6            </a>
 7        </menu>
 8    </nav>
 9    <h1 ht-content='title'></h1>
10</header>

This ht-template attribute tells HyperTemplates to clone the <a> element for each item in the nav property and treat is as a nested layout template. It assigns the value of each item in nav to a new variable called link and uses that as the template data for the nested template.

Let's move on to the next step to see how the template data side of this equation works.

EXERCISE 2: create repeated content

Add a list of links to our template data to see how HyperTemplates handles repeated content.

Let's add some navigation links to content/index.md.

content/index.md

 1---
 2title: Introduction to HTML templating
 3description: My first HyperTemplates page!
 4coyright: 2025 Acme Inc
 5nav:
 6  - label: Home
 7    href: /
 8  - title: About
 9    href: /about
10  - label: Contact
11    url: /contact
12---
13  
14## Hello, world
15  
16This is my first HyperTemplates content!

OK, let's render the page again, then refresh the browser or view the updated index.html file to see what changed.

1hyperctl render -d content/index.md -l layouts/default.html > index.html

We restored the original "Home" and "About" links, and easily added a third "Contact" link right from our template data! Pretty cool, right? 😊

Did you notice? We introduced another feature in this step: the ht-content attributes in the <a> element are referencing multiple properties:

1ht-content='link.title,link.label,link.name,link.text'

It's a good thing because our nav: array had a mix of label and title properties, and href and url properties. Oops! This is a silly example that shows how HyperTemplates components can be used with a variety of data structures.

Discussion

Congratulations, you've just completed the "Learn HyperTemplates" tutorial! 🏁

In this lesson we replaced some repetitive layout with a template iterator using the ht-template attribute. We also added a third navigation link!

Do you have any questions and/or feedback about ht-template or this "Learn HyperTemplates" tutorial? Join the @hypertexting.community and visit the "Getting Started" category. 💬

When you're ready, let's go ahead and move on to the review. 👉

← PREV
Lesson 4: Introducing ht-include NEXT →
Tutorial Review