Skip to content

Presentation Template Specification

Data in Project Catalyst is divided into:

  • Form captured data, which is controlled and validated by FormTemplates; and
  • Dynamic System Data, which is derived by the system based on activity or on-chain information.

There needs to be a way to present this data in a meaningful, cross platform, structured approach.

This is achieved with this Presentation Template.

Each Presentation Template defines a presentation for a particular Card of information. The UI composes its display based on these cards, which allow for both static content and dynamic content defined within the system to be merged and presented.

This helps divide the system by intent, data capture/generation and presentation.

Presentation Templates DO NOT capture user flows. They ONLY define how data could be displayed by combining source for a particular purpose. The purpose is derived solely by the cards id.

JSON Schema

Presentation Template payloads all follow the same structure, which is defined by JSON Schema version 2020-12.

Schema

The Presentation template schema has the following format.

Presentation Template Schema 
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "maintainers": [
        {
            "name": "Catalyst Team",
            "url": "https://projectcatalyst.io/"
        }
    ],
    "title": "Presentation Template",
    "description": "Presentation Templates define how data extracted from Form Data is to be presented.\nThey provide a way to parameterize the contents of a UI in response to the changing\nneeds of the Forms themselves.",
    "$defs": {
        "cardDescription": {
            "description": "A long form description of the purpose of the card. Not used by the UI.",
            "type": "string"
        },
        "cardName": {
            "description": "A Card has to have one of the well known defined names.\nThese are the primary identifier which is used by the UI to determine\nwhere the UI will place the card.",
            "enum": [
                "draft-proposal-summary",
                "proposal-contest-summary"
            ],
            "type": "string"
        },
        "cardTitle": {
            "description": "A title shown to the editor of the card.  Not used by the UI.",
            "type": "string"
        },
        "css": {
            "contentType": "text/css; charset=utf-8; template=handlebars",
            "description": "Optional styling that can be used by the HTML generated from the template for presentation.",
            "type": "string"
        },
        "layoutParameters": {
            "description": "Parameters which help the front end layout the provided template. To be defined.",
            "type": "object"
        },
        "requiredDocumentTypes": {
            "description": "A list of the document types (UUIDs) the presentation template needs.",
            "items": {
                "format": "uuid",
                "type": "string"
            },
            "type": "array",
            "uniqueItems": true
        },
        "template": {
            "contentType": "text/html; charset=utf-8; template=handlebars",
            "description": "HTML5 defined presentation layout for the card.\nThe data is templated with handlebars, and the data that can be inserted is\nderived from the `requiredDocumentTypes` and available system wide dynamic data.",
            "type": "string"
        }
    },
    "type": "object",
    "properties": {
        "css": {
            "$ref": "#/$defs/cardTemplateCss"
        },
        "description": {
            "$ref": "#/$defs/cardDescription"
        },
        "layout": {
            "$ref": "#/$defs/layoutParameters"
        },
        "name": {
            "$ref": "#/$defs/cardName"
        },
        "requiredDocs": {
            "$ref": "#/$defs/requiredDocumentTypes"
        },
        "template": {
            "$ref": "#/$defs/cardTemplate"
        },
        "title": {
            "$ref": "#/$defs/cardTitle"
        }
    },
    "additionalProperties": false,
    "required": [
        "cardName",
        "requiredDocuments",
        "layoutParameters",
        "template"
    ]
}

"$schema"

This defines that the template is a standard JSON Schema version 2020-12 document. Any document derived from the template is only valid if it validates according to JSON Schema validation rules against the template.

"maintainers"

Is a list of the entities who have made or updated the template. It is optional, but if it is included, it MUST be an array of objects. Each object must have two fields:

  • "name" : The name of the individual maintainer or group responsible for the template.
  • "url" : A link where more information about the maintainer or group can be found. If there is no link, the field is still present, but an empty string ("").

"title"

This is a name for the template. It is not used by consumers of the template, but could be used by template builders to help identify the template.

"description"

This is a long multi line description about the template itself. It is not used by consumers of the template, but could be used by template builders to help identify and define the purpose of the template.

There is expected to be a number of templates used in the system, and both "title" and "description" help template builders organize templates.

"$defs"

Defines the fields within the properties that define the presentation template.

"type": "object"

The Presentation Template is an object type.

"properties"

The "properties" section defines each field that is used to define the Presentation Template.

"additionalProperties": false

This Templates is exhaustively defined. It is not permissible to add fields to a document, that are not present in this schema.

"additionalProperties": false

Example Presentation Template

This Specification is draft, and there are currently no examples.

Presentation Template Cards

Defined Presentation Cards
All Presentation Card Names that may be defined by Presentation Templates.

Draft Proposal Summary

A Summary of a draft proposal.
Card ID draft-proposal-summary
Available Documents

Proposal Contest Summary

A Summary shown when selecting proposals to vote on.
Card ID proposal-contest-summary
Available Documents