Using Frontastic components
What's a Frontastic component?
A Frontastic component 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 component is made up of a definition from the Frontastic studio, the corresponding frontend code, and the required data from an API.
A Frontastic component always consists of 2 parts:
- A JavaScript entry point which is a ReactJS (JSX) component that receives some special props
- A JSON file that defines which data the Frontastic component requires and how this should be configurable in the Frontastic studio, we call this JSON file the schema
Throughout this article, we'll be referencing a simple Frontastic component that displays a list of products. We'll use the ProductList
Frontastic component from the Frontastic starter components 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 components:
- Static
- Flexible
- Connected
Static components are those that you can build with a schema, and there are no configurable fields in the Frontastic studio. For example, a horizontal spacer.
Flexible components are those that have some fields that are configurable in the Frontastic studio, 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 source and are then filtered in the Frontastic studio. For example, a product slider.
Frontastic components are called
tastics
in code for short.
For tips on how to split your commerce site into Frontastic components, see our How to slice a commerce site into components article.
File placement
Custom Frontastic components 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 component requires its own sub-directory which is the camelCased Frontastic component name.
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/catwalk/src/js/tastic/productList/productListTastic.jsx
Tip
When you download the schema from the studio, you can add this to your repository in this folder to keep the files together.
Frontastic component specification
The Frontastic studio needs to know how the Frontastic component 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 component:
{
"tasticType": "year-productList",
"name": "Product List",
"icon": "list",
"schema": [
...
]
}
The tasticType
defines a name of how the Frontastic component 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 component which can be selected from the Material Design Icons. The schema
key then contains the parameter list for the Frontastic component:
{
...
"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 studio 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 component 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 studio and result in objects to submit the information to your Frontastic component. 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 component 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 component will be created in the Components area of the Frontastic studio. Any time you want to change required parameters or any metadata, you'll need to adjust the specification in the studio. See the creating a Frontastic component in the Frontastic studio
Frontastic component React code
The Frontastic component itself is basically a ReactJS component that receives some pre-defined props from the API hub. If you're not familiar with ReactJS, components, and props, 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 component receives the prop tastic
which contains all information that's available about the Frontastic component itself. This includes the schema
.
The data
prop contains all collected data the Frontastic component 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 using 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 returnsnull
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 component, but a simple React component.
Register the Frontastic component
By now you still need to register your Frontastic component in the code base of your project. Do this by editing <project>/src/js/tastic/tastics.js
, import the ReactJS class of your Frontastic component and add it to the list that maps Frontastic components 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 yourschema.json
, otherwise, it won't work.
Now that you implemented a very first Frontastic component, it's time to preview it in your local machine, for that you'll need to create your Frontastic component in the Frontastic studio. We'll show you how to do that in the Creating a Frontastic component in the Frontastic studio article.
Updated 9 months ago