Analytics Widgets allow you to display custom charts and reports in the analytics section to track your important KPIs.

Registering an Analytics Widget

import { UcManifestAnalyticsWidget } from "@umbraco-commerce/backoffice";

export const manifests : UcManifestAnalyticsWidget[] = [
   {
        type: 'ucAnalyticsWidget',
        alias: 'Uc.AnalyticsWidget.TotalOrders',
        name: 'Total Orders',
        element: () => import('./total-orders-widget.element.js'),
        meta: {
            label: '#ucAnalytics_totalOrdersHeadline',
            description: '#ucAnalytics_totalOrdersDescription'
        }
    }
];

extensionRegistry.register(manifests);

Each entry must have a type of ucAnalyticsWidget along with a unique alias and name. An element key should be defined to import the implementation of the UcAnalyticsWidget component interface.

A meta entry provides configuration options for the widget

The Analytics Widget element

In order to define the UI for a widget, you'll need to define a component that implements the UcAnalyticsWidget interface. This interface is defined as

export interface UcAnalyticsWidget extends UmbControllerHostElement {
    storeId:string;
    manifest: UcManifestAnalyticsWidget;
    timeframe: UcAnalyticsTimeframe;
}

This provides widget implementations with access to the current storeId, the defined manifest, and the current selected timeframe for which the widget should show relevant data.

An example implementation would be

// total-orders-widget.element.js

import { customElement, html, property, state } from "@umbraco-cms/backoffice/external/lit";
import { UmbLitElement } from "@umbraco-cms/backoffice/lit-element";
import { UcAnalyticsTimeframe, UcAnalyticsWidget, UcManifestAnalyticsWidget } from "@umbraco-commerce/backoffice";

@customElement('uc-total-orders-widget')
export class UcTotalOrdersWidgetElement extends UmbLitElement implements UcAnalyticsWidget {

    @property({ type:String })
    storeId!:string;

    @property({ type: Object, attribute: false })
    manifest?: UcManifestAnalyticsWidget;

    @property({ type: Object, attribute: false })
    set timeframe(timeframe: UcAnalyticsTimeframe) {
        this._timeframe = timeframe;
        this.#fetchData();
    }
    private _timeframe?: UcAnalyticsTimeframe;

    @state()
    private _data?:any[];

    #fetchData = async () => {
        // Fetch data using this._timeframe properties as a filter
        // and store the result in this._data
    }

    render() {
        if (!this._data) return;
        return html`-- WIDGET MARKUP GOES HERE --`;
    }

}

export default UcTotalOrdersWidgetElement;

declare global {
    interface HTMLElementTagNameMap {
        'uc-total-orders-widget': UcTotalOrdersWidgetElement;
    }
}

When an alternative timeframe is selected from the widget dashboard, all widget's timeframe properties will be updated to re-fetch and render the widget.

With the use of Properties, Umbraco Commerce allows a lot of flexibility to capture whatever data you need to record against an Order. To complement that functionality, it is also possible to configure those properties to be editable within the backoffice UI.

Order Properties are defined as manifest entries in your umbraco-package.manifest.

"extensions": [
    {
        "type": "ucOrderProperty",
        "alias": "Uc.OrderProperty.FirstName",
        "name": "Customer FirstName",
        "weight": 400,
        "meta": {
            "propertyAlias": "firstName",
            "group": "Uc.OrderPropertyGroup.Customer",
            "editorUiAlias": "Umb.PropertyEditorUi.TextBox",
            "labelUiAlias": "Umb.PropertyEditorUi.Label"
        }
    }
]

Each entry must have a type of ucOrderProperty along with a unique alias and name. An optional forEntityTypes key can also be defined to control whether the property is visible on the Cart editor, or the Order editor, or both. The forEntityTypes is an array and can accept either or both of uc:cart or uc:order values.

A meta entry provides configuration options for the property

Order Property Groups

Order properties can be defined as one of the following to control where the property is displayed.

Localization

When displaying your properties in the backoffice UI it is necessary to provide localizable labels. This is controlled by Umbraco's UI Localization feature.

Umbraco Commerce will automatically look for the following entries:

Here {alias} is the property alias of a property.

Entity Quick Actions allow you to display a button directly in the entity editor screen for important actions that require instant access.

Registering a Quick Action

import { UcManifestEntityQuickAction } from "@umbraco-commerce/backoffice";

export const manifests : UcManifestEntityQuickAction[] = [
    {
        type: 'ucEntityQuickAction',
        kind: 'default',
        alias: 'My.EntityQuickAction.MyQuickAction',
        name: 'My Quick Action Action',
        weight: 300,
        api: () => import('./my-quick-action.api.js'),
        meta: {
            entityType: 'uc:order',
            label: "#quickActions_myQuickAction",
            look: 'primary'
        }
    }
];

extensionRegistry.register(manifests);

Each entry must have a type of ucEntityQuickAction along with a unique alias and name. Unless you wish to override the button, the kind key should be set to default. An api key should be defined that imports the implementation of the UcEntityQuickActionApi interface.

A meta entry provides configuration options for quick actions:

The Entity Quick Action API

In order to define the logic to perform when a quick action button is clicked, you'll need to implement the UcEntityQuickActionApi interface. This interface is defined as

export interface UcEntityQuickActionApi extends UmbApi {
    manifest: UcManifestEntityQuickAction;
    execute(): Promise<void>;
}

This provides quick action implementations with access to the defined manifest and expects the implementation of an execute method to act.

An example implementation would be

// my-quick-action.api.js

import { UcEntityQuickActionApi, UcManifestEntityQuickAction } from "@umbraco-commerce/backoffice";
import { UmbControllerBase } from "@umbraco-cms/backoffice/class-api";

export default class MyEntityQuickActionApi extends UmbControllerBase implements UcEntityQuickActionApi {
    manifest!: UcManifestEntityQuickAction;
    async execute() {
        console.log("You clicked the My Quick Action");
    }
}

Umbraco Commerce offers a number of UI extension points, from the ability to add custom quick actions, to adding custom order property editors. These UI extension points are designed to allow you to adjust Umbraco Commerce's behavior to more closely match the requirements of the store owner.

Umbraco Commerce offers the following UI extension points:

Define custom analytics widgets to display in the analytics dashboard

Define quick actions to display in the entity editor

Define properties to be editable in the cart/order editor

Define properties to display in the cart/order collection view

Define order line properties to be editable in the cart/order editor

Define custom menu items to display a store menu

With the use of , Umbraco Commerce allows a lot of flexibility to capture whatever data you need to record against an Order Line. To complement that functionality, it is also possible to configure those properties to be editable within the backoffice UI.

Order Properties are defined as manifest entries in your .

Each entry must have a type of ucOrderLineProperty along with a unique alias and name. An optional forEntityTypes key can also be defined to control whether the property is visible on the Cart editor, or the Order editor, or both. The forEntityTypes is an array and can accept either or both of uc:cart or uc:order values.

A meta entry provides configuration options for the property

Localization

Umbraco Commerce will automatically look for the following entries:

Here {alias} is the property alias of a property.

With the use of , Umbraco Commerce allows a lot of flexibility to capture whatever data you need to record against an Order. To complement that functionality, it is also possible to configure those properties to be displayed within the Orders collection view.

Order Collection Properties are defined as manifest entries in your .

Each entry must have a type of ucOrderCollectionProperty along with a unique alias and name. An optional forEntityTypes key can also be defined to control whether the property is visible on the Cart editor, or the Order editor, or both. The forEntityTypes is an array and can accept either or both of the uc:cart or uc:order values.

A meta entry provides configuration options for the property

Localization

Umbraco Commerce will automatically look for the following entries:

Here {alias} is the property alias of a property.

Store Menu Items allow you to display custom menu items inside a Store tree, either in the Settings or Commerce sections.

Registering a Store Menu Item

Each entry must have a type of ucStoreMenuItem along with a unique alias and name.

A meta entry provides configuration options for the menu item

Menu items are set to navigate to the following route on click

Here:

• {currentSection} is the current section you are in,

• {rootEntityType} is the entity type of the menu this item is a child of (should be one of uc:store-management or uc:store-settings),

• {rootUnique} is the ID of the Store this menu is for, and

• {entityType} is the entity type as defined in the menu items manifest meta data.

Handling Store Menu Item Requests

To handle requests to this endpoint, you should define a workspace manifest for the given entity type.