dashboard:control-changed embed event

Emitted by Omni when the value of one or more controls on an embedded dashboard changes. The payload has only the controls that changed, so your page can react to a single control without comparing two dashboard:controls payloads. Omni sends this event right after the dashboard:controls event that it compares, and only when at least one control changed:

When the dashboard loads, every control is reported as added. A dashboard with no controls doesn’t send this event.
When a parent control changes, each child control whose value follows the parent is also reported as updated.
When only the URL changes, such as a new asUrlSearchParam for a child control or a new urlId, Omni doesn’t send this event. The value didn’t change. Omni still sends a new dashboard:controls event.

Payload

{
  "<controlId>": {
    "action": "added | removed | updated",
    "prev": {
      "control": {},
      "value": "string | null",
      "asUrlSearchParam": "string | null"
    },
    "next": {
      "control": {},
      "value": "string | null",
      "asUrlSearchParam": "string | null"
    },
    "urlId": "string"
  }
}

Properties

object

Change object keyed by the control’s ID.

Hide change properties

string

The type of control change:

added - The control was added, or the dashboard loaded
removed - The control was removed
updated - The control’s value changed. Multi-field filter and dynamic filter controls don’t have a value (it is always null), so they are reported as updated when the control itself changes.

object

The control as the previous dashboard:controls event reported it, with control, value, and asUrlSearchParam. Refer to dashboard:controls for a description of each property. Not included for added controls.

object

The control as this dashboard:controls event reports it, with control, value, and asUrlSearchParam. Not included for removed controls.

string

ID of the dashboard used in the URL.

Example

This example shows a timeframe control that changed from month to week:

{
  "createdAtTimeframe": {
    "action": "updated",
    "prev": {
      "control": {
        "id": "createdAtTimeframe",
        "type": "FIELD_SELECTION",
        "kind": "TIMEFRAME",
        "field": "order_items.created_at[month]",
        "label": "Created At",
        "options": [
          { "label": "Month", "value": "order_items.created_at[month]" },
          { "label": "Week", "value": "order_items.created_at[week]" }
        ]
      },
      "value": "order_items.created_at[month]",
      "asUrlSearchParam": "c--createdAtTimeframe=order_items.created_at%5Bmonth%5D"
    },
    "next": {
      "control": {
        "id": "createdAtTimeframe",
        "type": "FIELD_SELECTION",
        "kind": "TIMEFRAME",
        "field": "order_items.created_at[week]",
        "label": "Created At",
        "options": [
          { "label": "Month", "value": "order_items.created_at[month]" },
          { "label": "Week", "value": "order_items.created_at[week]" }
        ]
      },
      "value": "order_items.created_at[week]",
      "asUrlSearchParam": "c--createdAtTimeframe=order_items.created_at%5Bweek%5D"
    },
    "urlId": "0f238b75"
  }
}

This example listens for the event and logs the new value of each control that changed:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://yourcompany.embed-omniapp.co") return
  if (event.data?.name !== "dashboard:control-changed") return

  for (const [controlId, change] of Object.entries(event.data.payload)) {
    if (change.action === "removed") {
      console.log(`${controlId} was removed`)
    } else {
      console.log(`${controlId} is now ${change.next.value}`)
    }
  }
})

Getting started

Setup

App customization

Events & interactivity

Admin

dashboard:control-changed embed event

Payload

Properties

Example

​Payload

​Properties

​Example

Payload

Properties

Example