Tastic Schemas

A Tastic schema defines which data is collected for the Tastic from Backstage and the Catwalk back-end. This data is then made available to to the Tastic automatically through the data prop of the Tastics react component.

To learn more about this mechanism, please refer to the Tastic Tutorial.

The authoritive instance for Tastic schemas is the JSON schema found in paas/libraries/common/src/json/tasticSchema.json. You can use this schema for validation and auto-completion in your IDE.

Structure

The basic structure of a schema is as follows:

{
    "tasticType": "vendor/project/tasticIdentifier",
    "name": "Readable Name in Backstage",
    "icon": "wrap_text",
    "schema": [
        {
            // ...
        }
    ]
}

The tasticType is most important here, since it connects the schema to the React component using the tastics.js in your project. It must be identical to the mapping defined in there. The name is also important because this is what non-technical users see in Backstage. The icon can be used to define a speaking icon from Material Icons.

schema section

The schema section is an array of configuration sections (realized as tabs in Backstage). For simple Tastics, a single schema object works fine.

{
    // ...
    "schema": [
        {
            "name": "First Tab in Backstage",
            "fields": [
                {
                    "label": "Label in Backstage",
                    "field": "identifierUsedToAccessFieldInDataProp",
                    "type": "string"
                },
                // ...
            ]
        },
        {
            "name": "Second Tab in Backstage",
            "fields": [
                {
                    "label": "Label for Field in Backstage",
                    "field": "fieldIdentifierMustBeUnique",
                    "type": "string"
                },
                // ...
            ]
        }
    ]
}

You can move around fields between these sections as you like, because the resulting data property will be flat (without the sections). They are only for visualization purposes in Backstage. That also means that every field identifier (see below) must be unique across the whole schema. Only excption are fields that are parts of a group (also see below).

Each schema section has a name (the tab headline in Backstage) and a number of fields.

Fields

Each object in fields consist of a similar structure which can slightly differ depending on the type of the field:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    // Required field properties
                    "label": "Label in Backstage",
                    "field": "identifierUsedToAccessFieldInDataProp",
                    "type": "string",
                    // Optional field properties
                    "translatable": false,
                    "required": true,
                    "default": "Hello!"
                },
                // ...
            ]
        },
    ]
}

Each field has a label which is displayed to the user as the prompt to insert some information. The property field determines how you can access this field in your Tastic code later. So, for this example you would use props.data.identifierUsedToAccessFieldInDataProp. (Remember that field identifiers must be unique across a schema!)

The type determines what kind of information should be input by the user in Backstage. string is the most simple one. Find a reference about all supported types and their options below.

The remaining properties of a field are optional and help you to configure the behavior of the field in Backstage:

  • translatable: Determines if the field value should be available in different languages (see I18N Tutorial. Default of this setting depends on the field type (see below).
  • required (default: false): If the setting is mandatory in Backstage. Note that you still need to check if the value is set in your Tastic code, because a) it might not be loaded yes (asynchronous) or b) the user in Backstage ignored the warning about a mandatory setting (e.g. to store a draft).
  • default (default null): Define a custom default value you want to receive when the config is left empty in Backstage.

Simple Field Types

There are a number of simple field types which are supported by Frontastic to allow different configuration inputs. The more complex types stream, group, tastic and custom are explained dedicatedly further below.

boolean

As simple switch returning true or false.

Default translatable = false

string / text

Let the user enter a simple text. string renders a 1-line input, while text makes it a multi-line input field.

Default translatable = true!

markdown

Allows the user to write simply fromatted text using Markdown. You will receive the raw markdown string and can render it in your component using paas/catwalk/src/js/component/markdown.jsx.

Default translatable = true

number / integer / decimal

Let the user input a numeric value.

Default translatable = false

enum

Present a select box to the user and let them pick a single value from it. Options are defined as:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "label": "Select One",
                    "field": "selectedValue",
                    "type": "enum",
                    "values": [
                        { "value": 1, "name": "First Selection" },
                        { "value": 2, "name": "Second Selection" },
                    ]
                },
                // ...
            ]
        },
    ]
}

The name of an enum value is displayed in Backstage while you receive the value part in your Tastic code.

Default translatable = false

media

Lets the user select an image from the Frontastic Media app and configure some additional settings such as an alt text, crop ratio and where the crop anchor should bbe in the image.

You can influence if the user can select a ratio or pre-define a fixed value using:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "label": "Image from the Galery",
                    "field": "selectedImage",
                    "type": "media",
                    "options": {
                        "ratio": "16:9",
                    }
                },
                // ...
            ]
        },
    ]
}

For how to render such media images properly, please refer to Media Handling.

Default translatable = false

node

This field lets the user select a Node from the Node Tree in the Stage app and returns the corresponding Node ID for you. You can use the paas/catwalk/src/js/app/nodeLink.jsx component to render a link to the corresponding Node.

Default translatable = false

reference

A reference can either be a Node (like from the node type) or an external link URL. If you want to give the user the choice, use this type. You can use the paas/catwalk/src/js/component/reference.jsx component to render the value of this type directly.

Default translatable = false

tree

For a tree, the user can select a node in the Stage app and you will receive the entire sub-tree of nodes that starts there. This is especially handy if you want to render a navigation.

json

This field type is meant for copy & paste of complex information (e.g. exports from other systems). You can ask users to paste some JSON and will receive it automatically parsed to an object

This field type is meant for copy & paste of complex information (e.g. exports from other systems). You can ask users to paste some JSON and will receive it automatically parsed to an object..

Default translatable = false

Stream Fields

The field type stream is special in the sense that you will not receive the user entered configuration, but the result from a stream query. For example, if you select the streamType product-list, the Backstage user will be able to filter products from the commerce backend by various criteria. In your Tastic you will simply receive the products that are returned by this query.

Every field of type stream needs a streamType parameter:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "label": "Trendy Products",
                    "field": "trendyProductList",
                    "type": "stream",
                    "streamType": "product-list"
                },
                // ...
            ]
        },
    ]
}

Possible values for streamType are:

  • product-list: A list of products
  • product: A single product
  • content-list: A list of content objects
  • content: A single content object

In addition, there are streams which do not allow the Backstage user to provide configuration but which you can nevertheless use to retrieve data:

  • account-addresses: A list of the consumers stored addresses
  • account-orders: A list of the consumers orders in the commerce backend
  • account-wishlists: All wishlists the consumer has in the backend

Complex input using group

In some cases, just a single input is not enough. Then you typically do not want to have multiple fields like image1, image2, image3 but use a field of type group to let the user in Backstage create a flexible number of group elemnts as values for the field. The elements of a group can contain any number of fields again (even nested group fields, although this is not recommended!). The basic configuration of a group looks like this:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "label": "Images in the Slider",
                    "field": "sliderImages",
                    "type": "group",
                    "min": 1,
                    "max": 5,
                    "fields": [
                        {
                            "label": "Image"
                            "field": "image",
                            "type": "media"
                        }
                    ]
                },
                // ...
            ]
        },
    ]
}

This schema creates a group of media fields. The user in Backstage can add add a number of media items (at least 1, up to 5, min/max are optional) in the group and as the value you simple receive an array of these elemens in your Tastic, for example:

this.props.data.sliderImages = [
    {
        "image": '// ...',
    },
    {
        "image": '// ...',
    },
    // ...
]

To allow the user to provide a Node and some text in addition to the image you can craft your schema like this:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "label": "Images in the Slider",
                    "field": "sliderImages",
                    "type": "group",
                    "fields": [
                        {
                            "label": "Image"
                            "field": "image",
                            "type": "media"
                        },
                        {
                            "label": "Teaser Text"
                            "field": "teaserText",
                            "type": "string"
                        },
                        {
                            "label": "Node Link"
                            "field": "nodeLink",
                            "type": "node"
                        }
                    ]
                },
                // ...
            ]
        },
    ]
}

The corresponding structure in your Tastic code will be:

this.props.data.sliderImages = [
    {
        "image": '// ...',
        "teaserText": '...',
        "nodeLink": '123abc'
    },
    {
        "image": '// ...',
        "teaserText": '...',
        "nodeLink": '424242'
    },
    // ...
]

Help Text with description and image

You can provide additional information to the user in Backstage using the field types description and image. In contrast to normal fields, those do not expect the label and field properties, but only type + their specific value properties. As there is:

{
    // ...
    "schema": [
        {
            // ...
            "fields": [
                {
                    "type": "description",
                    "text": "I will be displayed in Backstage as help."
                },
                {
                    "type": "image",
                    "url": "https://example.com/some/image.png"
                },
                // ...
            ]
        },
    ]
}

Images can, for example, be hosted in your Catwalk project or an external HTTPS secured file hosting.

Tastic Fields

Stability

The tastic field type allows you to ask the user to configure another Tastic is the parameter for your Tastic. This feature is highly experimental. If you want to try it anyway, please take a look at paas/catwalk/src/js/tastic/card/tastic.jsx.

Custom Fields

TODO