Extending Forms with Custom Field Components
Authors:
Cameron Johns, Cille Schliebitz, Anita Gu
Changed on:
3 Feb 2025
Overview
This lesson introduces the concept of custom form fields within the UX Framework. While standard form fields are automatically generated based on data types, developers can create custom field components to handle more complex data structures or enhance the user experience for specific scenarios, such as workflow user actions, GraphQL mutations, and list filters. In our client scenario, we'll focus on building a custom form field to capture stock reservation details, which requires a JSON object containing
`locationRef``quantity`Key points
- Form Field Generation: The UX Framework automatically generates forms based on expected data types.
- Custom Field Components: Developers can create custom field components to handle complex data types or improve UX.
- Extending Scenarios: Custom field components can be used with workflow user actions, GraphQL mutations, and list filters.
- JSON Data Capture: This lesson's focus is on creating a custom field component to capture a JSON object for stock reservation details, containing locationRef and quantity fields.
- Client Scenario: The need for a custom form field arises from the client's requirement to capture stock reservations, which involves a specific JSON structure.
Form fields are the data capture elements in a Web App and are presented on forms to capture user input.
The UX Framework automatically generates forms based on the expected output of the form.
e.g., A form capturing data for a GraphQL mutation or a Workflow Framework User Action.
Developers can extend several scenarios:
- 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.
Each field in the form is determined by its type, such as a text box for a string field or a date picker for a date-typed field.
The UX Framework provides a number of standard field types, but you can create your own custom field types to handle more complex types using the Component SDK
For example, many user actions require the event attribute to contain a JSON structure. This structure is essentially a composite of other types, such as strings, numbers, and dates, but in a single object.
Let's continue with our client scenario:
In our client scenario, the store assistant needs to capture a stock reservation for another store.
To do this, the user action expects an object containing a
`locationRef``quantity``{`` "locationRef": "F_NSYD",`` "quantity": 1``}`A Workflow may be configured to name the type, such as "StockReservationDetails", and declare this in the user action attribute type definition.
The UX Framework will look for field components registered as "StockReservationDetails" and render them to the form. However, this field component does not yet exist.
So, let's move on to the next lesson, which is to build a custom form field for this special complex type.
