Component SDK (course)

Introduction to the Fluent OMX: Extend - Component SDK

Lesson Overview

What is the Component SDK?

What can be extended?

• Content components: used to display information, such as data on cards and lists, or even more graphical and visual information such as images, maps, and charts.
• Layout / Page components: layout and page components facilitate screen layout.
• Interaction components: used to capture user input, such as buttons or card-based user action forms.
• Form field components: used to capture data in a form as part of a workflow-driven user action or mutation.
• Template helpers: utility functions for template strings in the manifest document, for transforming data in different ways, such as formatting, styling, and calculating.

Why use the Component SDK?

SDK Features

Custom Components

• Custom View Component: A component that you can simply drop onto a page.
• Custom Field Component: A component that you can hook up to a workflow user action to accept new input types, mutations, or list filters.

Hooks

• useState hook handles all of the state management of an object for you
• useEffect hook for handling side effects and managing the component lifecycle

• useAuth hook provides access to the currently logged in user context
• useI18n hook provides access to the Fluent localisation capability
• useQuery hook lets you interact with the Fluent GraphQL API​

Utility Components

• Card
• Children
• DynamicValue
• Loading
• Drawers, Modals, and Toasts

Registries

• Component Registry - for standard in-page components
• Field Registry - for interactive form field components
• Template Registry - for adding new template helpers

Want to learn more?

Download & Setup the Component SDK

• Download the Component SDK file 
• Save the Component SDK zip file to your computer, and extract the zip file in a suitable location for development

• Open a terminal (command line) window, and change the directory into the `omx-component-sdk` folder.
• Next, run `yarn install` — this will download all the required dependencies by the SDK.
• Now open the `omx-component-sdk` folder in Visual Studio Code — You will notice that the project contains some sample components. 
• Open the `Hello.tsx` file, and make sure that you don't see any errors or red underlines on the Hello component file.
• While in development mode, you can run the project locally, and reference it in your Fluent Web Apps manifest — You will configure this later in the course. However, in the meantime, switch back to the terminal window, and start the project using `yarn start`

Client Scenario: Product availability lookup and stock reservation at a close by location

Client Scenario

• Be added to the Product Availability details screen/interface.
• Display pins corresponding to the 10 closest locations that currently stock for the specific shoe variant requested.
• Display store details upon clicking each pin to display:
  • Location Name
  • Product Reference
  • Available Stock on hand
• Be configurable through the manifest and unit tested.

Hands on Lab:

• Add a new Page to the Fluent Store Web App as a top level menu item.

• Use a List Component and configure it to show variant products

• Configure the List Filter
• Hyperlink the product reference using the following format: `#/products/{{node.catalogue.ref}}/{{node.ref}}`

• Add a new page
• Update the Product Lookup page to link the product ref to the Detail Availability Page

• Add a card component for product details
• Add a card component to show the product image
• Add a list component and configure it to show data from the searchVirtualInventory query

Building your first Custom Content Component (Hello World)

Need help?

Need help?

Defining Properties for configuration via the Manifest

Using your first Hook

Using a 3rd party library

• Prefer React-based
• Prefer Material UI

Adding Nested (Child) Components

Access Data from the Page Query

Style & Theme your component

Make Your Component Interactive

Configurability using Settings

Using Dynamic Attributes

Intro to Field Components

• Workflow user actions to match the data types expected by custom Rules.
• GraphQL mutations to improve the UX of previously purely auto-generated forms.
• List filters to extend the UIs available to select filter options, e.g. doing a customer lookup to provide a customer ID.

Let's continue with our client scenario:

Building your first Custom Field Component (Hello Field)

To start with, let's simply create a "Hello Field" example:

• Create a new `StockReservation.tsx` and define the interface for the outgoing payload. [0:50]
• You now need to define the Field component by once again using the `FC` (FunctionComponent) component from React as the base, and typing it to the UX Framework `FormFieldProps` — which in turn requires another generic for the output, in our case we will define it to be our payload structure `StockReservationPayload`. [1:43]
• The FormFieldProps provides a number of useful properties — use the `onChange` since this will allow us to capture the user input. [2:36]

• Before you go implement the full function of the component, let's make sure it renders to screen by simply returning a "Hello Form" div. [3:01]
• Register the field with the `FieldRegistry`, and take note of the name. This will be used to configure the workflow later. [3:29]
• Make sure the local references include a dot slash: `'./fields/StockReservation';` [4:02]
• Update the workflow user action definition to change the type from `STRING` to `stockReservation`. [4:13]

Using existing Field Components from the Registry

• Add some structure to your custom field
• Add some style to your custom field
• Add in the form controls 

• First is a control for the `quantity` property of the `StockReservationPayload — `the value should be a positive integer. We have an existing control in the component library for this very purpose, so we can pull that component into use within our new field.
• Add a new state variable to hold the `quantity` value. [0:28]
• Next, retrieve the `QuantitySelector` field component from the `FieldRegistry` using its alias "number". [0:56]
• Now add the `QuantitySelector` component to the `div` with the `quantitySelectorContainer` class, and set the `name`, `label`, `value`, and `onChange` handler. [1:33]
• When developing it's helpful to make use of the web console for debugging and confirming the output. This can be done using the `useEffect` hook. [2:45]

Retrieving Data using the useQuery Hook

• Define a structure for the SearchVirtualInventory query result nodes
• Define a structure for SearchVirtualInventory results
• Store the query in a string constant
• Use the `useQuery` hook to pass in the parameters, and execute the query

• Add the entityContext property to your component props [0:33], and call the useAuth hook [0:39]. We will retrieve values from each of these later when setting the query parameter values.
• Use the `useQuery` hook [0:52] to pass in the parameters [1:45] and execute the query.  

• Retrieve the `productRef` from the `entityContext` on `FormFieldProps`, which is the current Product we're performing the availability lookup on [2:22]
• Retrieve the `locationRef`, `lat` and `lng` from the currently logged-in user's context, using the `useAuth` hook. [3:08]
• Since the query will be executed asynchronously, it is best practice to show a "Loading" component in the UI until the query results are returned and can be rendered. [4:37]
• Once the results are returned by the query, they can be rendered to screen. For now, we'll print out the JSON response. [5:01]

• Add a new state variable for the location [0:10].  This will be updated each time the user selects a different location.
• Loop through the results and render a radio button and label for each result [0:44] — for this, use the `FormControlLabel` from the standard Material UI component library [1:06]
• Set the checked radio property to the result that matches the state variable location [1:30]
• Add an `onChange` handler to update the `location` state variable [1:54]
• To confirm it works, add another console log to the `useEffect` hook to print out the currently selected `location` state variable value [2:42]

Produce a Custom Value

• First, you need to update the useEffect hook and call the onChange event defined on the FormFieldProps component.
• Since we typed the FormFieldProps to use the StockReservationPayload interface, this expects a locationRef and a quantity as part of the complex object value.
• Additionally, onChange should only be called if there is a valid value selected for the location state variable.
• Since this is a form for a User Action, you can view the event posted to the transition API in the Network tab of your browser developer tools.
• Finally, locate the reservationDetails event attribute to see the result.

Building a Custom Template Helper

• Styling
• Formatting
• Calculations

Testing Components

• Create static mock objects:
  • `useAuthResponse` - mock the response for the useAuth hook
  • `data` - mock the data result from the page query
  • `attributes` - mock the manifest configured dynamic attributes
• Arrange: The Arrange step sets up the mocks. In this case, we simply need to tell the useAuth hook to return our previously prepared mock auth response object
• Act: The Act step creates an instance of the TrainingMap component, taking in the mocked objects for page query response data and manifest configured dynamic attributes
• Assert: The Assert step compares the rendered output of the component to the previously snapshotted output

Deploying a Custom Component Plugin

• Versioning
• Bundle
• Deploy
• Add your plugin reference to the Manifest document