Tastic Schema

A Tastic Schema defines which data is collected for the Tastic from Backstage and the Catwalk backend. This data is then made available to the Tastic automatically through the data prop of the Tastics React component.

The authoritative 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 the most important piece here as it connects the Schema to the React component using the tastics.js in your Project and they must be identical to the mapping defined in there. The name is also important because this is what your Frontend Manager sees 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 the Configuration Panel in Backstage). For simple Tastics, a single Schema object works fine.

{
    // ...
    "schema": [
        {
            "name": "First Section in Backstage",
            "fields": [
                {
                    "label": "Label in Backstage",
                    "field": "identifierUsedToAccessFieldInDataProp",
                    "type": "string"
                },
                // ...
            ]
        },
        {
            "name": "Second Section 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're only for visualization purposes in Backstage. That also means that every field identifier (see below) must be unique across the whole Schema. The only exceptions are fields that are part of a group (also see below).

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

Fields

Each object in fields consists 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 Frontend Manager 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 Frontend Manager 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 Internationalization article for more info. 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 Frontend Manager 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 one-line input, while text makes it a multi-line input field.

Default translatable = true

Markdown

Allows the user to write simply formatted text using Markdown. You'll 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

Lets the user input a numeric value.

Default translatable = false

Enum

Presents a select box to the Frontend Manager and lets 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 Frontend Manager 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 be 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 Gallery",
                    "field": "selectedImage",
                    "type": "media",
                    "options": {
                        "ratio": "16:9",
                    }
                },
                // ...
            ]
        },
    ]
}

Default translatable = false

See the Image Usage article for more info.

Node

This field lets the Frontend Manager 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. For more info on this, please see this article.

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 and paste of complex information (for example, 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 won't 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'll simply receive the products that are returned by this query.

Every field of type stream needs a streamType parameter:

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

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 don't allow the Frontend Manager in Backstage to provide configuration but which you can nevertheless use to retrieve data on specific master pages:

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

Complex Input Using Group

In some cases, just a single input isn't enough. Then you typically don't want to have multiple fields like image1, image2, image3 but use a field of type group to let the Frontend Manager in Backstage create a flexible number of group elements as values for the field. The elements of a group can contain any number of fields again. 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 Frontend Manager in Backstage can add add a number of media items (at least one, up to five, min/max are optional) in the group and as the value you simple receive an array of these elements 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 your Frontend Manager in Backstage using the field types description and image. In contrast to normal fields, these don't 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.


‹ Back to Article List

Next Article ›

Example Tastics to Create

Still need help? Contact Us Contact Us