Docs
Author:
Fluent Commerce staff
Changed on:
22 Apr 2024
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.
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`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>`In this section:
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.
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]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. | |
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`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. | |
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. |
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
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 | |
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. | |
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. | |
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. |
Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.
