Introducing: ht-include

Template Includes Tutorial

Goal

In this lesson we will split up a layout template into individual components to make our growing website easier to maintain.

Introduction

As our layout template starts to become more complex, it would be nice if we could split up the layout code into individual components. Organizing our code in this way not only makes it easier to maintain, it also makes the individual components reusable across multiple layouts!

Let's see how to do this with the ht-include attribute.

Exercises

EXERCISE 1: Create layout partials

Create new <header> and <footer> layout partials.

First let's create a new subdirectory and add two new files to our project.

1mkdir partials
2touch partials/header.html partials/footer.html

Now lets add the <header> layout to partials/header.html. While we're at it, let's flesh it out a little bit by adding some navigation links.

partials/header.html

1<header ht-if='title'>
2    <nav>
3        <menu>
4            <a href='/'>Home</a>
5            <a href='/about/'>About</a>
6        </menu>
7    </nav>
8    <h1 ht-content='title'></h1>
9</header>

Next, let's add the <footer> layout to partials/footer.html.

partials/footer.html

1<footer ht-if='copyright'>
2    &copy; <span ht-content='html:copyright'>2024</span> &bullet; Powered by HyperTemplates&trade;
3</footer>

OK, great. We can now use these <header> and <footer> components across multiple layouts! Let's move on to the next step to see how to use these in our default layout.

EXERCISE 2: Include external sources

Use the ht-include attribute to include external sources in a layout template.

Let's update layouts/default.html to include the <header> and <footer> components.

layouts/default.html

 1<html lang='en-US'>
 2    <head>
 3        <meta charset='utf-8'>
 4        <title ht-content='title'>Learn HyperTemplates</title>
 5        <meta name='description' ht-attrs='content:description'>
 6    </head>
 7    <body>
 8        <header ht-include='partials/header.html' id='header'></header>
 9        <main>
10            <article ht-content='markdown:content'>
11                <h2>Hello, world</h2>
12                <p>
13                    This is an <a href='https://developer.mozilla.org/en-US/docs/Web/HTML'>HTML</a> layout!
14                </p>
15            </article>
16        </main>
17        <footer ht-include='partials/footer' id='footer'></footer>
18    </body>
19</html>

Lookin' good! 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

HyperTemplates replaced our placeholder <header> and <footer> elements with the contents of partials/header.html and partials/footer, respectively.

PROTIP: did you notice that one of our includes was not like the other one? We included our header with ht-include='partials/header.html, but our footer with ht-include='partials/footer', sans file extension. This shorthand include reference Just Works™ in because HyperTemplates is a pure-HTML templating system, so we can safely assume that included file should have an .html extension. 🤌

The order of operations is important here: ht-include attributes are processed before all other templating steps, so our components are effectively inserted into our layout before content and attribute templating.

Oh and there's one more thing: did you notice that the id attributes on the <header> and <footer> elements were retained in the rendered HTML? This is called attribute forwarding, and it's one of the many more subtle features of HyperTemplates that facilitate progressive enhancement.

Discussion

In this lesson we split our <header> and <footer> into smaller components and composed them together using the ht-include attribute. This not only makes our layouts/default.html template easier to read, it means we can reuse the components we created in future layouts. Bonus!

We also introduced a new type of templating opportunity during this lesson when we added navigation links to our header. It's the first example we've encountered where we have a bit of layout that we'd like to repeat. Let's learn how to configure repeating elements in the final lesson of this tutorial.

Core Concepts

Learn more about the concepts in this lesson:

Attributes reference

ht-include attribute

Do you have any questions and/or feedback about ht-include 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 lesson 5. 👉

← PREV
Lesson 3: Introducing ht-if NEXT →
Lesson 5: Introducing ht-template

Template Includes Tutorial

Goal

Introduction

Exercises

Discussion

💬 Join the community