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.
Please see here for full documentation: https://developer.openactive.io/publishing-data/dataset-sites
There are two templates available, depending on your use case.
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).
- 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/
.
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.
- Host the CSP compatible template static assets somewhere on the same domain as your dataset site.
- 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 ofdatasetsite-csp.static.zip
. The value of "staticAssetsPathUrl
" can be a relative or absolute URL, and must not include a trailing slash (/). - Output the template at an endpoint, for example
https://example.com/openactive/
.
$ npm install @openactive/dataset-site-template
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);
});
$ npx @openactive/dataset-site-template@latest example.jsonld output.html
See Usage for CLI
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.
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.
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');
});
Extracts the CSP static asset files (contents of datasetsite-csp.static.zip) to the specified directory. Useful for build scripts.
const { unzipAssetsArchiveToDirectory } = require('@openactive/dataset-site-template');
/* Output OpenActive Dataset Site Template CSP compatible static assets */
await unzipAssetsArchiveToDirectory('./assets/static/datasetsite');
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.
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:
$ 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:
$ 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:
$ npx @openactive/dataset-site-template@15.0.0 example.jsonld index.html . .
Full usage instructions:
Usage:
npx @openactive/dataset-site-template@<version> <inputJsonFile> <outputHtmlFile> [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@<version> --raw <outputDirectory>
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
Please note that there are various libraries available that do all of the below automatically.
- 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:
Downloads for CSP compatible template:
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:
- 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
<script type="application/ld+json">
tag within the generated HTML - view the source of this page to see an example.
- This is important as it is used to populate the machine-readable
- If using static hosted files, set the
"staticAssetsPathUrl"
property at the root of the JSON to the URL path of the directory containing the CSP static asset files (contents ofdatasetsite-csp.static.zip
). This can be a relative or absolute URL, and must not include a trailing slash (/). Note this must take place after Step 1 so that this property is not included in the machine-readable JSON-LD. - Use the resulting JSON with the mustache template to render the dataset site.
PLEASE NOTE: This is only an example to demonstrate the logic and is not intended for production use. The mustache template must be copied locally and rendered server-side for production use, for security (to prevent XSS attacks), and as its primary purposes are SEO and machine readability.
This sample contains a prototype of the logic above written in JavaScript.
Contributions to this project are welcome.
The datasetsite.mustache.template
and datasetsite.styles.css
files are used to create the two different templates available for download.
When making changes, to preview the template files simply run npm install
and then npm run build
. This script is also run by CI on master
, and the resulting templates automatically deployed to GitHub Pages and NPM.
When developing the templates npm run watch
can be used to run a live test harness to preview changes in real-time.
All changes that impact the output dataset site templates or static assets MUST trigger a major version bump (both for security, and for the static asset version matching mechanism). The CI of downstream libraries will then automatically pick up these changes.
Minor and patch version numbers may be used to update any functionality of the npm library that impacts direct users of that library, but does not impact the templates or static assets themselves.
NOTE: All commits to master currently trigger a major version bump in CI by default.