Basic Knowledge
Essential knowledge articles on Component SDK
UX Configuration - Common Concepts
Essential knowledgeCore knowledge to understand Fluent CommerceSome common types and conventions are used across many component definitions. These items are not directly configurable in the manifest but will often be referenced in other component definitions that use them.- The Mystique manifest configures icons, cards, and template strings. Icons come from React Icons.
- Cards have common fields, and template strings allow dynamic values. Dynamic attributes (standard, image, component) offer flexibility based on conditions.
- A selection of helper functions are also available to control and transform these values as required, for example, number, logic, i18n, array, date, and string functions.
- Additional options like TextOptions and ImageOptions provide styling choices.
Extending the UX Framework with the Component SDK
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson introduces the Component SDK, a powerful toolkit for extending the UX Framework Component Library. We'll explore the core concepts behind the SDK, covering its purpose, capabilities, and benefits. By the end of this lesson, you'll understand how the Component SDK empowers developers to create custom, OMX-ready components for Fluent Web Apps, streamlining development and ensuring consistent user experiences.- What is the Component SDK? A development kit for building custom components for the UX Framework Component Library using modern, developer-friendly tools like React and TypeScript.
- What can be extended? Developers can create a wide range of components, including content, layout/page, interaction, form field components, and template helpers, significantly expanding the functionality of the standard library.
- Why use the Component SDK? The SDK simplifies custom component creation by handling complex tasks like manifest configuration, authorization, data access, localization, and workflow interaction, allowing developers to focus on component logic and design. It also leverages the Fluent OMX Design System (based on Material-UI) for consistent and high-quality UX.
Unit Testing Custom Components
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson covers the process of unit testing custom components using the tools provided within the Component SDK: Jest and React's test renderer. We'll walk through the steps of creating mock objects for dependencies (authentication, data, attributes), arranging the test environment, acting by rendering the component with the mocks, and asserting the output using snapshot testing. This process ensures the reliability and correctness of your custom components.- Testing Framework: The SDK includes Jest and React's test renderer for unit testing.
- Mock Objects: Mock objects are created for external dependencies like authentication (
`useAuth`), data from the page query, and dynamic attributes from the manifest. - Arrange, Act, Assert: The testing process follows the standard Arrange, Act, Assert pattern.
- Arrange: Mocks are set up and configured.
- Act: The component is rendered with the mock data.
- Assert: The rendered output is compared against a snapshot.
- Snapshot Testing: Jest's snapshot feature is used to compare the component's output to a previously saved snapshot, ensuring consistency.
- Testable Components: Unit tests help ensure the reliability and maintainability of custom components.
Enhance Your Custom Fields: Leveraging Existing Components from the Registry
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson details how to enhance custom form fields by adding structure, styling, and interactive controls. We'll focus on improving the user experience and data capture capabilities of our custom field component. This involves using Material-UI for styling, organizing the field's layout, and integrating pre-built form controls from the component library, such as the `QuantitySelector`. We'll also cover best practices like using the `useEffect` hook for debugging.- Structure and Layout: Learn how to structure and organize the elements within your custom form field for optimal presentation.
- Styling with Material-UI: Use Material-UI's styling capabilities (e.g., makeStyles) to style your custom field and maintain design consistency.
- Form Control Integration: Integrate pre-built form controls, like the QuantitySelector, to efficiently capture specific data types (e.g., integers for quantity).
- Component Registry Retrieval: Learn how to retrieve and use existing components from the component registry (e.g., the QuantitySelector using its alias "number").
- State Management: Manage the state of form inputs using React's state mechanisms.
- Debugging with
`useEffect`: Use the `useEffect` hook to debug and verify the behavior and output of your custom field.
Accessing User and Location Context with the useAuth Hook
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson explores the `useAuth` hook provided by the Component SDK, which grants access to crucial information about the currently logged-in user. We'll learn how to retrieve user details, including roles/permissions and the current location/retailer context. Specifically for location-context web apps like Fluent Store, we'll focus on using this hook to access the currently selected store's information, such as longitude and latitude coordinates, which will be essential for our map implementation.`useAuth` Hook Purpose: The useAuth hook provides a convenient way to access details about the authenticated user, including their roles, permissions, and current context.- Contextual Information: The hook provides access to the user's current location or retailer context, which is vital for location-based applications.
- Location Coordinates: For location-context apps, useAuth allows retrieval of the selected store's coordinates (longitude and latitude), enabling map integration and location-based functionality.
- Fluent Store Application: In the context of Fluent Store, this hook will be used to get the coordinates of the currently viewed store, providing the data needed to display the store's location on the map.
Client Scenario: Building a Product Availability Map
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson introduces a practical client scenario: visualizing product availability on a map. Building upon the foundation laid in the UX Framework course, we'll enhance the Fluent Store app's Product Availability screen by adding a map that displays nearby store locations and stock information for a selected product variant. This hands-on lab will guide you through configuring the product lookup and detail availability pages, setting the stage for creating custom components in subsequent lessons.- Client Need: The client requires a visual representation of product availability in nearby stores, which would enable staff to locate items quickly for customers.
- Map Functionality: The map should be integrated into the Product Availability details screen. It should display pins for the 10 closest stores with stock and show store details (name, product reference, available stock) when a pin is clicked. The map's appearance and behavior should be configurable via the manifest.
- Product Lookup Configuration: This involves adding a new page to the Fluent Store app, using a List Component to display product variants, configuring list filters, and creating hyperlinks to product details pages.
- Detail Availability Page Configuration: This includes creating a new page, linking it from the Product Lookup page, and adding card components to display product details and images. A List Component will show data from the search VirtualInventory query.
- Hands-on Lab Focus: The lab simulates a real-world scenario where a customer seeks a specific shoe size, requiring a store associate to check nearby store inventory. This exercise will prepare you for creating custom components in the following lessons to realize the client's vision fully.
Building Custom Components with the Component SDK
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson dives into the practical application of the Component SDK, focusing on how to build custom components for OMX Web Apps. We'll explore the different types of custom components you can create, the powerful hooks available for interacting with the Fluent platform, and the utility components that streamline development and ensure consistency. We'll also touch on the crucial concept of component registries.- Types of Custom Components: The Component SDK enables the creation of custom view components (for page content) and custom field components (for workflow user actions), allowing developers to tailor interfaces to specific needs.
- Hooks for OMX Integration: Fluent-specific React hooks (e.g.,
`useAuth`, `useI18n`, `useQuery`) provide easy access to platform functionalities like authentication, localization, and API interaction, simplifying complex tasks. - Utility Components for Consistency: The SDK offers utility components (e.g., Card, Loading, Drawers) that serve as building blocks for custom components, ensuring a consistent look and feel, theme responsiveness, and mobile compatibility.
- Component Registries: Custom components must be registered with the appropriate registry (Component, Field, or Template) before they can be used in OMX Web Apps, making them discoverable and usable within the framework.
Creating Custom Template Helpers
Essential knowledgeCore knowledge to understand Fluent CommerceThis lesson explores the creation and registration of custom template helpers within the Component SDK. Template helpers are powerful utilities that can be used within Manifest documents for tasks like styling, formatting, and calculations. We'll demonstrate how to create a custom template helper, in this case, one that bolds entity references, showcasing how to leverage the `TemplateRegistry` and its utility methods for generating formatted HTML.- Template Helpers: Template helpers are reusable functions that can be called within Manifest documents to perform various operations.
- Use Cases: Template helpers can be used for styling, formatting, calculations, and other data transformations.
`TemplateRegistry`: The `TemplateRegistry` is used to register custom template helpers, making them available for use in Manifests.- HTML Formatting: The lesson demonstrates creating a template helper that bolds entity references using
`TemplateRegistry` utility methods for formatted HTML generation. - Customizability: Custom template helpers extend the functionality of Manifests, allowing for greater flexibility and control over data presentation.
Extending Forms with Custom Field Components
Essential knowledgeCore knowledge to understand Fluent CommerceThis 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` and `quantity`.- 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.