UX Framework - Configuration Guide
Author:
Fluent Commerce
Changed on:
4 Mar 2025
Overview
The OMX UX Framework delivers configuration-based solution implementation for UIs (Web Apps). Configuration is managed in a JSON document called the OMX Web App .
Key points
- The OMX Web App Manifest document is essential for configuring Fluent Platform web apps and is stored in a setting following the convention "fc.mystique.manifest.<appname>". For instance, Fluent Commerce UIs have settings like "fc.mystique.manifest.oms" and "fc.mystique.manifest.store."
- The document, configured in the ACCOUNT context, is a specific JSON structure that includes sections like App-Level Configuration, Route-Level Configuration, and Local Development Options. Each web app defined within an account has a unique URL, and the Manifest guides app development, covering aspects like navigation, screen layouts, data sources, and user actions.
- Manifest updates can be done through Console/settings or directly via the API, with the ability to partition the document for manageability.
Introduction to the OMX Web App Manifest document
Each Web App in the Fluent Platform will have a setting to hold the Web App document.
The required convention for this setting name is: `fc.mystique.manifest.<appname>`
For example, the Fluent Commerce UIs have the following settings:
`fc.mystique.manifest.oms``fc.mystique.manifest.store`
The setting is configured in `ACCOUNT` context and contains a specific JSON structure.
OMX Web App URL Endpoint
Each Web App defined within the will have a unique URL, with the following convention: `https://<accountid>.sandbox.apps.fluentcommerce.com/<appname>`.
Notice how the `<appname>` in the setting matches the URL path.
Web App Manifest Guide
In this section:
- App-Level Configuration
- Route-Level Configuration
- Page Routes
- Section Routes
- Reference Routes
- Local Development Options
Updating the Manifest
The lives in an setting, so updates can be done in the same way other settings are update - either by looking it up in Console/settings and editing or on the API directly via Postman/Insomnia/other API client.
The name of the setting to update for a given app is prefixed with the `mystique` domain, followed by the name of the app. For example, a servicepoint would be set at:
`fc.mystique.manifest.servicepoint`
Currently, all settings must be populated at the level; however, there are several within the (e.g., roles, conditional components, etc) to change the look and behavior of a single app across different retailers or locations.
Partitioning the Manifest
The document can get pretty big, so it's possible to split a single into smaller fragment settings and manage each separately.
See Reference Routes below for more information on splitting routes into separate JSON documents.
Individual values in a may also be stored as API settings and referenced with a string prefixed with `setting:` followed by the setting name - similar to how you would use an i18n label.
For example, a page's data query's variables could be stored in a setting:
1"data": {
2 "query":"query(status:[String!]) {...}",
3 "variables": { "status":"setting:fc.sf.arrivals.states" }
4 }
5}App-level Configuration
Name | Type | Req | Description | Sample |
|
| ✅ | The version of the Web App schema. At present, this should always be set to |
|
|
| ✅ | Name of the app used in logs and when filtering user actions. |
|
|
| ❌ | The icon is associated with this web app. See Icons for details. |
|
|
| ✅ | Name of the app used in visible locations (app header, browser title bar, etc). Since this is end-user visible, it should be translated via i18n. |
|
|
| ❌ | Enables us to rename 'servicepoint' to 'store' without changing all the workflows. |
|
|
| ❌ | The
The | Fluent Store Example
|
|
| ❌ | Defines the Component SDK plugins to load while rendering this app. |
|
|
| ✅ | The initial page to load on login, or whenever no other page is referenced in the URL. |
|
|
| ✅ | The pages available in this app (see [Route-level Configuration][7]). | |
|
| ❌ | Default settings values which are used out of the box. |
|
|
| ❌ | Components can be added for both mobile and desktop views, appearing between the app name and context name. Accepts standard In addition to the standard array of properties, the |
|
`headerProperties`
For more details on how to configure the headerProperties checkout the how-to guide.
Name | Type | Req | Description | Sample |
|
| ❌ | Allows a builder to configure extra header components between the icon/app name and the selector/user menu shown on desktop screen dimensions.
|
|
|
| ❌ | Allows a builder to configure extra header components between the icon/app name and the selector/user menu shown on mobile screen dimensions.
|
|
Route-level Configuration
The "routes" section of the is where you define the pages of your app and what content to present on them.
Routes is an array of `MystiqueRoutes`, which are one of "Page", "Section", or "Reference" (see below), and other fields depending on that type.
Page Routes
Name | Type | Req | Description | Sample |
|
| ✅ | Defines this route as a page. |
|
|
| ✅ | The URL for this page. |
|
|
| ❌ | Determines if the left side navigation is shown on pages within the route |
|
|
| ❌ | Optional configuration for this page in the navigation page. |
|
|
| ❌ | If present, users must have at least one of the roles defined in the context of the app (retailer or ) to be able to access the page. |
|
|
| ✅ | Name of the component to be used to render this page. Typically |
|
|
| ❌ | If present, the defined query will be executed before rendering the page, and the resulting data will be made available to the page and it's descendants.
Note: template strings will always produce a string value, and there are some cases where requires a non-string variable. | Standard example
Parsed values example
|
|
| ❌ | The component props are to be passed into the page component. |
|
|
| ❌ | The components to display on the page. |
|
Section Routes
A section is a group of pages that are nested under a single header in the nav sidebar.
Name | Type | Req | Description | Sample |
|
| ✅ | Defines this route as a section. |
|
|
| ✅ | Details for configuring the Nav bar properties are provided in the table below: "NAV PROPERTIES". |
|
|
| ❌ | If present, users must have at least one of the roles defined in the context of the app (retailer or ) to be able to access the section. |
|
|
| ✅ | Pages within this section, as defined in the page section above. |
NAV PROPERTIES
Property | Type | Required | Default | Description | Sample |
|
| Yes | N/A | The label is the user-facing text that defines the name of the page and should use a translatable i18n key. |
|
|
| Yes | N/A | The icon is displayed in the nav bar for a page. |
|
|
| Yes | N/A | Badges are configured to show a number of outstanding items for a particular page. |
|
Badge Properties
Name | Type | Required? | Default | Description | Sample |
|
| Yes | N/A | Takes a named GraphQL Schema query. This is used to retrieve a count of outstanding items from the query. |
|
|
| Yes | N/A | Takes properties that are available in the query to filter data. |
|
|
| No | N/A | Define the color of the badge and number using low and high thresholds to indicate the severity of outstanding items. |
|
thresholds Properties
Name | Type | Required? | Default | Description | Sample |
|
| Yes | N/A | If results are below this threshold, then the badge will be green. |
|
|
| Yes | N/A | If results are above this threshold, then the badge will be red. When results are between |
|
Note
Reference Routes
A reference route is a mechanism for partitioning the into logical smaller JSON documents.
To achieve this, include a "reference" type in the routes section of the (instead of the usual "section" or "page" types) like so:
Name | Type | Req | Description | Sample |
|
| ✅ | Defines this route as a section. |
|
|
| ✅ | Defines the name of the Setting to load the fragment |
|
MANIFEST FRAGMENT STRUCTURE
The fragment is a cut-down version of a full , in that it defines additional sections and pages that will appear in the app navigation in the position where the reference was included in the original . The fragment may also define additional default settings to be used by the .
The fragment should simply define the `manifestVersion`, a `routes` array, and an optional `settings` array.
Name | Type | Req | Description | Sample |
|
| ✅ | Version of the schema. At present, this should always be set to |
|
|
| ✅ | The pages available in this app (see [Route-level Configuration][7]). | |
|
| ❌ | Default settings values which are used out of the box. It is recommended to place default settings which are referenced by multiple pages, under the top-level 's default settings key. |
|
Mystique Component Instance
Components within the page follow a consistent structure
Name | Type | Req | Description | Sample |
|
| ✅ | Name of the component in the ComponentRegistry. Refer to component docs for specific examples. |
|
|
| ❌ | The component props to be passed in to the component. |
|
|
| ❌ | Select the subset of the page query that this component will use to render. |
|
|
| ❌ | Some components allow nesting of other components within them, e.g., the |
|
|
| ❌ | If present, users must have at least one of the roles defined in the app's context (retailer or ) to see this component. |
|
Local Development Options
When developing locally, we provide a number of overrides so you can easily control the manifests and fragments being loaded.
This can let you test changes quickly without uploading to your or store multiple versions of the same web app on an and swap between them.
To use these options, you must set the `key` and `value` in your browser's localStorage using its developer tools. See the documentation for your preferred browser:
Setting Name (local storage key) | Type | Description |
|
| A document defining an app. If set, OMX will load this regardless of the app name in the URL. Any fragment references in the will be resolved from the API as normal. |
|
| A setting name. If set, OMX will query the setting API for this key and use its value as the app . Any fragment references in the will be resolved from the API as normal. |
