Custom components

The Plaza theme enables you to create themes using our React components library, which is included in the latest sfb-toolkit version. The toolkit includes components that you can use to quickly build and customize your storefront pages through the Storefront Builder visual editor. For example, you can integrate the Slider, Carousel, ProductBanner, and many more components with your Plaza theme.

If none of the components in our library suit your needs, you can create custom components. Custom components are components that you can create and customize through the schema object.

The Getting Started section contains everything you need to know to start building your custom components according to our guidelines and best practices.

Installation

note

Once custom components are installed there is currently no command to automatically reverse the action! See below for instructions on how to manually remove them.

To setup your theme to use custom components, execture the following sfb-toolkit commands:

sfb-toolkit components

sfb-toolkit components

sfb-toolkit components

The above command will setup the current theme such that you can create your own custom components. When you run the command, the toolkit:

Installs a version of @appdirect/sfb-theme-components in your current theme. The version installed depends on the toolkit version. Older toolkit versions will install older versions of @appdirect/sfb-theme-components.

Creates a customComponents folder in your current theme with two AtomsShowcase components as examples.

Bundles both sfb-theme-components and custom components into one package in the current theme assets folder.

By default, the sfb-theme-components library is bundled and deployed in a CDN (Content Delivery Network) and referenced in your theme. To use custom components, sfb-theme-components is bundled together with the user-defined custom components into a single package.

Therefore, when you run sfb-toolkit components, the toolkit creates a customComponents folder in your current theme where you can start building custom components. Then, when you start your sfb-toolkit server with the sfb-toolkit start command and you make a change inside your customComponents folder, the toolkit bundles your components into a single package and puts it in your theme assets folder so you can preview the changes in your browser using hot module replacement.

sfb-toolkit storybook

sfb-toolkit storybook

This command enables theme developers to visualize all available component documentation through Storybook UI. The Storybook includes both sfb-theme-components and the custom components that you have created.

Reuse existing sfb-theme-components

You can reuse existing components (atoms or components) from the library for your custom components. For example, if you want to reuse the Button atom in your custom component, add the following import:

import Button from '@appdirect/sfb-theme-components/src/atoms/button/Button';

For each component documented in Storybook UI, you can find under Usage Example an example of how you can reuse/import one of our components in your custom components.

Remove custom components usage (manual steps)

To stop using custom components and use instead the CDN version of @appdirect/sfb-theme-components (instead of the npm module one) please follow these steps:

In the base.html file replace:

<link rel="stylesheet" type="text/css" href="{{ r("/assets/js/components/sfb-components.css") }}"> with
<link rel="stylesheet" type="text/css" href="{{ config.channelSettings.channelCanonicalBaseUrl }}/sfb-theme-components@0/sfb-components.css">

<script src="{{ r("/assets/js/components/sfb-components.js") }}"></script> with
<script src="{{ config.channelSettings.channelCanonicalBaseUrl }}/sfb-theme-components@0/sfb-components.js"></script>

In the theme folder:

• Delete the customComponents folder.
• Using a terminal execute npm uninstall @appdirect/sfb-theme-components --save.

    npm uninstall @appdirect/sfb-theme-components --save

Update custom components UI library (sfb-theme-components)

When sfb-toolkit components is executed a specific version of sfb-theme-components will be installed as part of your theme and will not change. This is done to ensure that the expected behaviour is not changed through future updates. As such, the installed sfb-theme-components library version is effectively fixed.

To update the sfb-theme-components library you can simply execute sfb-toolkit install @appdirect/sfb-theme-components@latest.

    sfb-toolkit install @appdirect/sfb-theme-components@latest

note

There is a possibility that your theme might not be compatible with the latest version of sfb-theme-components before attempting the upgrade please check the package.json file and note down the fb-theme-component version you are currently using so that you can revert back to it in cases you encounter any issues.

To revert back to an older sfb-theme-components version sfb-toolkit install @appdirect/sfb-theme-components@version where version represents the previously noted down npm package version number.

    sfb-toolkit install @appdirect/sfb-theme-components@version

Availability

@appdirect/sfb-toolkit@2.0.5