configurator-react

Introduction

This React library simplifies the process of building configurator web applications using the Viamedici Headless Configuration Engine (HCE).

It offers all the features of the HCE through strongly typed hooks and logic components, eliminating the need to interact directly with the HCE's REST API.

This library is intended for use in a browser environment and is not compatible with server-side rendering.

UI Framework Independence

The library is designed to be UI framework-agnostic, allowing you to use any UI framework or component library of your choice to build your configurator application.

It provides powerful hooks and logic-only components that can be easily integrated into your styled components.

Features

The library includes additional features that make it even easier to build a configurator.

For a complete list of features, please refer to the base library configurator-ts.

Demo App

The Demo App is a comprehensive showcase of the features provided by this library and the HCE. It demonstrates how to effectively integrate and utilize this library within a React-based Single Page Application (SPA).

Getting Started

1. Install Package

This library supports both ESM and CommonJS.

npm install @viamedici-spc/configurator-react
yarn add @viamedici-spc/configurator-react

2. Define the Session Context

Create a SessionContext to set up the connection parameters for the HCE and defining the Configuration Model you want to use.

Note: If defined inside a component, make sure to memorize the session context object, e.g. with useMemo or useRef.

const sessionContext: SessionContext = {
    sessionInitialisationOptions: {
        accessToken: "<your access token>",
    },
    configurationModelSource: {
        type: ConfigurationModelSourceType.Channel,
        deploymentName: "Car-Root",
        channel: "release"
    }
}

3. Setup Configuration Component

Wrap the configuration area with the Configuration component as its root component. This component manages the configuration state and provides a configuration context for all child components.

Use React’s Suspense feature to render configuration-related components only when the configuration is ready.

Note: Make sure your suspense barrier is located inside the Configuration component when using suspended hooks. Otherwise, the Configuration component will freeze forever.

<Configuration sessionContext={sessionContext}>
    <Suspense fallback={<span>Configuration loading …</span>}>
        <PaintingColorAttribute/>
    </Suspense>
</Configuration>

4. Create an Attribute Component

Now, create a component for the PaintingColor attribute of the Configuration Model.

This component displays the currently selected value of the attribute.

The button triggers a decision to select (include) the value Green.

function PaintingColorAttribute() {
    const {makeDecision, getIncludedChoiceValues} = useChoiceAttribute({localId: "Painting Color"});
    const includedValue = getIncludedChoiceValues()[0] ?? "<nothing>"

    return (
        <div>
            <div>
                Selected value: {includedValue}
            </div>
            <button onClick={() => makeDecision("Green", ChoiceValueDecisionState.Included)}>
                Select Green
            </button>
        </div>
    )
}

License

This project is licensed under the MIT License - see the LICENSE file for details.