Templates

Overview

The platform will generate templates (using nunjucks, which allows for functionality such as shared base templates) and save them to the database. The templates will include HTML tags such as <platform-component package-name="..." name="..." some-data="..."></platform-component> where Platform Components need to be loaded.

Link clicks are intercepted and trigger the routing:navigate:v1 event on the eventbus instead of navigating.

Rendering

Templates are fetched using the API by name, and rendered using a Template Platform Component:

// React
<PlatformComponent packageName="platform-core" name="Template" templateName="my-name" />

// Platform Templates
<platform-component package-name="platform-core" name="Template" template-name="my-name"></platform-component>

The template is rendered using nunjucks - including fetching any necessary base templates by name using the API. Platform (<platform-eventbus-scope>...</platform-eventbus-scope> or <platform-component package-name="..." name="..."></platform-component>) and breeze-ui tags can be used in the templates.

This could be used, for example, to render a page full of Platform Components with a custom layout.

Implementation

Template Component

The Template Platform Component takes a template-name, which it fetches and renders. Any additional props passed to the component are included in the nunjucks context as template variables. For example:

<platform-component package-name="platform-core" name="Template" template-name="my-template" uid="123"></platform-component>

// my-template:
<div>UID is {{ uid }}</div>

useTemplate

useTemplate (exported from @skedulo/platform-react) does the heavy lifting for Template component:

const { loading, error, result } = useTemplate({
  templateName: templateName,
  context: props,
})

// Alternatively pass a template instead of a name:
const { loading, error, result } = useTemplate({
  template: `<div>This is a template</div>`,
  context: props,
})

useTemplate performs the following actions:

1. Create a nunjucks environment for the provided template name or template: this nunjucks environment has a loader that requests templates from the API (the initial template, and any extended or included templates).
2. Uses the environment and provided context to asynchronously render the template. This has to be asynchronous because templates may need to be fetched from the API.
3. The rendered template is passed into parsePlatformTemplate which uses html-react-parser to convert the HTML to react whilst intercepting any platform-component or platform-eventbus-scope elements and replacing them with the PlatformComponent and PlatformEventbusScope components from platform-react.

nunjucks

As well as using a loader that uses the API to request templates, the nunjucks environment has custom filters added such as date and number formatting.