1 of 7

Workspaces

An overview of the available extension types related to workspaces.

Workspace Actions

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

Workspace actions are a set of functionalities or operations that can be performed within a workspace. These actions involve creating documents within the workspace, organizing and categorizing documents, publishing content and so on.

Workspace action relates to a workspace alias (Umb.Workspace.Document) and has Access to the workspace context.

JavaScript Manifest example

import { extensionRegistry } from '@umbraco-cms/extension-registry';
import { MyWorkspaceAction } from './my-workspace-action';

const manifest = {
 type: 'workspaceAction',
 alias: 'My.WorkspaceAction',
 name: 'My Workspace Action',
 meta: {
  label: 'My Action',
  api: MyWorkspaceAction,
 },
 conditions: [
  {
   alias: 'Umb.Condition.WorkspaceAlias',
   match: 'My.Workspace',
  },
 ],
};

extensionRegistry.register(manifest);

The Workspace Action Class

As part of the Extension Manifest you can attach a class that will be instantiated as part of the action. It will have access to the host element and the Workspace Context. When the action is clicked the execute method on the API class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements.

import { UmbWorkspaceActionBase } from '@umbraco-cms/backoffice/workspace';

export class MyWorkspaceAction extends UmbWorkspaceActionBase {
 execute() {
  this.workspaceContext.myAction(this.selection);
 }
}

Default Element

interface UmbWorkspaceActionElement {}

Workspace Context

Establish an extension to communicate across the application.

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

A Workspace context is a container for the data of a workspace. It is a wrapper around the data of the entity that the workspace is working on. It is responsible for loading and saving the data to the server. Workspace Contexts are used to bring additional context alongside the default context of a workspace.

A workspace context knows about its entity type (for example content, media, member, etc.) and holds its unique string (for example: key).
Most workspace contexts hold a draft state of its entity data. It is a copy of the entity data that can be modified at runtime and sent to the server to be saved.

If a workspace wants to utilize Property Editor UIs, then it must provide a variant context for the property editors. The variant-context is the generic interface between workspace and property editors.

interface UmbWorkspaceContext {}

Example of Workspace

Example of Workspace Context

The API will be initiated with the same host as the default Workspace Context.

{
    type: 'workspaceContext',
    alias: 'My.WorkspaceContext.Counter',
    name: 'My Counter Context',
    api: 'my-workspace-counter.context.js',
    conditions: [
        {
            alias: 'Umb.Condition.WorkspaceAlias',
            match: 'Umb.Workspace.Document',
        }
    ]
}

The code of such an API file could look like this:

import {
    UmbController,
    UmbControllerHost,
} from "@umbraco-cms/backoffice/controller-api";
import { UmbContextToken } from "@umbraco-cms/backoffice/context-api";
import { UmbNumberState } from "@umbraco-cms/backoffice/observable-api";

export class MyContextApi extends UmbController {
    #counter = new UmbNumberState(0);
    readonly counter = this.#counter.asObservable();

    constructor(host: UmbControllerHost) {
        super(host);
        this.provideContext(UMB_APP_CONTEXT, this);
    }

    increment() {
        this.#counter.next(this.#counter.value + 1);
    }
}

export const api = MyContextCounterApi;

Context APIs have to be self-providing. To do so it has to be an Umbraco Controller.

A Context Token for a Workspace Context Extension should look like this:

export const UMB_APP_CONTEXT = new UmbContextToken<MyContextCounterApi>(
    "UmbWorkspaceContext",
    "My.WorkspaceContext.Counter"
);

We recommend using UmbWorkspaceContext as the Context Alias for your Context Token. This will ensure that the requester only retrieves this Context if it's present at their nearest Workspace Context. Use the Extension Manifest Alias as the API Alias for your Context Token. For more information, see the Context API article.

Workspace Views

Append a view to any Workspace

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

Workspace Views was previously called Content Apps.

Workspace Views are customizable companion tabs with the ability to take place in any workspace.

In Content Section

With Workspace Views, editors can switch from editing 'Content' to accessing contextual information related to the item they are editing.

The default workspace view is 'Info' - displaying Links, History and Status of the current content item.

Example of a Workspace View

Create a manifest file named umbraco-package.json at the root of the welcome-dashboard folder. Here we define and configure our dashboard.
Add the following code to umbraco-package.json:

Add the following code to the existing my-element.ts from the srcfolder:

In the workspaceview folder run npm run build and then run the project. Then in the content section of the Backoffice you will see our new Workspace View:

To see the Workspace View that we have created in the content section, first you will need to have some content created.

Modals

A modal is a popup layer that darkens the surroundings and comes with a focus lock. There are two types of modals: "dialog" and "sidebar".

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

The Dialog modal appears in the middle of the screen. and the Sidebar Modal slide in from the right.

For type safety, we recommend that you use Modal Tokens. The Modal Token binds the Modal Type with a Modal Data Type and a Modal Result Type.

This can also come with defaults, for example, settings for the modal type and size.

This is an example of a Modal Token declaration:

import { UmbModalToken } from "@umbraco-cms/backoffice/modal";

export type OurSomethingPickerModalData = {
    // We do not have any data to parse for this example
};

export type OurSomethingPickerModalValue = {
    key: string;
};

export const MY_SOMETHING_PICKER_MODAL = new UmbModalToken<
    OurSomethingPickerModalData,
    OurSomethingPickerModalValue
>("Our.Modal.SomethingPicker", {
    modal: {
        type: "sidebar",
        size: "small",
    },
});

To create your own modal, read the Implementing a Custom Modal article before proceeding with this article.

Basic Usage

Consume the UMB_MODAL_MANAGER_CONTEXT and then use the modal manager context to open a modal. This example shows how to consume the Modal Manager Context:

import { LitElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import {
    UMB_MODAL_MANAGER_CONTEXT,
} from "@umbraco-cms/backoffice/modal";

export class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
            // modalManagerContext is now ready to be used.
        });
    }
}

A modal can be opened in two ways. Either you register the modal with a route or at runtime open the modal. The initial option allows users to deep-link to the modal, a potential preference in certain cases; otherwise, consider the latter.

In this case, we use the Modal Token from above, this takes a key as its data. And if submitted then it returns the new key.

const modalContext = this.#modalManagerContext?.open(this, MY_SOMETHING_PICKER_MODAL, {
    value: {
        key: this.selectedKey,
    },
});

modalContext
    ?.onSubmit()
    .then((value) => {
        this.selectedKey = value.key;
    })
    .catch(() => undefined);

See the implementing a Confirm Dialog for a more concrete example.

Modal Route Registration

You can register modals with a route, making it possible to link directly to that specific modal. This also means the user can navigate back and forth in the browser history. This makes it an ideal solution for modals containing an editorial experience.

For a more concrete example, check out the Implementing a Confirm Dialog article.

Confirm Dialog

Ask the user for confirmation

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

This example shows how to open a confirm dialog. The UMB_CONFIRM_MODAL is a token that represents the confirm dialog. The open method takes the token and an object with the data for the confirm dialog. The onSubmit method returns a promise that resolves when the user confirms the dialog and rejects when the user cancels the dialog.

The confirm modal itself is built-in and does not need to be registered in the extension registry.

The modal token describes the options that you can pass to the modal. The confirm modal token has the following properties:

headline - The headline of the modal.
content - The content of the modal, which can be a TemplateResult or a string.
color - (Optional) The color of the modal. This can be positive or danger.
confirmLabel - (Optional) The label of the confirm button.

Basic Usage

my-element.ts

import { html, LitElement, customElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UMB_MODAL_MANAGER_CONTEXT, UMB_CONFIRM_MODAL } from '@umbraco-cms/backoffice/modal';

@customElement('my-element')
export class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
        });
    }

    #onRequestDisable() {
        const modalContext = this.#modalManagerContext?.open(
            this, UMB_CONFIRM_MODAL,
            {
                data: {
                    headline: `${this.localize.term("actions_disable")}`,
                    content: `${this.localize.term(
                        "defaultdialogs_confirmdisable"
                    )}`,
                    color: "danger",
                    confirmLabel: "Disable",
                }
            }
        );
        modalContext
            ?.onSubmit()
            .then(() => {
                console.log("User has approved");
            })
            .catch(() => {
                console.log("User has rejected");
            });
    }

    render() {
        return html`<uui-button
                            look="primary"
                            color="danger"
                            @click=${this.#onRequestDisable}
                            label=${this.localize.term("actions_disable")}></uui-button>`;
    }
}

Custom Modals

New modals can be added to the system via the extension registry. This article goes through how this is done.

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

There are two parts to creating a custom modal:

First, you need to create a modal element which you need to register in the extension registry.
Second, you need to create and export a modal token.

A modal token is a string that identifies a modal. This is the modal extension alias. It is used to open a modal and is also to set default options for the modal. It should also have a unique alias to avoid conflicts with other modals.

import { UmbModalToken } from "@umbraco-cms/backoffice/modal";

export type MyModalData = {
    headline: string;
}

export type MyModalValue = {
    myData: string;
}

export const MY_MODAL_TOKEN = new UmbModalToken<MyModalData, MyModalValue>('My.Modal', {
    modal: {
        type: 'sidebar',
        size: 'small'
    }
});

A modal token is a generic type that takes two type arguments. The first is the type of the data that is passed to the modal when it is opened. The second is the type of the value that is returned when the modal is closed.

A modal element is a web component that is used to render the modal. It should implement the UmbModalExtensionElement interface. The modal context is injected into the element when the modal is opened in the modalContext property. The modal context is used to close the modal, update the value and submit the modal.

Additionally, the modal element can see its data parameters through the modalContext property. In this example, the modal data is of type MyModalData and the modal value is of type MyModalValue. The modal context is of type UmbModalContext<MyModalData, MyModalValue>. We are using the data to render a headline and the value to update the value and submit the modal.

my-modal.element.ts

import { html, LitElement, property, customElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
import type { UmbModalContext } from "@umbraco-cms/backoffice/modal";
import type { MyModalData, MyModalValue } from "./my-modal.token.ts";
import { UmbModalExtensionElement } from "@umbraco-cms/backoffice/extension-registry";

@customElement('my-dialog')
export default class MyDialogElement
    extends UmbElementMixin(LitElement)
    implements UmbModalExtensionElement<MyModalData, MyModalValue> {

    @property({ attribute: false })
    modalContext?: UmbModalContext<MyModalData, MyModalValue>;

    @property({ attribute: false })
    data?: MyModalData;

    private _handleCancel() {
        this.modalContext?.submit();
    }

    private _handleSubmit() {
        this.modalContext?.updateValue({ myData: "hello world" });
        this.modalContext?.submit();
    }

    render() {
        return html`
            <div>
                <h1>${this.modalContext?.data.headline ?? "Default headline"}</h1>
                <button @click=${this._handleCancel}>Cancel</button>
                <button @click=${this._handleSubmit}>Submit</button>
            </div>
        `;
    }
}

Register in the extension registry

The modal element needs to be registered in the extension registry. This is done by defining the modal in the manifest file. The element property should point to the file that contains the modal element.

{
    "type": "modal",
    "alias": "My.Modal",
    "name": "My Modal",
    "element": "../path/to/my-modal.element.js"
}

To open the modal, you need to consume the UmbModalManagerContext and then use the modal manager context to open a modal. This example shows how to consume the Modal Manager Context:

my-element.ts

import { MY_MODAL_TOKEN } from './my-modal.token';
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-element')
class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
            // modalManagerContext is now ready to be used.
        });
    }

    render() {
        return html`
            <uui-button look="primary" label="Open modal" @click=${this._openModal}></uui-button>
        `;
    }

    private _openModal() {
        this.#modalManagerContext?.open(this, MY_MODAL_TOKEN, {
            data: {
                headline: "My modal headline",
            },
        });
    }
}

Custom Modals

New modals can be added to the system via the extension registry. This article goes through how this is done.

This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice.

There are two parts to creating a custom modal:

First, you need to create a modal element which you need to register in the extension registry.
Second, you need to create and export a modal token.

import { UmbModalToken } from "@umbraco-cms/backoffice/modal";

export type MyModalData = {
    headline: string;
}

export type MyModalValue = {
    myData: string;
}

export const MY_MODAL_TOKEN = new UmbModalToken<MyModalData, MyModalValue>('My.Modal', {
    modal: {
        type: 'sidebar',
        size: 'small'
    }
});

my-modal.element.ts

import { html, LitElement, property, customElement } from "@umbraco-cms/backoffice/external/lit";
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
import type { UmbModalContext } from "@umbraco-cms/backoffice/modal";
import type { MyModalData, MyModalValue } from "./my-modal.token.ts";
import { UmbModalExtensionElement } from "@umbraco-cms/backoffice/extension-registry";

@customElement('my-dialog')
export default class MyDialogElement
    extends UmbElementMixin(LitElement)
    implements UmbModalExtensionElement<MyModalData, MyModalValue> {

    @property({ attribute: false })
    modalContext?: UmbModalContext<MyModalData, MyModalValue>;

    @property({ attribute: false })
    data?: MyModalData;

    private _handleCancel() {
        this.modalContext?.submit();
    }

    private _handleSubmit() {
        this.modalContext?.updateValue({ myData: "hello world" });
        this.modalContext?.submit();
    }

    render() {
        return html`
            <div>
                <h1>${this.modalContext?.data.headline ?? "Default headline"}</h1>
                <button @click=${this._handleCancel}>Cancel</button>
                <button @click=${this._handleSubmit}>Submit</button>
            </div>
        `;
    }
}

Register in the extension registry

{
    "type": "modal",
    "alias": "My.Modal",
    "name": "My Modal",
    "element": "../path/to/my-modal.element.js"
}

To open the modal, you need to consume the UmbModalManagerContext and then use the modal manager context to open a modal. This example shows how to consume the Modal Manager Context:

my-element.ts

import { MY_MODAL_TOKEN } from './my-modal.token';
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-element')
class MyElement extends UmbElementMixin(LitElement) {
    #modalManagerContext?: typeof UMB_MODAL_MANAGER_CONTEXT.TYPE;

    constructor() {
        super();
        this.consumeContext(UMB_MODAL_MANAGER_CONTEXT, (instance) => {
            this.#modalManagerContext = instance;
            // modalManagerContext is now ready to be used.
        });
    }

    render() {
        return html`
            <uui-button look="primary" label="Open modal" @click=${this._openModal}></uui-button>
        `;
    }

    private _openModal() {
        this.#modalManagerContext?.open(this, MY_MODAL_TOKEN, {
            data: {
                headline: "My modal headline",
            },
        });
    }
}

Workspaces

Workspace Actions

The Workspace Action Class

Workspace Context

Example of Workspace

Example of Workspace Context

Workspace Views

Example of a Workspace View

Modals

Modal Types

Modal Token

Make a custom Modal Element

Basic Usage

Open a modal

Directly open a Modal

Confirm Dialog

Basic Usage

Custom Modals

Create a modal token

Create a modal element

Register in the extension registry

Open the modal

Workspaces

Workspace Context

Example of Workspace

Example of Workspace Context

Modals

Modal Types

Modal Token

Make a custom Modal Element

Basic Usage

Open a modal

Directly open a Modal

Custom Modals

Create a modal token

Create a modal element

Register in the extension registry

Open the modal

Confirm Dialog

Basic Usage

Workspace Actions

The Workspace Action Class

Workspace Views

Example of a Workspace View