ht-param attribute

`ht-param` attribute reference

Overview

The ht-param attribute replaces the target element with text or HTML content from template data.

Example

This example shows the ht-param attribute being used to template a <p> element.

example.html

1<p>Hello, <param ht-param='page.title,site.title' /> world! 👋</p>

This template will cause the <param> element to be replaced with the value of the template data page.title or site.title property. If no template data value is found, the <param> element is simply removed.

Example output example.html

Let's see what happens when we process this template with the following sample template data.

1{
2    site: {
3        title: "HyperTemplates"
4    }
5}

Notice that this example template data object does have a site.title property, but does not have a page.title property. The <param> element will be replaced by the value of site.title, as shown here:

1<p>Hello, HyperTemplates world! 👋</p>

If no matching value was found, the <param> element would simply be removed, as shown below:

1<p>Hello, world! 👋</p>

In cases where a fallback or default value is desired, a data-default or default attribute value may be provided.

example.html

1<p>Hello, <param ht-param='page.foo' default='Documentation' /> world! 👋</p>

This template will attempt to replace the <param> element with the value of the template data site.nope property. If no template data value if found, the <param> element is replaced with the default value.

Example output example.html

Let's see what happens when we process this template with the following sample template data.

1{
2    page: {
3        title: "ht-param",
4        description: "ht-param attribute reference"
5    }
6}

Notice that this example template data object does have a page.title and page.description property, but it does not not have a page.foo property. The result is that the <param> element will be replaced by the default value of Documentation.

1<p>Hello, Documentation world! 👋</p>

Specification

Supported elements

The ht-param attribute can be used with any HTML element. The ht-param attribute is best used with void elements, simply because they do not require closing tags and thus improve template brevity.

1<param ht-param='page.title' />

A brief aside about the HTML <param> element

Why are we using the deprecated HTML <param> element in these examples, when HyperTemplates layouts are supposed to be valid HTML5 documents? Because we prefer to use the ht-param attribute with Void elements, and the only void element that isn't actively in use is the <param> element. And we like how it looks in our templates. 🤓 But the most important reason is because HyperTemplates will always remove or replace elements with ht-param attributes, so we'll never see them in rendered HTML.

NOTE: although the ht-param attribute can be added to any HTML element, ht-param elements cannot be nested inside of elements that only support Text nodes, such as the <title> element. Most HTML parsers – including the net/html standard library used by HyperTemplates – will ignore tags within elements that can only contain text, effectively treating them as plain text.

For templating elements that contain only text (e.g. the <title> element), please see the ht-content reference.

Attribute syntax

The ht-param attribute provides content templating instructions, expressed as a single format:value pair, where value is a comma-separated list of dot-notation style references to one or more template data properties.

1<param ht-param='markdown:page.summary,page.content' />

See content formats for more information.

Default values

The ht-param attribute will only insert content if the specified template data property is found. In cases where no value is found, the associated element is simply removed.

In scenarios where a default or fallback value is desired, add a data-default or default attribute.

1<h1><param ht-param='page.title' default='Placeholder Title' /></h1>

In this example, if the template data page.title property does not exist, HyperTemplates will replace the <param> element with the default value of Placeholder Title.

Content formats

The ht-param attribute can optionally specify the format of the data to be inserted into the layout. The supported formats are text, html, and markdown. If no format is specified, the content is treated as plain text and inserted as a Text node.

1<article>
2    <!-- Insert article metadata here -->
3    <param ht-param='markdown:page.content' />
4</article>

In this example, markdown:page.content configures HyperTemplates to parse the value of page.content as Markdown. The rendered Markdown (i.e. Element nodes) are then inserted as a replacement for the <param> element.

NOTE: Unsupported formats are ignored, effectively resulting in the default behavior (plain text format).