Template Variables

Overview

Template variables are placeholders that are replaced by template data. Template variables can be used to populate HTML element attributes, and HTML element contents.

Example

This example shows how variable substitution works in HyperTemplates.

1<head>
2    <title ht-apply>${ site.title } | ${ page.title }</title>
3    <meta ht-apply name='description' content='${ page.description }'>
4    <!-- ...other <head> elements... -->
5</head>

If site.title is HyperTemplates, page.title is Template Variables, and page.description is Learn more about the HyperTemplates variable substitution system., the rendered HTML for this fragment would be as follows:

1<head>
2    <title>HyperTemplates | Template Variables</title>
3    <meta name='description' content='Learn more about the HyperTemplates variable substitution system.'>
4    <!-- other <head> elements -->
5</head>

Specification

Supported elements

Template variables can be used with any HTML element.

See template variable syntax for more information on the template variable CSS syntax, which is required when applying variables to a <style> element or style attribute.

Template variable syntax

Template variables are defined using delimiters. The default syntax for a template variable is a string that begins with ${ and ends with }.

Example

1<a href='${ page.path }' ht-apply>${ page.title }</a>

An alternate syntax is required for <style> elements and style attributes where the default variable syntax is invalid CSS. Template variables in a <style> elements or style attributes begin with --ht-value( and end with ). The --ht-value() syntax also supports CSS-style fallback values as an optional second argument. Fallback values can be any valid CSS value.

Example

1<head>
2    <!-- other <head> elements -->
3
4    <style id='layout'>
5        :root {
6            --color-1: --ht-value("site.colors.default", rgba(236, 120, 184, 1.0))
7        }
8    </style>
9</head>

In this example the --ht-value( ... ) variable will be replaced with the template data property site.colors.default if it is defined, or else it will use a fallback value of rgba(236, 120, 184, 1.0).

Template variables are not Javascript (or CSS)

The default template variable syntax is inspired by Javascript template literals, but they are not Javascript. However, the syntax for performing "string interpolation" with HyperTemplates variables should look & feel very similar to a Javascript template literal that is only doing variable substitution.

Here's an example of how to perform string interpolation using a Javascript template literal:
1`${ site.title } | ${ page.title }`
Note the Javascript-required ` backtick characters.

This same string interpolation is possible using HyperTemplates variables, sans backticks:
1<title ht-apply>${ site.title } | ${ page.title }</title>
Similarly, the template variable CSS --ht-value() syntax is inspired by CSS custom functions, but they are not CSS. By adopting the custom function syntax, template variables in <style> elements are valid CSS. If/when a CSS template variable cannot be processed by HyperTemplates (e.g. due to missing template data), they will be present in the generated HTML files and all major browsers will simply ignore them.

Template variable functions

Template variables support functions, and there are three built-in functions: get, html, and markdown.

get function

The get function gets template data values.

The get function supports two arguments: a comma-separated list of [template data keys], and a default value. Default values must be quoted, and they must be the last argument passed to the get function.

Examples

1<title>${ get "page.title, site.title", "Default Title" }</title>

1<title>${ get page.title, site.title, "Default Title" }</title>

Both examples shows the get function with two arguments:

A comma-separated list of [template data keys] (i.e. page.title, site.title)
A string literal default value (i.e. "Default Title")

The HyperTemplates variable parser automatically recognizes ${ get page.title, site.title, "Default Title" } as two arguments and not three because it detects the argument types – the unquoted template data keys vs the quoted default value – in addition to the delimiters (the comma characters).

html function

The html function converts HTML strings to HTML elements.

Example

If a template data property contains HTML strings, you may see HTML tags as plain text.

1<!-- fragment -->
2<div ht-apply>
3    ${ page.overview }
4</div>
5
6<!-- output -->
7<div>
8    "<p>Lorem ipsum hipsters get some</p>" <!-- this is a quoted HTML string -->
9</div>

Use the html function to convert HTML strings to elements:

1<!-- fragment -->
2<div ht-apply>
3    ${ html page.overview }
4</div>
5
6<!-- output -->
7<div>
8    <p>Lorem ipsum hipsters get some</p> <!-- this is an HTML element -->
9</div>

NOTE: the html function is available in HTML content template variables, but it is not allowed in HTML attribute variables.

markdown functions

The markdown function converts Markdown strings to HTML elements.

Example

If a template data property contains Markdown strings, you may see the markup as plain text.

 1<!-- fragment -->
 2<div ht-apply>
 3    ${ page.overview }
 4</div>
 5
 6<!-- output -->
 7<div>
 8    ## Hello world
 9      
10    Lorem ipsum, hipsters get some.
11</div>

Use the markdown function to convert Markdown strings to elements:

 1<!-- fragment -->
 2<div ht-apply>
 3    ${ markdown page.overview }
 4</div>
 5
 6<!-- output -->
 7<div>
 8    <h2>Hello world</h2>
 9    <p>Lorem ipsum, hipsters get some.</p>
10</div>

NOTE: the markdown function is available in HTML content template variables, but it is not allowed in HTML attribute variables.

Plugin functions

Additional functions are added using template variable plugins.

Template variable plugins

HyperTemplates supports custom template variable functions via plugins. A template variable plugin is created by adding a Javascript file to the site.config.plugins_dir or theme.config.plugins_dir directory with a plugin entrypoint named plugin.

Examples

Both of the following examples create a plugin called uppercase (created via the plugins/uppercase.js file). In the first example the uppercase plugin entrypoint function is defined via a function declaration (i.e. function plugin(input="") { ... }).

plugins/uppercase.js

1// uppercase transforms strings to uppercase
2function plugin(input="") {
3    if (typeof input !== "string") { return input }
4    return input.toUpperCase()
5};

In the second example the uppercase plugin entrypoint function is defined via a const declaration (const plugin = uppercase).

plugins/uppercase.js

1// upper transforms strings to uppercase
2function uppercase(input="") {
3    if (typeof input !== "string") { return input }
4    return input.toUpperCase()
5};
6const plugin = uppercase;

Implicit gets

A template variable that doesn't begin with a registered function name (including plugins) is treated as an "implicit get".

1<!-- this is an impliciet get -->
2<h1>${ page.title, "Default Title" }</h1>
3
4<!-- this is a explicit get -->
5<h2>${ get page.title, "Default Title" }</h2>

Example:

1<a href='${ link.href }' ht-apply>${ link.label, link.title, "Placeholder" }</a>