Extending Dashboard with Apps

Key concepts

App extensions allow applications to alter the dashboard’s interface by contributing custom buttons, menu items, screens, widgets, and modal overlays. It’s a convenient way to add new features and capabilities without maintaining a custom dashboard application fork.

All contributed views are embedded inside an <iframe> to protect against XSS attacks.

Relation to Saleor dashboard and custom Dashboard

While these API, just like any other Saleor APIs, can be used with a fully custom Dashboard, the API is mainly designed to be consumed by the official Saleor Dashboard.

This document contains assumptions of how the UI can handle such APIs

Manifest

A single App can provide multiple extensions. You can add each extension by specifying it in the App’s manifest. The example manifest below defines two extensions, one providing a custom product action that opens a modal overlay and the second one providing an alternative product creation page:

{
  ...
  "extensions": [
      {
        "label": "Create with Sample app",
        "mount": "PRODUCT_DETAILS_MORE_ACTIONS",
        "target": "POPUP",
        "permissions": [
            "MANAGE_PRODUCTS"
        ],
        "url": "https://example.com/extension/"
      },
      {
        "label": "Create with App and redirect",
        "mount": "PRODUCT_OVERVIEW_CREATE",
        "target": "APP_PAGE",
        "permissions": [
            "MANAGE_PRODUCTS"
        ],
        "url": "/extension/redirect"
      }
    ]
}

• label: The name which will be displayed in the dashboard.
• mount: The place where the extension will be mounted.
• target: The method of presenting the interface (defaults to POPUP). See target section below
• permissions: An array of permissions required for a user to access the extension.
• url: The URL of the view to display. You can skip the domain and protocol when target is set to APP_PAGE, or when your manifest defines an appUrl. When target is set to POPUP, the url will be used to render an <iframe>.
• options depending on the target, additional properties to control the behavior.
• identifier (optional, from 3.23.19): A stable, app-defined identifier used to reference a specific extension programmatically. See Extension identifier.

Extension identifier

From Saleor 3.23.19, an extension can declare an optional identifier — a stable, app-defined string that lets other parts of your app reference that specific extension instead of relying on its label or position.

• It must be unique per app (an app cannot reuse the same identifier for two of its extensions), but the same value may be used by different apps.
• Blank or whitespace-only values are treated as not provided.
• It is exposed on the AppExtension GraphQL type via the identifier field.

The main use case is opening a POPUP extension from a WIDGET of the same app: the widget dispatches the OpenPopup App Bridge action with extensionIdentifier set to the popup’s identifier.

Target types

App extensions provide four different types of targets, that control the behavior and rendering in the Dashboard. If target is not set, POPUP will be used as a default.

POPUP target

This target is meant to render an app iframe on the modal view. The provided url will be used to render app’s page. This UI renders medium-sized frame

This target doesn’t provide any options

APP_PAGE target

The APP_PAGE target works as a redirection from the mount location to the apps/ section in the Dashboard. This section renders the app in the biggest possible frame.

This target doesn’t provide any options

NEW_TAB target (from 3.22)

The NEW_TAB target is meant to open the provided url in the new browser tab. This can be helpful, for example, to connect 3-rd party services with Dashboard.

There are following options available

"options": {
  "newTabTarget": {
    "method": "GET" // or "POST"
  }
}

If not provided, the default value GET will be used by Dashboard.

• GET will open the URL similar to user opening the link in the new tab. Dashboard will append query params: saleorApiUrl and context fields (see “Context” below)
• POST will open the URL using POST method. This is similar to submitting the HTML form by the user. The body will contain following fields:
  • saleorApiUrl - the URL of the saleor (starting with https, ending with /graphql/)
  • appId - ID of the app object
  • accessToken - short-living token that is intersection of app and logged user permissions
  • context fields — see below

WIDGET target (from 3.22)

The WIDGET target stands for statically mounted iframes in various places around the dashboard. It will mount the frame similar to APP_PAGE and POPUP, but usually much smaller.

On *_DETAILS_WIDGETS mounts (for example, the product details sidebar), widgets are stacked in a scrollable column. An app can report its content height via the widgetResize App Bridge action so each iframe grows or shrinks with the UI instead of staying in a fixed box — see Sizing sidebar widgets (@saleor/app-sdk 1.9+).

Similar to NEW_TAB there are options allowing to choose the request method

"options": {
  "widgetTarget": {
    "method": "GET" // or "POST"
  }
}

If not provided, GET is the default choice for Dashboard.

• GET will open the URL similar to user opening the link in the new tab. Dashboard will append query params: saleorApiUrl and context fields (see “Context” below). Additional fields will be passed to the iframe, similar to APP_PAGE and POPUP, to help it render the UI (theme, feature flags, etc.)
• POST will open the URL using POST method. This is similar to submitting the HTML form by the user. The body will contain the following fields:
• saleorApiUrl - the URL of the saleor (starting with https, ending with /graphql/)
• appId - ID of the app object
• accessToken - short-living token that is intersection of app and logged user permissions. This token will be refreshed by the Dashboard in the background.
• context fields — see below

Home page widgets (from 3.23)

The HOMEPAGE_WIDGETS mount lets apps render widgets directly on the Dashboard home page. It uses the WIDGET target, but instead of widgetTarget it is configured with the homeWidgetTarget option:

"options": {
  "homeWidgetTarget": {
    "method": "GET", // or "POST"
    "fullscreen": false
  }
}

• method works the same as for other widgets. If not provided, GET is the default choice for Dashboard.
• fullscreen controls how the widget is laid out on the home page. When false (the default), the widget is rendered inside the home page grid alongside other widgets. When true, the widget takes the full available width.

Requires Dashboard 3.23.12+ and @saleor/app-sdk 1.10+.

Command palette actions (from 3.23.21)

The SEARCH_ACTION mount surfaces an app action in the Dashboard command palette (Cmd+K / Ctrl+K), so users can run it by typing instead of hunting for a button.

It supports the POPUP, APP_PAGE and NEW_TAB targets (not WIDGET). When the action is run from an entity page, the app receives that entity’s context — the same context the entity’s “more actions” extensions get.

{
  "label": "Recalculate taxes",
  "mount": "SEARCH_ACTION",
  "target": "POPUP",
  "permissions": ["MANAGE_ORDERS"],
  "url": "/actions/recalculate-taxes",
  "options": {
    "views": ["ORDER_DETAILS", "ORDER_LIST"],
    "aliases": ["taxes", "avatax"]
  }
}

options.views

Scopes the action to specific Dashboard views. When omitted, the action is available everywhere. When provided, the list must contain at least one view.

Detail views resolve a single entity id as context; list views are surfaced without an id.

Available views: PRODUCT_LIST, PRODUCT_DETAILS, ORDER_LIST, ORDER_DETAILS, DRAFT_ORDER_LIST, DRAFT_ORDER_DETAILS, CUSTOMER_LIST, CUSTOMER_DETAILS, COLLECTION_LIST, COLLECTION_DETAILS, CATEGORY_LIST, CATEGORY_DETAILS, GIFT_CARD_LIST, GIFT_CARD_DETAILS, VOUCHER_LIST, VOUCHER_DETAILS, DISCOUNT_LIST, DISCOUNT_DETAILS, PAGE_LIST, PAGE_DETAILS, PAGE_TYPE_LIST, PAGE_TYPE_DETAILS, MENU_LIST, MENU_DETAILS, CHANNEL_DETAILS.

CHANNEL_DETAILS requires Dashboard 3.23.28+; the extension is then opened with channelId holding the channel’s global id.

options.aliases

Extra terms the command palette matches the action against, for example ["taxes", "avatax"]. They are searchable but never displayed, which lets users find an action by the vendor or domain name instead of its exact label.

Requires Dashboard 3.23.28+.

Context

Context fields are specific to the mount extension is being attached to. For example, on CATEGORY_DETAILS_MORE_ACTIONS, the context field will be categoryId.

Context fields can be a string, usually an ID of the Saleor object, or a list of strings, usually when multiple Saleor items are selected by the user.

For example

• Order details page context will be {orderId: "AABBCC"}
• Product list page context will be {productIds: ["XXYYZZ", "BBCCDD"]}

Dashboard will provide contextual values depending on the mounting point. In the future more data can be passed to the context.

Context in GET operations

GET type operations, like rendering WIDGET using options.widget.method: "GET", or POPUP will provide context fields as query params in URL. Other data like theme or feature flags will be also provided.

You can access all the fields with JavaScript, like this:

const searchParams = new URLSearchParams(window.location.search);

console.log(
    Array.from(searchParams.entries())
)

Context in POST operations

POST type operations like target WIDGET or NEW_TAB with POST method, will provide context values within request body.

Since requests origin from the browser, they will be type of a form data. Your backend framework should provide a way to parse it.

Possible mounting places

Saleor requires extensions to define a mounting place. The table below explains all mounting locations currently supported by Saleor.

More resources

• app-template: minimal starter boilerplate, containing extensions example implementation