UX Framework - Configuration Guide
Author:
Fluent Commerce
Changed on:
15 Oct 2024
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 Manifest.
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 Manifest 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`OMX Web App URL Endpoint
Each Web App defined within the account will have a unique URL, with the following convention:
`https://<accountid>.sandbox.apps.fluentcommerce.com/<appname>`Notice how the
`<appname>`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 manifest lives in an account 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``fc.mystique.manifest.servicepoint`Currently, all manifest settings must be populated at the account level; however, there are several controls within the manifest (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 manifest document can get pretty big, so it's possible to split a single manifest 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 manifest may also be stored as API settings and referenced with a string prefixed with
`setting:`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}Language: java
Name: A page's data query's variables could be stored in a setting
Description:
[Warning: empty required content area]App-level Configuration
Name | Type | Req | Description | Sample |
| | ✅ | The version of the Web App Manifest 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 If not provided it will default to the value 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`
`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 location selector/user menu shown on desktop screen dimensions. | |
| | ❌ | Allows a builder to configure extra header components between the icon/app name and the location selector/user menu shown on mobile screen dimensions. | |
Route-level Configuration
The "routes" section of the manifest is where you define the pages of your app and what content to present on them.
Routes is an array of
`MystiqueRoutes`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 location) 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 GraphQL 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 location) 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 GraphQL 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 manifest into logical smaller JSON documents.
To achieve this, include a "reference" type in the routes section of the manifest (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 manifest fragment | |
MANIFEST FRAGMENT STRUCTURE
The fragment is a cut-down version of a full manifest, 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 manifest. The fragment may also define additional default settings to be used by the Manifest.
The fragment should simply define the
`manifestVersion``routes``settings`Name | Type | Req | Description | Sample |
| | ✅ | Version of the Mystique Manifest 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 Manifest'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 location) 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 manifest changes quickly without uploading to your account or store multiple versions of the same web app on an account and swap between them.
To use these options, you must set the
`key``value`Setting Name (local storage key) | Type | Description |
| | A Manifest document defining an app. If set, OMX will load this regardless of the app name in the URL. Any fragment references in the manifest 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 manifest. Any fragment references in the manifest will be resolved from the API as normal. |
