Using Frontastic components

What's a Frontastic component?

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. needs to be created by a developer and then can be used to build your commerce site. They're the central part of Frontastic.

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. is made up of a definition 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`., the corresponding frontend code, and the required data from an API.

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. always consists of 2 parts:

  1. A JavaScript entry point which is a ReactJS (JSX) component that receives some special props
  2. A JSON file that defines which data 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. requires and how this should be configurable 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`., we call this JSON file the schemaschema - The framework behind a Frontastic component and the fields that are available within the Frontastic studio.

Throughout this article, we'll be referencing a simple 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. that displays a list of products. We'll use the ProductList 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 starter componentsFrontastic starter components - Frontastic components that come with each Frontastic project that can be copied into your own project to use. Known in code as `boost theme`. as the basis but stripped the HTML code down a bit for better illustration. You can copy the following files as a starting point:

  • paas/catwalk/src/js/tastic/productList/schema.json
  • paas/catwalk/src/js/tastic/productList/tastic.jsx

Frontastic component types

There are 3 types of 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.:

  • Static
  • Flexible
  • Connected

Static components are those that you can build with a schema and there are no configurable fields 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 example, a horizontal spacer.

Flexible components are those that have some fields that are configurable 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`., but Frontastic stores the data to publish to your site. For example, a markdown component.

Connected components are those that you connect to a data sourcedata source - The data provided from an API to display products, content, or anything from an integration or extension. A data source filter is created and can be selected for a Frontastic component that will display the data source filter on your commerce site. and are then filtered 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 example, a product slider.

πŸ“˜

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. are called tastics in code for short.

For tips on how to split your commerce site into 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., see our How to slice a commerce site into components article.

File placement

Custom 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. need to be placed in the project directory they belong to. By convention, the path project/src/js/tastic/ holds all custom components. Each 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. requires its own sub-directory which is the camelCased 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. name.

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. schema specification should always be named schema.json for easier lookup.

So if you start with the example from above, have a project named fall2018, and your Customer ID is year, you should copy the files to:

  • year_fall2018/src/js/tastic/productList/schema.json
  • year_fall2018/catwalk/src/js/tastic/productList/productListTastic.jsx

Frontastic component specification

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`. needs to know how 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. requires to be initialized and what parameters it expects to be available. This comes in the form of a JSON file that follows a JSON schema that can be found in:
paas/libraries/common/src/json/tasticSchema.json with the common definitions from paas/libraries/common/src/json/library/common.json.

On the top level, this file contains meta-information about 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.:

{
    "tasticType": "year-productList",
      "name": "Product List",
      "icon": "list",
      "schema": [
        ...
    ]
}

The tasticType defines a name of how 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. can be looked up in code. This must be prefixed by (at least) your customer ID or another unique identifier.

The name provides a readable name, in contrast to that. You should provide an icon for 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. which can be selected from the Material Design Icons. The schema key then contains the parameter list 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.:

{
    ...
    "schema": [
        {
            "name": "Data source selection",
            "fields": [
                {
                    "label": "Data source",
                    "field": "stream",
                    "type": "stream",
                    "streamType": "product-list",
                    "default": null
                },
                ...
                {
                    "label": "Show strike price",
                    "field": "showStrikePrice",
                    "type": "boolean",
                    "default": true
                }
            ]
        }
  ]
}

The schema is presented 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`. as a settings panel. For this reason, structure your schema into meaningful blocks that cover related fields (here, the block is named Data source selection).

Each field specifies one parameter that'll be provided to 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. under the name provided as field. The label is used in the UI in the settings panel (for example, Data source). The type determines what kind of information you require. Frontastic supports typical programming data types like string, integer, or boolean. But also advanced types like node, tree, media, or group. See the Frontastic component schema article for more information.

The latter types provide advanced UI elements 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`. and result in objects to submit the information to 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, a media field provides image selection from the media library, plus settings for cropping, and more.

In the shown case, the Product List 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. requires a stream of type product-list and a boolean flag which determines if strike prices are shown.

πŸ“˜

A stream and a data source are the same things.

The specification for 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. should be stored in the source code repository together with 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. code.

To make 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. known by 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 need to upload the schema file to the Components area in the studio once. In addition, you need to re-upload the specification every time you change the required parameters or any metadata. We'll go through how to do this in the next article.

Frontastic component React code

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. itself is basically a ReactJS component that receives some pre-defined props from 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.. If you're not familiar with ReactJS, components, and props, please refer to the React Component documentation first.

The stub of the tastic.jsx file looks like this:

import React, { Component } from 'react'
import PropTypes from 'prop-types'
import _ from 'lodash'

...

class ProductListTastic extends Component {
    render () {
        // ...
    }
}

ProductListTastic.propTypes = {
    data: PropTypes.object.isRequired,
    tastic: PropTypes.object.isRequired,
}

ProductListTastic.defaultProps = {
}

export default ProductListTastic

While the remaining boilerplate is pretty standard for a React component, the important part here is the ProductListTastic.propTypes declaration.

Every 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. receives the prop tastic which contains all information that is available about 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. itself. This includes the schema.

The data prop contains all collected data 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. required if this data is available yet. You can directly access the values by their name. If your specification schema contains a field campaignProductStream you can access the corresponding stream via this.props.data.campaignProductStream.

How this works can be seen in the following example which reveals the first part of the render() method:

class ProductListTastic extends Component {
    render () {
        let productList = this.props.data.stream
        if (!productList) {
            return null
        }

      let showPercent = this.props.data.showPercent || true
      let showStrikePrice = this.props.data.showStrikePrice || true

      // ...
    }
}

πŸ“˜

You can't be sure that data is filled every time. For example, during an update of data source filters or view change, it might be empty. So, the code needs to take care of resilience and simply returns null if it misses data (no rendering at all). If you can display something meaningful instead, feel free to do that.

For convenience, the 2 other settings (of which we saw one in the specification) are extracted and filled with defaults for resilience. The remaining code in render() is again straightforward React:

class ProductListTastic extends Component {
    render () {
        // ...
    
        return (<div className='o-layout'>
            {_.map(productList.items, (product) => {
                return (<div key={product.productId} className='...'>
                    <Product
                        product={product}
                              showPercent={showPercent}
                              showStrikePrice={showStrikePrice}
                    />
                </div>)
            })}
          </div>)
    }
}

The component wraps all HTML into a div with o-layout class, iterates all items from the product-list stream, and presents the product itself using another React component: <Product>. The latter isn't 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., but a simple React component.

Register the Frontastic component

By now you still need to register 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. in the code base of your project. Do this by editing <project>/src/js/tastic/tastics.js, import the ReactJS class of 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. and add it to the list that maps 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. types to classes, for example:

//
... import ProductList from './productList/tastic.jsx'
//

... export default (() => {
    return {
          // ...
          'year-productList': ProductList,
          // ...
    }
})()

🚧

The class must be the same name as that's tasticType in your schema.json, otherwise, it won't work.

Now that you implemented a very first 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., it's time to preview it in your local machine, for that you'll need to create 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. 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`.. We'll show you how to do that in the Creating a Frontastic component in the Frontastic studio article.


Did this page help you?