dataset-site-template  

About

This repository contains a mustache template for creating an OpenActive dataset site, similar to those that can be found at https://status.openactive.io.

It is designed to be embedded in a booking system, and easily customised.

Getting started

Please see here for full documentation: https://developer.openactive.io/publishing-data/dataset-sites

How it works

$3

There are two templates available, depending on your use case.

$3

This file contains stylesheets and images embedded in a single file, with fonts loaded via the CDNs of Google Fonts and cdnjs (powered by Cloudflare).

1. Use one of the options below to dynamically render the embedded 'single-file template' and output it at an endpoint, for example https://example.com/openactive/.

$3

This template must be rendered using a reference to a self-hosted stylesheet and assets. This is useful for implementations that have a Content Security Policy (CSP) in place.

1. Host the CSP compatible template static assets somewhere on the same domain as your dataset site.
2. Use one of the options below to dynamically render the 'CSP compatible template' ensuring that the "staticAssetsPathUrl" references the URL path to the directory containing the contents of datasetsite-csp.static.zip. The value of "staticAssetsPathUrl" can be a relative or absolute URL, and must not include a trailing slash (/).
3. Output the template at an endpoint, for example https://example.com/openactive/.

Options for template rendering

$3

``bash
$ npm install @openactive/dataset-site-template
`

`js
const { renderDatasetSite } = require('@openactive/dataset-site-template');

/ Render OpenActive Dataset Site /
app.get('openactive', async (req, res) => {
/* @type {import('@openactive/models-ts').Dataset} /
const jsonld = {...};
return await renderDatasetSite(jsonld);
});
`

See Usage for Node.js

$3


`bash
$ npx @openactive/dataset-site-template@latest example.jsonld output.html
`

See Usage for CLI

$3

There are various libraries available that handle template rendering in a variety of languages.

If a library is not available in your language, consider manual rendering.

npm / Node.js

$3

This function renders the dataset site from a given JSON-LD object, such as example.jsonld.

If staticAssetsPathUrl is provided it will use the CSP compatible template, otherwise it will use the single-file template.

staticAssetsPathUrl is the relative or absolute URL path to the hosted CSP assets (contents of datasetsite-csp.static.zip). staticAssetsPathUrl is relative to the location of the dataset site endpoint.

Note that the JSON-LD should be of type Dataset, which can be validated with the OpenActive Validator and also by the models-ts library.

`js
const { renderDatasetSite } = require('@openactive/dataset-site-template');

/ Render OpenActive Dataset Site via a single file /
app.get('openactive', async (req, res) => {
/* @type {import('@openactive/models-ts').Dataset} /
const jsonld = {...};
return await renderDatasetSite(jsonld);
});

/ Render OpenActive Dataset Site that is CSP compatible /
app.get('openactive', async (req, res) => {
/* @type {import('@openactive/models-ts').Dataset} /
const jsonld = {...};
return await renderDatasetSite(jsonld, '/static/datasetsite');
});
`

$3

Extracts the CSP static asset files (contents of datasetsite-csp.static.zip) to the specified directory. Useful for build scripts.

`js
const { unzipAssetsArchiveToDirectory } = require('@openactive/dataset-site-template');

/ Output OpenActive Dataset Site Template CSP compatible static assets /
await unzipAssetsArchiveToDirectory('./assets/static/datasetsite');
`

$3

This function returns a string containing the raw content of the template file (depending on singleFileMode).

If singleFileMode is false or omitted it will return the content of the CSP compatible template), otherwise it will return the content of the single-file template.




CLI static dataset site generator

Use npx @openactive/dataset-site-template to generate a Dataset Site HTML file that can be statically hosted. This can be useful for single database systems where the contents of the dataset site will not change per-customer.

Node.js version 14 or above must be installed to use this command.

You will need to supply a JSON-LD file, such as example.jsonld, based on your organisation.

Note that the various libraries available are preferred to this approach where possible, as they are easier to iterate with during development, and as the Dataset API Discovery specification is yet to be formally released.

To host a static single-file dataset site, simply run:

`bash
$ npx @openactive/dataset-site-template@latest example.jsonld index.html
`

To host a static CSP compatible dataset site from a single directory, simply run the following in that directory:

`bash
$ npx @openactive/dataset-site-template@latest example.jsonld index.html . .
`

Please note if running the above in CI, it is recommended for stability and security that the version is specified explicitly. For example:
`bash
$ npx @openactive/dataset-site-template@15.0.0 example.jsonld index.html . .
`

Full usage instructions:

`
Usage:
npx @openactive/dataset-site-template@ [staticAssetsPathUrl] [staticAssetsOutputDirectory]

Arguments:
inputJsonFile: Dataset Site JSON file used to generate the Dataset Site HTML
outputHtmlFile: Output Dataset Site HTML file, rendered using the relevant template
staticAssetsPathUrl: Optional.
Relative or absolute URL path to the hosted CSP assets (contents of datasetsite-csp.static.zip), if you are hosting static assets.
If staticAssetsPathUrl is supplied, the CSP compatible template is used, otherwise the single-file template is used.
staticAssetsPathUrl is relative to the hosted location of the outputHtmlFile.
staticAssetsOutputDirectory: Optional. If supplied, output the CSP assets (contents of datasetsite-csp.static.zip) to this directory.

npx @openactive/dataset-site-template@ --raw

Arguments:
outputDirectory: Output both raw mustache template files and the CSP assets archive to this directory

Examples:
npx @openactive/dataset-site-template@latest example.jsonld index.html
npx @openactive/dataset-site-template@latest example.jsonld index.html . .
npx @openactive/dataset-site-template@latest example.jsonld output.html "http://example.com/static" ./static
npx @openactive/dataset-site-template@latest --raw ./templates
`

Manual rendering

> Please note that there are various libraries available that do all of the below automatically.

$3

- NOTE: DO NOT DOWNLOAD THE MUSTACHE FILE LIVE, IT MUST BE SAVED LOCALLY TO PREVENT XSS ATTACKS
- NOTE: DO NOT RENDER THIS FILE CLIENT-SIDE, IT MUST BE RENDERED SERVER-SIDE FOR SEO AND MACHINE READABILITY

Use one of these downloads for rendering the template manually:

Downloads for Single-file template:

- ⬇️ Download single-file template

Downloads for CSP compatible template:

- ⬇️ Download CSP compatible template
- ⬇️ Download CSP compatible static asset files




$3

First construct the JSON-LD found in example.jsonld based on your organisation (for single database systems) or your customers' own properties (for multiple database systems), then process it with the following steps:

1. Stringify the input JSON-LD, and place the contents of the string within the "jsonld" property at the root of the JSON-LD itself.
- This is important as it is used to populate the machine-readable