Fluent Commerce Docs

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Content in this track:

UX Framework - Component Library

UX Framework - Configuration Guide

UX Configuration - Common Concepts

Configure a drawer via manifest

Configure UI for Mixed Baskets

End Of Track

Content in this track: UX Framework - Configuration Guide

Essential knowledge

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 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>`

Note

`mystique` is a short-hand codename for the OMX UX Framework

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 account 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 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` domain, followed by the name of the app. For example, a servicepoint manifest would be set at:`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:` 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}

Note

A `setting:` label may safely reference a setting that contains an `i18n:` label, but must not reference another `setting:` label - they cannot be nested.

App-level Configuration

*Name*	*Type*	*Req*	*Description*	*Sample*
`manifestVersion`	`string`	✅	The version of the Web App Manifest schema. At present, this should always be set to `2.0`.	`"manifestVersion": "2.0"`
`name`	`string`	✅	Name of the app used in logs and when filtering user actions.	`"name": "servicepoint"`
`icon`	`string`	❌	The icon is associated with this web app. See Icons for details.	`"icon": "FaLaptop"`
`title`	`string`	✅	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.	`"title": "i18n:fc.mystique.appName.ServicePoint"`
`orchestrationAlias`	`string`	❌	Enables us to rename 'servicepoint' to 'store' without changing all the workflows.	`'orchestrationAlias': 'servicepoint'`
`context`	`MystiqueManifestRole`	❌	The `level` property defines the context of this app. For example this could be either at a “retailer” (Fluent OMS) or “location” (Fluent Store) level. If not provided it will default to the value`{ "level": "retailer" }`The `role` property can be optionally defined as either singular or an array of strings, which gives the ability to restrict access to users who have been granted a particular role. Users without access won't see those apps across the store in any selectors or dropdowns. For example in the Fluent Store location, you could define the `STORE_ASSOCIATE` role as well as adding the relevant location context to a particular user to give them access to the app. The `switcher` property can be optionally defined, which allows for users to switch contexts from within the app. If this property is enabled and a user has multiple contexts at the same level, then a dropdown will appear on the top right of the app, allowing for navigation between contexts. The dropdown will contain 10 contexts, and the list is scrollable in case of additional contexts.	Fluent Store Example`"context": {` ` "level": "location",` ` "role": "[“STORE”, “STORE_ASSOCIATE”],` ` "switcher": true` `}`
`plugins`	`MystiquePlugin[]`	❌	Defines the Component SDK plugins to load while rendering this app.	`"plugins": {` ` "src": "https://example.com/bundle.js",` ` "name": "Example"` `}`
`homePath`	`string`	✅	The initial page to load on login, or whenever no other page is referenced in the URL.	`"homePath": "orders"`
`routes`	`MystiqueRoute[]`	✅	The pages available in this app (see [Route-level Configuration][7]).
`settings`	`key/value map`	❌	Default settings values which are used out of the box.	`"settings:" : {` ` "defaults": {` ` "fc.setting.name": "value"` ` }` `}`
`header`	`headerProperties`	❌	Components can be added for both mobile and desktop views, appearing between the app name and context name. Accepts standard `MystiqueComponentInstance` properties.In addition to the standard array of properties, the `position` property determines the component's position and can have values of "left", "right", "center" or "centre". This is an optional property, and the default value is 'left'.	`"header": {`` "desktop": [`` {`` "position": "left",`` "component": "fc.mystique.collapsible.text",`` "props": {`` "text": "text",`` "charCutoff": 100`` }`` }`` ],`` "mobile": [`` {`` "position": "center",`` "component": "fc.mystique.collapsible.text",`` "props": {`` "text": "text",`` "charCutoff": 100`` }`` }`` ]``}`

`headerProperties`

For more details on how to configure the headerProperties checkout the how-to guide.

*Name*	*Type*	*Req*	*Description*	*Sample*
`desktop`	`MystiqueComponentInstance & { position: string }[]`	❌	Allows a builder to configure extra header components between the icon/app name and the location selector/user menu shown on desktop screen dimensions.`position` allows the builder to specify (`left, right, centre/center`) which determines where the component is placed on the header.	`[`` {`` "position": "left",`` "component": "fc.mystique.collapsible.text",`` "props":`` {`` "text": "text",`` "charCutoff": 100`` }`` }``]`
`mobile`	`MystiqueComponentInstance & { position: string }[]`	❌	Allows a builder to configure extra header components between the icon/app name and the location selector/user menu shown on mobile screen dimensions. `position` allows the builder to specify (`left, right, centre/center`) which determines where the component is placed on the header.	`[`` {`` "position": "center",`` "component": "fc.mystique.collapsible.text",`` "props":`` {`` "text": "text",`` "charCutoff": 100`` }`` }``]`

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`, which are one of "Page", "Section", or "Reference" (see below), and other fields depending on that type.

Page Routes

*Name*	*Type*	*Req*	*Description*	*Sample*
`type`	`page`	✅	Defines this route as a page.	`"type": "page"`
`path`	`string`	✅	The URL for this page. This URL can optionally include parameters, which may then be used in the GraphQL query and/or page components. Parameters are denoted with a colon, for example, when visiting a page with a path of `/orders/:id` as `/orders/123`, the value `id = 123` would be available to be used in the page query to retrieve the corresponding Order.	`"path": "/orders/:id"`
`fullScreen`	`boolean`	❌	Determines if the left side navigation is shown on pages within the route The default value is `false`	`"fullScreen": true`
`nav`	`MystiqueNavConfig`	❌	Optional configuration for this page in the navigation page. If there is no nav defined for a given page, it won't appear in the sidebar but will still be accessible via URL. This is common for pages that require parameters, such as the individual Order page `/order/123`. `label` is user-facing and should use a translatable i18n key.	`"nav": {` ` "label": "i18n:fc.om.orders.index.nav",` ` "icon": "library_books"` `}`
`roles`	`string[]`	❌	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. Specifically, on failed role check, the page will disappear from nav and show 404 if directly navigated via the URL.	`"roles": ["ORDER_ADMIN", "CUSTOMER_SERVICE"]`
`component`	`string`	✅	Name of the component to be used to render this page. Typically `fc.page`, but any registered component can be used, so long as it's designed to fill a screen.	`"component": "fc.page"`
`data`	`GQLQuery`	❌	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. Query variables are template strings, and can: access the user's login context information, to filter queries to only those items relevant to the current users retailer or location. Available fields are: activeUser username attributes activeRetailer (for retailer-level apps) id ref activeLocation (for location-level apps) id ref primaryAddress longitude latitude access URL parameters (e.g. on page "/order/:id" you can reference "{{params.id}}") use other template helpers (e.g. data manipulation to generate timeframes for dashboards etc) Note: template strings will always produce a string value, and there are some cases where GraphQL requires a non-string variable. For such cases, you can tell Mystique to parse the value using `JSON.parse` by providing an object following the second code example.	Standard example`"data": {` ` "query": "query ($id: ID!) { orderById(id: $id) { id ref } }",` ` "variables": {` ` "id": "{{params.id}}"` ` }` `}`Parsed values example`"data": {` ` "query": "query ($id: ID!) { orderById(id: $id) { id ref } }",` ` "variables": {` ` "lat": { "value": "{{activeLocation.primaryAddress.latitude}}", "parse":true },` ` "objectValue": { "value":"{\"a\":\"{{params.ref}}\"}", "parse":true } }` `}`
`props`	`key/value map`	❌	The component props are to be passed into the page component. These will differ depending on the component, so refer to individual component documentation for more details.	`"props": {` ` "title": "i18n:fc.om.orders.detail.title",` ` "actions": true,` ` "backButtons": [` ` {` ` "path": "orders",` ` "menuLabel": "i18n:fc.om.orders.detail.breadcrumb.backToOrders"` ` }` ` ]` `}`
`descendants`	`MystiqueComponentInstance[]`	❌	The components to display on the page. Refer to individual component documentation for more details.	`"descendants": [` ` {` ` "component": "fc.card",` ` "dataSource": "orderById",` ` "props": {` ` "title": "i18n:fc.om.orders.detail.card.summary.title",` ` "width": "half",` ` "attributes": [` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.orderType.label",` ` "value": "{{type}}"` ` },` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.orderStatus.label",` ` "template": "{{status}}"` ` },` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.creationDate.label",` ` "template": "{{formatDate createdOn day='numeric' month='numeric' year='numeric'}}"` ` }` ` ]` ` }` ` }` `]`

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
`type`	`section`	✅	Defines this route as a section.	`"type": "section"`
`nav`	`MystiqueNavConfig`	✅	Details for configuring the Nav bar properties are provided in the table below: "NAV PROPERTIES".	`"nav": {` ` "label": "i18n:fc.om.orders.index.nav",` ` "icon": "library_books",` ` "badge":{` ` "queryName": "fulfilments",` ` "variables": {` ` "fromLocation": {` ` "ref": "{{activeLocation.ref}}"` ` },` ` "status": [` ` "AWAITING_WAVE"` ` ]` ` }` ` }` ` }`
`roles`	`string[]`	❌	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. Specifically, on failed role check, all pages will disappear from the nav and show 404 if directly navigated via the URL.	`"roles": ["ORDER_ADMIN", "CUSTOMER_SERVICE"]`
`pages`	`MystiquePage[]`	✅	Pages within this section, as defined in the page section above.

NAV PROPERTIES

*Property*	*Type*	*Required*	*Default*	*Description*	*Sample*
`label`	`string`	Yes	N/A	The label is the user-facing text that defines the name of the page and should use a translatable i18n key.	`"label": "i18n:fc.sf.ui.waves.index.nav"`
`icon`	`string`	Yes	N/A	The icon is displayed in the nav bar for a page.	`"icon": "store"`
`badge`	`object`	Yes	N/A	Badges are configured to show a number of outstanding items for a particular page. Badge properties are defined in the table below.	`"badge":{` ` "queryName": "fulfilments",` ` "variables": {` ` "fromLocation": {` ` "ref": "{{activeLocation.ref}}"` ` },` ` "status": [` ` "AWAITING_WAVE"` ` ]` ` }` ` }`

Badge Properties

*Name*	*Type*	*Required?*	*Default*	*Description*	*Sample*
`queryName`	`string`	Yes	N/A	Takes a named GraphQL Schema query. This is used to retrieve a count of outstanding items from the GraphQL query.	`"queryName": "fulfilments"`
`variables`	`object`	Yes	N/A	Takes properties that are available in the query to filter data.	`"variables": {` ` "fromLocation": {` ` "ref": "{{activeLocation.ref}}"` ` },` ` "status": [` ` "AWAITING_WAVE"` ` ]` ` }`
`thresholds`	`object`	No	N/A	Define the color of the badge and number using low and high thresholds to indicate the severity of outstanding items. Threshold properties are defined in the table below.	`"thresholds": {` ` "thresholdHigh": 5,` ` "thresholdLow": 3` ` }`

Note

Badges are limited to 999 outstanding items. After 999 results are returned than 999+ will be shown to the user.

thresholds Properties

*Name*	*Type*	*Required?*	*Default*	*Description*	*Sample*
`thresholdLow`	`number`	Yes	N/A	If results are below this threshold, then the badge will be green.	`"thresholdLow": 3`
`thresholdHigh`	`number`	Yes	N/A	If results are above this threshold, then the badge will be red. When results are between `thresholdLow` and `thresholdHigh` the badge will be orange.	`"thresholdHigh": 5`

Note

Note

If the `thresholds` object is removed, the badge color is always purple.

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*
`type`	`reference`	✅	Defines this route as a section.	`"type": "reference"`
`settingName`	`<SETTING_NAME>`	✅	Defines the name of the Setting to load the manifest fragment	`"settingName": "fc.mystique.manifest.servicepoint.fragment.pickandpack"`

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`, a `routes` array, and an optional `settings` array.

*Name*	*Type*	*Req*	*Description*	*Sample*
`manifestVersion`	`string`	✅	Version of the Mystique Manifest schema. At present, this should always be set to `2.0`.	`"manifestVersion": "2.0"`
`routes`	`MystiqueRoute[]`	✅	The pages available in this app (see [Route-level Configuration][7]).
`settings`	`ApiSetting[]`	❌	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. Note that if multiple fragments define the same default setting key, the last fragment will determine the value - later setting definitions overwrite previous ones.	`[` ` {` ` "name": "fc.custom.default.setting",` ` "value": "custom default value"` ` }` `]`

Mystique Component Instance

Components within the page follow a consistent structure

*Name*	*Type*	*Req*	*Description*	*Sample*
`component`	`string`	✅	Name of the component in the ComponentRegistry. Refer to component docs for specific examples.	`"component": "fc.list"`
`props`	`key/value map`	❌	The component props to be passed in to the component. These will differ depending on the component, so refer to individual component documentation for more details.	`"props": {` ` "title": "i18n:fc.om.orders.detail.title",` ` "width": 6` `}`
`dataSource`	`string`	❌	Select the subset of the page query that this component will use to render. This mostly just helps to shorten configuration in the props area so that each data reference doesn't have to write out the full path every time.	`"dataSource": "orderById.customer"`
`descendants`	`MystiqueComponentInstance[]`	❌	Some components allow nesting of other components within them, e.g., the `fc.tabs` component uses its descendants to represent the content displayed in each tab.	`"descendants": [` ` {` ` "component": "fc.card",` ` "dataSource": "orderById",` ` "props": {` ` "title": "i18n:fc.om.orders.detail.card.summary.title",` ` "width": "half",` ` "attributes": [` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.orderType.label",` ` "value": "{{type}}"` ` },` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.orderStatus.label",` ` "template": "{{status}}"` ` },` ` {` ` "label": "i18n:fc.om.orders.detail.card.summary.attribute.creationDate.label",` ` "template": "{{formatDate createdOn day='numeric' month='numeric' year='numeric'}}"` ` }` ` ]` ` }` ` }` `]`
`roles`	`string[]`	❌	If present, users must have at least one of the roles defined in the app's context (retailer or location) to see this component. If not, the component will simply not appear on the page.	`"roles": ["ORDER_ADMIN", "CUSTOMER_SERVICE"]`

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` 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*
`mystique.dev.overrides.manifest`	`JSON`	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.
`mystique.dev.overrides.manifestSettingName`	`string`	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. For example, you may have a development version of the Store app in a setting called `example.manifest.store.dev`

What's next?

The next knowledge you would like to know is the Page Component.

Content in this track:

UX Framework - Overview

Component SDK - Overview

UX Framework - Component Library

UX Framework - Configuration Guide

UX Configuration - Common Concepts

Configure a drawer via manifest

Configure UI for Mixed Baskets

fc.mystique.fields.basicpack

End Of Track

UX Framework - Configuration Guide

UX Framework - Configuration Guide

Overview

Key points

Introduction to the OMX Web App Manifest document

OMX Web App URL Endpoint

Web App Manifest Guide

Updating the Manifest

Partitioning the Manifest

App-level Configuration

`headerProperties`

Route-level Configuration

Page Routes

Section Routes

NAV PROPERTIES

Reference Routes

MANIFEST FRAGMENT STRUCTURE

Mystique Component Instance

Local Development Options

Related content

Page Component

Fluent Commerce

Knowledge Tracks Related To This Topic

Building Blocks

By Type

Helpful Resources

Quick Links