Template Data

Overview

Template data is content in key-value pairs used to hydrate a layout template. Template data is generally managed as content files in Markdown, YAML, or JSON format.

Example

This example shows the an approximation of a template data object.

 1{
 2    created_at: "2025-01-27T17:00:00-08:00",
 3    updated_at: "2025-01-27T17:00:00-08:00",
 4    title: "Template Data",
 5    description: "HyperTemplates generates template data from content files",
 6    author: {
 7        name: "Jane Doe",
 8        href: "https://janedoe.com",
 9    },
10    content: "## Overview\n\nLorem ipsum, hipsters get some."
11}

Template attributes reference template data using "dot notation" property accessors. The name of the property being accessed is the template data key, and the value of the property being accessed is the template data value.

In this sample, title and author.name are valid template data keys (property names), and their corresponding template data values (property values) are Template Data and Jane Doe.

Example template data source files

The example template data provided above could be managed via any one of the following source files in Markdown, YAML, or JSON format. The following example content files will generate identical template data.

index.md 
 1---
 2created_at: 2025-01-27T17:00:00-08:00
 3updated_at: 2025-01-27T17:00:00-08:00
 4title: Template Data
 5description: HyperTemplates generates template data from content files
 6author:
 7    name: Jane Doe
 8    href: https://janedoe.com
 9---
10
11## Overview
12
13Lorem ipsum, hipsters get some.
index.yaml 
 1created_at: "2025-01-27T17:00:00-08:00"
 2updated_at: "2025-01-27T17:00:00-08:00"
 3title: Template Data
 4description: HyperTemplates generates template data from content files
 5author:
 6    name: Jane Doe
 7    href: https://janedoe.com
 8content: |
 9    ## Overview
10
11    Lorem ipsum, hipsters get some.
index.json 
 1{
 2    "created_at": "2025-01-27T17:00:00-08:00",
 3    "updated_at": "2025-01-27T17:00:00-08:00",
 4    "title": "Template Data",
 5    "description": "HyperTemplates generates template data from content files",
 6    "author": {
 7        "name": "Jane Doe",
 8        "href": "https://janedoe.com"
 9    },
10    "content": "## Overview\n\nLorem ipsum, hipsters get some."
11}

Specification

Template data object

The HyperTemplates rendering system always expects a single template data input to hydrate a layout with. This singular input is referred to as the "template data object". Template data objects do not have required fields. The only structural requirement for template data is that template data keys must be strings.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: "favicon.png",
 5    },
 6    page: {
 7        created_at: "2025-01-27T17:00:00-08:00",
 8        layout: "default.html",
 9        title: "Hello, world",
10        content: "Lorem ipsum, hipsters get some.",
11    },
12}

This is an approximation of a template data object.

NOTE: Applications built with HyperTemplates — such as the HyperTemplates CLI – may combine template data from multiple sources into a single template data object before processing. For example, the HyperTemplates CLI hyperctl build command combines data from a website configuration file with individual page content into a single template data object. The resulting template data object maps the website configuration template data to the site key, and page template data to the page key, similar to the sample shown above.

Template data sources

The HyperTemplates CLI and libraries have built-in support for parsing template data from files in Markdown, YAML, and JSON formats. In some cases, multiple data sources are combined into a single template data object. Template data sources may still be considered valid if "empty".

Markdown

Coming soon...

YAML

Coming soon...

JSON

Coming soon...

Layout data

Additional layout-scoped data can be added to any layout or other layout fragment as <meta> elements.

1<meta name='layout:name' content='default'>
2<meta name='layout:copyright' content='Herd Works Inc'>
3<meta name='layout:copyyear' content='2024'>

NOTE: completely empty JSON files (containing zero bytes) may cause JSON parsing errors in some implementations, so a JSON format template data source would be considered empty (and still valid) as long as they contain opening and closing curly braces (i.e. {}).

Template data keys

Template data keys are "dot notation" property accessors to properties in a template data object. The name of the property being accessed is the template data key.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: {
 5            href: "favicon.png",
 6            sizes: "128x128",
 7        },
 8    },
 9    page: {
10        created_at: "2025-01-27T17:00:00-08:00",
11        layout: "default.html",
12        title: "Hello, world",
13        content: "Lorem ipsum, hipsters get some.",
14    },
15}

In this example, there are 8 template data keys: site, site.title, site.favicon, site.favicon.href, site.favicon.sizes, page, page.created_at, page.layout, page.title, and page.content.

NOTE: template data objects are not vanilla Javascript objects, so template data keys may reference properties that do not exist (what would be considered "undefined" objects in Javascript parlance) without penalty. For example, in the sample above, the template data key site.foo.bar would simply result in a null value rather than an error due to site.foo being "undefined".

Template data values

Template data values are values of properties being accessed in a template data object.

 1{
 2    site: {
 3        title: "ACME Inc.",
 4        favicon: "favicon.png",
 5    },
 6    page: {
 7        created_at: "2025-01-27T17:00:00-08:00",
 8        layout: "default.html",
 9        title: "Hello, world",
10        content: "Lorem ipsum, hipsters get some.",
11    },
12}

In this example, the template data value for the key page.title is Hello, world.

Join the community

Stay up to date with the lastest releases and other news from the HyperTemplates community.