Frontastic for developers

We build the ordinary so you can build the incredible.

Documentation

Frontastic component schemas

A Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. schema defines which data is collected for the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. from the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. and the API hubAPI hub - The API hub combines our code, your code, and APIs to create the backend of a commerce site. Any backend development or extensions are done here. Known as `Catwalk` in code.. This data is then made available to the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. automatically through the data prop of the React part of the Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code..

The authoritative instance for Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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": "<customer>/<project>/tasticIdentifier",
      "name": "Readable name in Frontastic studio",
      "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 there. The name is also important because this is what the user sees in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `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 Frontastic component editorcomponent editor - An interface (usually a panel) where you can adjust the different display settings of your Frontastic component, for example, an image, a title, and so on. panel in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.). For simple Frontastic componentsFrontastic components - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., a single schema object works fine.

{
    // ...
    "schema": [
        {
            "name": "First section in Frontastic studio",
            "fields": [
                {
                    "label": "Label in Frontastic studio",
                    "field": "identifierUsedToAccessFieldInDataProp",
                    "type": "string"
                },
                // ...
            ]
        },
        {
            "name": "Second section in Frontastic studio",
            "fields": [
                {
                    "label": "Label for field in Frontastic studio",
                    "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 the studio. 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 section headline in the component editorcomponent editor - An interface (usually a panel) where you can adjust the different display settings of your Frontastic component, for example, an image, a title, and so on. panel) 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 Frontastic studio",
                    "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 Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. 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 the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. string is the most simple one. You'll find a reference for 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 the studio:

  • translatable: Determines if the field value should be available in different languages (see Internationalization article for more information. The default of this setting depends on the field type (see below).
  • required (default: false): If the setting is mandatory in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.. You'll still need to check if the value is set in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. code because it might not be loaded yet (asynchronous) or the user in the studio ignored the warning about a mandatory setting (for example, to store a draft).
  • default (default null): Define a custom default value you want to receive when the config is left empty in the studio.

Simple field types

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

Boolean

Default: translatable = false
Description: A simple switch that returns true or false.
Code example:

//...
    "fields": [
        {
            "label": "Whole tile clickable",
            "field": "isClickable",
            "type": "boolean",
            "default": false
        },
    ]
//...

Example of how it looks in the Frontastic studio:

String/Text

Default: translatable = true
Description: string renders a 1-line input, while text is a multi-line input field.
Code example for text:

//...
    "fields": [
        {
            "label": "Teaser Text",
            "field": "teaserText",
            "type": "text",
            "default": null
        },
    ]
//...

Example of how it looks in the Frontastic studio:

Code example for string:

//...
    "fields": [
        {
            "label": "Label",
            "field": "label",
            "type": "string"
        },
    ]
//...

Example of how it looks in the Frontastic studio:

Markdown

Default: translatable = true
Description: Allows the user to write simply formatted text using Markdown (see our using the markdown editor article for more information). You'll receive the raw Markdown string and can render it in your component using paas/catwalk/src/js/component/markdown.jsx.
Code example:

//...
    "fields": [
        {
            "label": "Content",
            "field": "text",
            "type": "markdown",
            "default": "* Enter\n* some\n* Markdown",
            "translatable": true
        },
    ]
//...

Example of how it looks in the Frontastic studio:

Number/Integer/Decimal

Default: translatable = false
Description: Lets the user input a numeric value.
Code example:

//...
    "fields": [
        {
            "label": "Space in px (Overrides Size field)",
            "field": "spaceInPx",
            "type": "integer",
            "default": ""
        }
    ]
//...

Example of how it looks in the Frontastic studio:

Enum

Default: translatable = false
Description: Presents a select box to pick a single value from it. The name of an enum value is displayed in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. while you receive the value part in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. code.
Code example:

// ...
    "fields": [
        {
            "label": "Size",
            "field": "size",
            "type": "enum",
            "required": false,
            "values": [
                {
                    "value": "xxs",
                    "name": "Extra Extra Small (4px)"
                },
                {
                    "value": "xs",
                    "name": "Extra Small (8px)"
                },
                {
                    "value": "sm",
                    "name": "Small (12px)"
                },
                {
                    "value": "md",
                    "name": "Medium (16px)"
                },
                {
                    "value": "lg",
                    "name": "Large (20px)"
                },
                {
                    "value": "xl",
                    "name": "Extra Large (24px)"
                }
            ],
            "default": "xl"
        },
//...

Example of how it looks in the Frontastic studio:

Media

Default: translatable = false
Description: Lets the user select an image from the Frontastic media library 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:
Code example:

// ...
    {
        "name": "Image",
        "helpText": "Customize your image",
        "fields": [
            {
                "label": "Image",
                "field": "image",
                "translatable": false,
                "type": "media",
                "required": true
            }
        ]
    },
//...

Example of how it looks in the Frontastic studio:

You can also add options for the crops if you want to, like:

//...
        "options": {
            "ratio": "16:9"
        }
//...

See the Image usage article for more info.

Node

Default: translatable = false
Description: Lets the user select a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. from the page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. tree in the site buildersite builder - An interface that you work with to build your commerce site. Previously known as `stage`. and returns the corresponding page folder ID. You can use the paas/catwalk/src/js/app/nodeLink.jsx component to render a link to the corresponding page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code..
Code example:

//...
    {
        "label": "Node",
        "field": "node",
        "translatable": false,
        "required": false,
        "type": "node",
        "default": null
    },
//...

Example of how it looks in the Frontastic studio:

Reference

Default: translatable = false
Description: A reference can either be a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. (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 Working with links.
Code example:

//...
    {
        "label": "Link",
        "field": "reference",
        "translatable": false,
        "required": false,
        "type": "reference",
        "default": null
    },
//...

Example of how it looks in the Frontastic studio:

Tree

Default: translatable = false
Description: The user can select a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. in the site buildersite builder - An interface that you work with to build your commerce site. Previously known as `stage`. and you'll receive the entire sub-tree of page folderspage folders - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. that starts there. This is especially handy if you want to render a navigation.
Code example:

//...
    {
        "label": "Navigation Tree",
        "field": "tree",
        "type": "tree"
    },
//...

Example of how it looks in the Frontastic studio:

JSON

Default translatable = false
Description: 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.
Code example:

//...                
    {
        "label": "Teaser Json",
        "field": "teaserJson",
        "type": "json", 
        "default": null
    }
//...

Example of how it looks in the Frontastic studio:

Data source fields

The field type stream is special in the sense that you won't receive the user entered configuration, but the result from a data source query. For example, if you select the streamType: product-list, the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. user will be able to filter products from the commerce backend by various criteria. In your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., you'll simply receive the products that are returned by this query.

Every field of type stream needs a streamType parameter:

//...
    {
        "name": "Stream selection",
        "fields": [
            {
                "label": "title",
                "field": "title",
                "type": "string",
                "default": ""
            },
            {
                "label": "Description",
                "field": "description",
                "type": "string",
                "default": ""
            },
            {
                "label": "Data source",
                "field": "data source",
                "type": "stream",
                "streamType": "product-list",
                "default": null
            }
        ]
    },
//...

Example of how it looks in the Frontastic studio:

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 that don't allow the user in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. to provide configuration but which you can nevertheless use to retrieve data on specific dynamic pagesdynamic pages - A type of page that creates the default layout of pages that use the same structure but with different data, for example, a Product Details Page, wishlist, cart, search, and so on. Previously known as `master pages`.:

  • account-addresses: A list of the consumer's stored addresses
  • account-orders: A list of the consumer's 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 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 user in the studio 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": "Image in the slider",
          "field": "selectedImage",
          "type": "group",
          "min": 1,
          "max": 5,
          "fields": [
            {
              "label": "Image",
              "field": "image",
              "type": "media"
            }
        },
        // ...
      ]
    },
  ]
}

This schema creates a group of media fields. The user in the studio can add a number of media items (at least 1, up to 5, min/max are optional) in the group and as the value, you receive an array of these elements in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code., for example:

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

To allow the user to provide a page folderpage folder - A way of structuring the pages within a project and forms the URL structure – they can contain sub-folders. Known as `node` in code. 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": "Page folder link",
                    "field": "pageFolderLink",
                    "type": "node"
                        }
                    ]
                },
                // ...
            ]
        },
    ]
}

The corresponding structure in your Frontastic componentFrontastic component - A customizable building block that's used together with other components to create a commerce site. Known as `tastic` for short in code. code will be:

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

Let's look at an example:

//...
    {
        "name": "Shipping countries",
        "fields": [
            {
                "label": "Countries",
                "field": "countries",
                "type": "group",
                "itemLabelField": "name",
                "fields": [
                    {
                        "label": "Name",
                        "field": "name",
                        "translatable": false,
                        "required": true,
                        "type": "string"
                    },
                    {
                        "label": "Code",
                        "field": "code",
                        "translatable": false,
                        "required": true,
                        "type": "string"
                    }
                ],
                "default": [
                    {
                        "name": "Germany",
                        "code": "DE"
                    },
                    {
                        "name": "United States of America",
                        "code": "US"
                    }
                ]
            }
        ]
    },
//...

And how that would look in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.:

Help text

You can provide additional information to your users in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`. by using the field types description and image. In contrast to normal fields, these don't expect the label and field properties, but only type plus their specific value properties. As there's:

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

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

Let's look at a description example:

//...
    "name": "Menu",
    "fields": [
        {
            "type": "description",
            "text": "Choose a few top categories to be displayed on top of the navigation. Selecting a top category will allow the consumer to navigate to its tree."
        },
//...

And how it looks in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.:

You can also use helpText which displays at the top of the section and appears on hover:

//...        
    {
        "name": "Image",
        "helpText": "Customize your image",
        "fields: [
        //...
    }
//...

Example of how it looks in the Frontastic studioFrontastic studio - The interface you use to manage, build, and edit all areas of your project and commerce sites. Previously known as `backstage`.:

Updated 4 months ago


Frontastic component schemas


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.