ht-apply directive reference
Overview
The ht-apply directive performs variable substitution on the target HTML elements attributes and child text nodes.
Example
This example shows the ht-apply directive being used to template the <title>, <meta>, <h1>, and <article> elements.
1<!DOCTYPE html>
2<html>
3 <head>
4 <meta charset='utf-8'>
5 <title ht-apply>${ site.title } | ${ "Placeholder Title" }</title>
6 <meta ht-apply name='description' content='${ page.description, site.description }'>
7 </head>
8 <body>
9 <header>
10 <h1 ht-apply>${ page.title, "Hello, world." }</h1>
11 </header>
12 <article ht-apply>
13 ${ markdown(page.content, "") }
14 </article>
15 </body>
16</html>
Example output index.html
Let's see what happens when we process this template with the following [template data].
1{
2 site: {
3 title: "HyperTemplates",
4 description: "The pure-HTML templating system for the modern web."
5 },
6 page: {
7 title: "ht-apply directive",
8 description: "ht-apply directive reference documentation",
9 content: "Lorem ipsum, _hipsters_ get some!"
10 }
11}
The <title> and <meta name='description'> elements are updated with the variables substituted:
1<html lang='en-US'>
2 <head>
3 <meta charset='utf-8'>
4 <title>HyperTemplates | ht-apply directive</title>
5 <meta name='description' content='ht-apply directive reference documentation'>
6 </head>
7 <body>
8 <header>
9 <h1>ht-apply directive</h1>
10 </header>
11 <article>
12 <p>Lorem ipsum, <em>hipsters</em> get some.</p>
13 </article>
14 </body>
15</html>
PROTIP: Why are there so many
ht-applydirectives in this simple example? See declarative templating below to learn why HyperTemplates does not process every single element in your layouts.
Specification
Supported elements
The ht-apply directive can be used with any HTML element, including void elements.
1<meta ht-apply name='description' content='${ page.description, "Placeholder description." }' />
Directive syntax
The ht-apply directive is an HTML boolean attribute.
If it is present, HyperTemplates will perform variable substitution on the target element and its child text nodes.
Example:
1<title ht-apply='false'>${ page.title }</pull-quote>
This example demonstrates that ht-apply directives are invoked by the presence of the ht-apply attribute (i.e. ht-apply attribute values are ignored).
The ${ page.title } variable is a regular HTML text node
Declarative templating
HyperTemplates is a declarative templating system.
For example, <h1 ht-apply>${ page.title }</h1> uses the ht-apply directive to declare that HyperTemplates should perform variable substitution on the <h1> element.
Declarative templating systems codify intent. They also facilitate an important separation of concerns: theme developers only need to express the what, while the tooling is responsible for the how.
Declarative templating also comes with some nice benefits, including the overall performance of the templating system. Instead of scanning HTML files as plain text and looking for template variables, HyperTemplates parses HTML documents and uses highly performant CSS selectors to process individual HTML elements in a deterministic order.
PROTIP: declarative programming allows you to express desired outcomes without having to describe the entire control flow. In the context of a templating system like HyperTemplates, it means users don't have to think about the order in which elements are processed (see Pipeline).
Implicit variable substitution
The ht-apply directive is implied by the ht-each and ht-block directives, so it is not necessary to add the ht-apply directive to invoke variable substitution on ht-each and ht-block elements.
Example
In this example, it is not necessary to add the ht-apply directive to the <a> element.
Variable substitution is implied by ht-each.
1<header>
2 <nav>
3 <menu>
4 <a ht-each='link in ${ data.nav.links }' href='${ link.href }'>${ link.text, "Link" }</a>
5 </menu>
6 </nav>
7</header>