Namespaces

Namespaces reference

Overview

A namespace is a globally accessible template data object.

Namespaces are created by adding data files to the website data directory (see site.config.data_dir). Custom data namespaces are accessible to layouts via their namespace identifier (i.e. data.<identifier>).

Examples

Namespaces are a useful tool for content that we might need to access across multiple pages. Instead of overloading our website configuration file with custom properties, we can split global website content out into discrete namespaces data files.

1---
2title: 💬 Join the community
3description: |
4    Stay up-to-date with the latest releases and other news from Team HyperTemplates. 
5    Ask the developers questions, get help from the community, and share your creations! 🎨    
6form:
7    action: https://hypertexting.community/signup

In this example we have created a newsletter namespace that is accessible from layouts as the data.newsletter property, with data.newsletter.title, data.newsletter.description, and data.newsletter.form.action properties.

Specification

Namespace data files

A namespace is created by adding data files to the site.config.data_dir directory.

The supported data file formats and extensions are:

• YAML (.yaml, .yml)
• JSON (.json)
• OPML (.opml)
• Javascript (.js)

Files with unsupported file extensions are ignored.

Namespace identifiers

The namespace identifier is the template data key used to access namespace data.

A data file's namespace identifier is derived from its pathname under the site.config.data_dir, sans file extension. Each path segment becomes a keypath segment, so subdirectories can be used to nest namespaces. Namespace data file path segments can use letters, numbers, and underscores (^[A-Za-z_][A-Za-z0-9_-]*$). Segments with whitespace or any other illegal character will result in build errors.

Examples

• <data_dir>/newsletter.yaml (accessible via data.newsletter)
• <data_dir>/social/twitter.yaml (accessible via data.social.twitter)

Nested Namespaces

Namespaces can be nested by organizing namespace data files into subdirectories of the site.config.data_dir directory. See namespace identifiers for more information.

Computed Namespaces

Computed namespaces provide support for generated template data using plugins. Computed namespaces are processed after static namespace data files are loaded, so they have access to the full build context, including: ht.*, build.*, env.*, data.*, theme.*, and site.* template data (including the full site.pages sitemap).

Computed Namespace Plugins

Computed namespaces are created using HyperTemplates plugins. To create a computed namespace plugin, add a Javascript file to your site.config.data_dir or theme.config.data_dir directory.

Example

Let's say we want to add a tag cloud to a website. We can use a computed namespace to generate template data at data.tags that we can then render with layout templates.

 1const logger = console.logger("tags.js");
 2export default function tagcloud() {
 3    var result = {}
 4    for (let page of site.pages) {
 5        let tags = page.tags || []
 6        logger.log(`${ page.path } has ${ tags.length } tags`)
 7        for (let tag of tags) {
 8            let id = tag.toLowerCase();
 9            result[id] = (result[id] || { label: tag, count: 0 })
10            result[id].count += 1
11        }
12    }
13    return result
14};

Use the hyperctl cms data inspect command to view the generated template data:

 1$ hyperctl cms data inspect data.tags | jq .
 2{
 3  "html": {
 4    "count": 3,
 5    "label": "HTML"
 6  },
 7  "htmx": {
 8    "count": 1,
 9    "label": "htmx"
10  },
11  "hypermedia": {
12    "count": 1,
13    "label": "HyperMedia"
14  },
15  "javascript": {
16    "count": 1,
17    "label": "javascript"
18  },
19  "markdown": {
20    "count": 1,
21    "label": "markdown"
22  },
23  "nowreading": {
24    "count": 1,
25    "label": "NowReading"
26  },
27  "rss": {
28    "count": 4,
29    "label": "RSS"
30  },
31  "wwdc": {
32    "count": 1,
33    "label": "WWDC"
34  }
35}