The extension registry is the center piece of the Backoffice UI. It holds information about most of the Backoffice UI, as most are extensions. This includes the built-in UI. The registry can be manipulated at any time, meaning you can add or remove extensions at runtime.

To provide new UI to the backoffice, you must register them via an Extension Manifest. This can be initiated via an Umbraco Package JSON file on the server. This will be your starting point.

Declaring a new extension is done by declaring an extension manifest. This can be done in one of two ways:

1. Via a manifest JSON file on the server.

2. In a JavaScript/TypeScript file.

These two options can be combined as you like.

A typical use case of such is achieved by registering a single extension manifest in your Umbraco Package JSON file. This manifest would then load a JS file, that registers the rest of your extensions. Learn more about these abilities in the bundle or backoffice entry point articles.

A header app appears next to the user profile and global search icon on the top-right corner of Umbraco's backoffice.

In this article, you can find an example of an extension registry. This example details the creation of a Header App in two ways, similar to how the extension registry can be created:

1. .

2. .

Button Header App with Manifest

Below you can find an example of how to setup a Header App using the manifest file.

2. Create a manifest file named umbraco-package.json at the root of the header-app folder. Here we define and configure our dashboard.

3. Add the following code to umbraco-package.json:

• First we define the type which is a headerApp. Then we add a unique alias and a name to define the extension UI.

• Then we can define what kind of extension it is, where in this case we can use a pre-defined element called button.

• The button requires some metdata: an icon, label of the button (name of the button) and a link which opens once clicked.

1. In the header-app folder run npm run build and then run the project. Then in the backoffice you will see our new Header App extension with heart icon:

Button Header App with JS/TS

Below you can find an example of how to setup a Header App using the TypeScript file.

This is a continuation of the above steps from the Button Header App with Manifest example. We will register a new Header App directly from the .ts file.

1. Add a reference to the .js file. Update the umbraco-package.json with the following:

1. Replace the content of the src/my-element.ts file with the following:

1. In the header-app folder run npm run build and then run the project. Then in the backoffice you will see our new Header App extension with address book icon:

Extension Manifest

Extension Manifest

The Extension Manifest is the point of entry for any extension. This is the declaration of what you want to register.

The content in this section describes all the extension types that the Backoffice supports. Find a list of the most common types in the article.

Extension Manifest Format

An Extension Manifest can be written either as a JavaScript Object or a JSON Object.

There are a few general properties, the required set of properties consists of the type, alias, and name.

The type defines what it is declaring The alias is a unique identifier for this manifest. It must be globally unique, so make sure to prefix it with something that makes your extension unique. The name is a representational name of this manifest, this does not need to be unique but such can be beneficial when debugging extensions.

Manifest Data

Each Extension Manifest has to declare its type. This is used to determine where it hooks into the system. It also determines what data is required of this manifest.

The abilities of the extensions rely on the specific extension type. The Type sets the scene for what the extension can do and what it needs to be utilized. Some extension types can be made purely via the manifest. Other requires files, like a JavaScript file containing a Web Component.

The required fields of any extension manifest are:

• type - The type defines the type and purpose of the extension. It is used to determine where the extension will be used and defines the data needed for this manifest.

• alias- The alias is used to identify the extension. This has to be unique for each extension.

• name - The name of the extension. This is used to identify the extension in the UI.

Additionally, many extensions support the use of the following fields:

• weight - Define a weight, to determine the importance or visual order of this extension.

Many of the Extension Types require additional information declared as part of a meta field.

Registration

An Extension Manifest can be declared in multiple ways.

Additionally, two Extension types can be used to register other extensions.

The bundle extension type

The Bundle extension type can be used for declaring multiple Extension Manifests with JavaScript in a single file.

The Bundle declares a single JavaScript file that will be loaded at startup. All the Extension Manifests exported of this Module will be registered in the Extension Registry.

The backofficeEntryPoint extension type

The backofficeEntryPoint extension type can run any JavaScript code at startup. This can be used as an entry point for a package.

The entry point declares a single JavaScript file that will be loaded and run when the Backoffice starts.

The entryPbackofficeEntryPointoint extension is also the way to go if you want to load in external libraries such as jQuery, Angular, or React. You can use the backofficeEntryPoint type to load in the external libraries to be shared by all your extensions. Loading global CSS files can also be used in the backofficeEntryPoint extension.

Registration via any JavaScript code

Alternatively, an Extension Manifest can be declared in JavaScript at any given point.

The following example shows how to register an extension manifest via JavaScript code:

This article describes how to add and use more icons in your UI.

Register a new set of icons

New icons can be added via an extension type called icons.

You must add a new manifest to the Extension API to register icons. The manifest can be added through the umbraco-package.json file as shown in the snippet below.

{
  "name": "MyPackage",
  "extensions": [
    {
      "type": "icons",
      "alias": "MyPackage.Icons.Unicorn",
      "name": "MyPackage Unicorn Icons",
      "js": "/App_Plugins/MyPackage/Icons/icons.js"
    }
  ]
}

The file set in the js field holds the details about your Icons. The file should resemble the following:

export default [
    {
        name: "myPackage-unicorn",
        path: () => import("./icon-unicorn.js"),
    },
    {
        name: "myPackage-giraffe",
        path: () => import("./icon-giraffe.js"),
    }
]

The icon name needs to be prefixed to avoid collision with other icons.

Each icon must define a path, either as a string or a dynamic import as shown above. This file must be a JavaScript file containing a default export of an SVG string. See an example of this in the code snippet below.

export default `<svg ...></svg>`;

Using Icons in your UI

The umb-icon element is automatically able to consume any registered icon.

The following example shows how to make a button using the above-registered icon.

<uui-button compact label="Make the unicorn dance">
    <umb-icon name="myPackage-unicorn"></umb-icon>
</uui-button>

Most of BackOffice is based on Extensions making it crucial to understand how to register your own extensions. This introduction will give you an outline of the abilities of the extension registry.

Extension Registration

The extension registry is a global registry that can be accessed and changed at anytime while Backoffice is running.

Extension Manifest

Each Extension Manifest has to declare its type, this is used to determine where it hooks into the system. It also looks at what data is required to declare within it.

Extension Types

Extension Conditions

Most extension types support conditions. Defining conditions enables you to control when and where the extension is available.

Kinds

The kinds feature enables you to base your extension registration on a preset. A kind provides the base manifest that you like to extend.

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

Entry Point

The Entry Point manifest type is used to register an entry point for the backoffice. An entry point is a single JavaScript file that is loaded when the backoffice is initialized. This file can be used to do anything, this enables more complex logic to take place on startup.

Bundle

The bundle extension type enables you to gather many extension manifests into one.

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.

Create 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.

Create a modal element

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.

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"
}

Open the modal

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:

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",
            },
        });
    }
}

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.

A modal can be registered via the UmbModalRouteRegistrationController. The registration accepts a modal token (or extension alias).

this.myModalRegistration = new UmbModalRouteRegistrationController(
    this,
    UMB_LINK_PICKER_MODAL
)
    .onSubmit((submitData) => {
        console.log("Modal submitted with data".submitData);
    })
    .observeRouteBuilder((routeBuilder) => {
        this._modalRouteBuilder = routeBuilder;
    });

The registration holds an instance of its UmbModalHandler when the modal is active. The modal registration accepts 4 different callbacks:

• onSetup - called when the modal is opened

• onSubmit - called when the modal is submitted

• onReject - called when the modal is rejected

• observeRouteBuilder - called when the modal route changes. Use the given route builder to build a route to open the modal

Additional features of the route Registration:

• Adds unique parts to the path.

• A modal registered in a dashboard can be setup in few steps

• A modal registered in a property editor needs to become specific for the property and the variant of that property.

• Builds some data for the setup.

• Rejects a modal by returning false in setup.

• Uses a parameter as part of the setup to determine the data going to the modal.

Modal registration for UI as part of a Property Editor

When configuring a routed modal from a Property Editor, it's important to be aware of some facts. Those facts are that the Property Editor shares the same URL path as other Property Editors. This means we need to ensure the registration is unique so it doesn't collide with other Property Editors. To do so we will make use of the Property Alias and the Variant ID.

	@property()
	public set alias(value: string | undefined) {
		this.myModalRegistration.setUniquePathValue('propertyAlias', value);
	}

	@property()
	public set variantId(value: string | UmbVariantId | undefined) {
		this.myModalRegistration.setUniquePathValue('variantId', value?.toString());
	}

	private _items = [
		{ name: 'Item 1' },
		{ name: 'Item 2' },
		{ name: 'Item 3' },
	]


	constructor() {
		super();

		this.myModalRegistration = new UmbModalRouteRegistrationController(
			this,
			MY_MODAL_TOKEN
		)
		.addAdditionalPath(`:index`)
		.addUniquePaths(['propertyAlias', 'variantId'])
		.onSetup((params) => {
			// Get item index:
			const indexParam = params.index;
			if (!indexParam) return false;
			let index: number | null = parseInt(params.index);
			if (Number.isNaN(index)) return false;

			// Use the index to find data:
			let data = null;
			if (index >= 0 && index < this._items.length) {
				data = this._items[index];
			} else {
				// If not then make a new pick:
				index = null;
			}

			return {
				index: index,
				itemData: {
					name: data?.name
				},
			};
		})
		.onSubmit((submitData) => {
			if (!submitData) return;
			this._items[submitData.index] = submitData.itemData;
		})
		.observeRouteBuilder((routeBuilder) => {
			this._modalRouteBuilder = routeBuilder;
		});
	}

	render() {
		return html`
			${this._items?.map((item, index) =>
				html`<uui-button look="placeholder" label="Edit item ${index}" .href=${this._modalRouteBuilder?.({ index })}>Add</uui-button>`
			)}
		`;
	}

Generate the URL to a Modal Route Registration

The Modal registration has an option to retrieve a URL Builder. This is a function that can be used to generate a URL to a modal:

const modalLink = _myUrlBuilder?.({ alias: "my-input-alias" });

The modalLink from above could look like this: /umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-input-alias

Notice the Property Editor registration will add the property alias and variant ID to the URL, so it becomes:

/umbraco/backoffice/my/location/modal/Our.Modal.SomethingPicker/my-property-alias/en-us/my-input-alias

Menu

Creating a custom menu

In this section, you can learn how to register and create a custom Menu for the Umbraco backoffice.

Manifest

The manifest file can be created using either JSON or TypeScript. Both methods are shown below.

{
 "type": "menu",
 "alias": "My.Menu",
 "name": "My Menu"
}

import { ManifestMenu } from "@umbraco-cms/backoffice/extension-registry";

const menuManifest: Array<ManifestMenu> = [
    {
        type: 'menu',
        alias: 'My.Menu',
        name: 'My Menu'
    }
];

Menu Item

Menu items are the items that appear in the menu.

Creating a custom menu items

In this section, you can learn how to add custom Menu Items to your Umbraco backoffice Menu.

Manifest

To add custom menu items, you can define a single MenuItem manifest and link an element to it. In this element, you can fetch the data and render as many menu items as you want based on that data.

The code snippets below show how to declare a new menu item using JSON or TypeScript.

{
 "type": "menuItem",
 "alias": "My.MenuItem",
 "name": "My Menu Item",
 "element": "./menu-items.ts",
 "meta": {
  "label": "My Menu Item",
  "menus": ["My.Menu"]
 }
}

const menuItemManifest: Array<ManifestMenuItem> = [
    {
        type: 'menuItem',
        alias: 'My.MenuItem',
        name: 'My Menu Item',
        meta: {
            label: 'My Menu Item',
            menus: ["My.Menu"]
        },
        element: () => import('./menu-items.ts')
    }
];

The UI Element

Rendering menu items with Umbraco's UI menu item component

To render your menu items in Umbraco, you can use the Umbraco UI Menu Item component. This component allows you to create nested menu structures with a few lines of code.

By default, you can set the has-children attribute to display the caret icon indicating nested items. It will look like this: ?has-children=${bool}.

Example:

<uui-menu-item label="Menu Item 1" has-children>
    <uui-menu-item label="Nested Menu Item 1"></uui-menu-item>
    <uui-menu-item label="Nested Menu Item 2"></uui-menu-item>
</uui-menu-item>

Custom menu item element example

You can fetch the data and render the menu items using the Lit element above. By putting the result of the fetch in a @state(), we can trigger a re-render of the component when the data is fetched.

import { UmbMenuItemElement } from '@umbraco-cms/backoffice/extension-registry';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { html, TemplateResult } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { MyMenuItemResponseModel, MyMenuResource } from '../../../api';

const elementName = 'my-menu-item';

@customElement(elementName)
class MyMenuItems extends UmbLitElement implements UmbMenuItemElement {
    @state()
    private _items: MyMenuItemResponseModel[] = []; // Store fetched items
    @state()
    private _loading: boolean = true; // Track loading state
    @state()
    private _error: string | null = null; // Track any errors

    constructor() {
        super();
        this.fetchInitialItems(); // Start fetching on component load
    }

    // Fetch initial items
    async fetchInitialItems() {
        try {
            this._loading = true;
            this._items = ((await MyMenuResource.getMenuApiV1()).items); // Fetch root-level items
        } catch (e) {
            this._error = 'Error fetching items';
        } finally {
            this._loading = false;
        }
    }

    // Render items
    renderItems(items: MyMenuItemResponseModel[]): TemplateResult {
        return html`
            ${items.map(element => html`
                <uui-menu-item label="${element.name}" ?has-children=${element.hasChildren}>
                ${element.type === 1 
                ? html`<uui-icon slot="icon" name="icon-folder"></uui-icon>` 
                : html`<uui-icon slot="icon" name="icon-autofill"></uui-icon>`}
                    <!-- recursively render children -->
                    ${element.hasChildren ? this.renderItems(element.children) : ''}
                </uui-menu-item>
            `)}
        `;
    }

    // Main render function
    render() {
        if (this._loading) {
            return html`<uui-loader></uui-loader>`;
        }

        if (this._error) {
            return html`<uui-menu-item active disabled label="Could not load form tree!">
        </uui-menu-item>`;
        }

        // Render items if loading is done and no error occurred
        return html`${this.renderItems(this._items)}`;
    }
}

export { MyMenuItems as element };

declare global {
    interface HTMLElementTagNameMap {
        [elementName]: MyMenuItems;
    }
}

Tree Menu Item

Manifest

// it will be something like this
{
 "type": "menuItem",
 "kind": "tree",
 "alias": "My.TreeMenuItem",
 "name": "My Tree Menu Item",
 "meta": {
  "label": "My Tree Menu Item",
  "menus": ["My.Menu"]
 }
}

Default Element

// get interface
interface UmbTreeMenuItemElement {}

Adding menu items to an existing menu

The backoffice comes with a couple of menus.

• Content, Media, Settings, Templating, Dictionary, etc.

To add a menu item to an existing menu, you can use the meta.menus property.

{
 "type": "menuItem",
 "alias": "My.MenuItem",
 "name": "My Menu Item",
 "meta": {
  "label": "My Menu Item",
  "menus": ["Umb.Menu.Content"]
 }
}

The Backoffice architecture is based on Extensions, making different UI parts extendable. Enabling you to append, replace, or remove parts.

You are not limited to any specific tech stack. UI Elements are based on Web Components and the Backoffice APIs are based on native code.

In this section you can find the common terms, concepts and guides used to extend the Umbraco backoffice.

Extension Registry

An overview of concepts on how to work with extension registration when extending the backoffice.

Extension Types

An overview of concepts on how to work with extension types when extending the backoffice.

The bundle extension type enables you to gather many extension manifests into one.

It points to a single JavaScript file that via JavaScript Modules, exports or re-exports Extension Manifests written in JavaScript.

It can be used as the entry point for a package, or as a grouping for a set of manifests.

Use Bundle as an entry point for a package

If you want to declare your manifests in JavaScript/TypeScript, the Bundle is a great choice.

The following example shows an umbraco-package.json that refers to one bundle, which can then declare manifests.

Kind

A kind is matched with a specific type. When another extension uses that type and kind it will inherit the preset manifest of the kind extension.

The registration of Kinds is done in the same manner as the registration of other extensions. But the format of it is different. Let's take a look at an example of how to implement the Kind registration for a Button Kind.

Understanding the Kind Extension

The root properties of this object define the Kind registration. Then the manifest property holds the preset for the extension using this kind to be based upon. This object can hold the property values that make sense for the Kind.

For the kind to be used, it needs to match up with the registration of the extension using it. This happens when the extension uses a type, which matches the value of matchType of the Kind. As well the extension has to utilize that kind, by setting the value of kind to the value of matchKind the Kind.

Kind example

In the following example, a kind is registered. This kind provides a default element for extensions utilizing this kind.

This enables other extensions to use this kind and inherit the manifest properties defined in the kind.

In this example a Header App is registered without defining an element, this is possible because the registration inherits the elementName from the kind.

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

Entity Bulk Action: Relates to an entity type: document, media, etc. Performs the action on a selection of items.

Registering an Entity Bulk Action

The Entity Bulk 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, a repository with the given alias and the unique (key etc) of the entity. 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.

Entity Actions is a feature that provides a generic place for secondary or additional functionality for an entity type. An entity type can be a media, document and so on.

Items in an Umbraco Tree can have associated Actions. The actions visible to the currently logged in user can be controlled via User Permissions.

You can set a User's permissions for each item in the Umbraco Content tree from the User Section of the Umbraco Backoffice.

If you are developing a custom section or a custom Dashboard, you might want to display some different options. This depends on a User's permission set on a particular item.

Entity Actions in the UI

Sidebar Context Menu

Sidebar Context Menu is an entity action that can be performed on a menu item. For example in the content section you can perform some extra actions on the content such as sorting, moving, etc.

Registering an Entity Action

Default Element

The Entity Action Class

As part of the Extension Manifest you can attach a class that will be instanciated as part of the action. It will have access to the host element, a repository with the given alias and the unique (key etc) of the entity.

The class either provides a getHref method, or an execute method. If the getHref method is provided, the action will use the link. Otherwise the execute method will be used. 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.

Example of providing a getHref method:

Example of providing a execute method:

If any additional contexts are needed, these can be consumed from the host element:

We currently have a couple of generic actions that can be used across silos, so we don't have to write the same logic again. These actions include copy, move, trash, delete, etc. We can add more as we discover the needs.

User Permission Codes

Here is a list of the entity actions and associated user permission codes shipped by Umbraco CMS and add-on projects, such as Umbraco Deploy. This list also includes codes used by some community packages.

If you are building a package or adding custom entity actions to your solution, it's important to pick a permission letter. Ensure that it doesn't clash with one of these.

Currently, we allow two extension points on the client for user permissions:

• Entity User Permissions - Relates to an entity (example document).

• Granular User Permission - Relates to a $type server schemaType.

Each permission comes with a set of verbs, that will be checked against client and server-side.

The Core currently ships with entity user permission for documents. The permissions are as follows:

Entity User Permissions will be registered in the extension registry with a manifest with the following type. Example:

Granular permissions will also be registered. It is possible to provide a custom element to build the needed UX for that type of permission:

The backofficeEntryPoint extension type can be used to run some JavaScript code at startup. The entry point declares a single JavaScript file that will be loaded and run when the Backoffice starts. In other words this can be used as an entry point for a package.

The backofficeEntryPoint extension is also the way to go if you want to load in external libraries such as jQuery, Angular, React, etc. You can use the backofficeEntryPoint to load in the external libraries to be shared by all your extensions. Additionally, global CSS files can also be used in the backofficeEntryPoint extension.

The Entry Point manifest type is used to register an entry point for the backoffice. An entry point is a single JavaScript file that is loaded when the backoffice is initialized. This file can be used to do anything, this enables more complex logic to take place on startup.

Register an entry point in the umbraco-package.json manifest

Register additional UI extensions in the entry point file

Each section of the Umbraco backoffice has its own set of default dashboards. Your own custom sections can show dashboards, and you can create your own custom dashboards for existing sections.

The dashboard area of Umbraco is used to display an "editor" for the selected item in the tree. If no item is selected, then the default set of section dashboards is shown in the dashboard area.

Notice that is another similar approach to append information to the root of a Section. Section views are thought mainly to be used as Secondary pages. These two approaches should ideally not be combined.

Default Dashboards in Umbraco

The default dashboards in Umbraco are the ones that are displayed when you first enter a section in the backoffice. These dashboards are used to display information and functionality that is relevant to the section you are in.

The default sections in Umbraco are:

Here is a table of the default dashboards in Umbraco and the sections they are used including their aliases:

Even though these dashboards are useful, you might want to create your own custom dashboard to display specific information or functionality.

Registering your Dashboard

This section dives into the Dashboard Extension Manifest, shows how to register one, and append additional details.

Example Extension Manifest

Insert this as an entry in the extensions list in a umbraco-package.json file.

This will register a dashboard with the alias my.welcome.dashboard and the name My Welcome Dashboard. The dashboard will be loaded from the file /App_Plugins/WelcomeDashboard/dashboard.js. The dashboard will be displayed with the label Welcome Dashboard and the URL /welcome-dashboard on all sections, e.g. /section/content/dashboard/welcome-dashboard.

Conditions

This will make the dashboard only be displayed on the Content section.

Properties

The dashboard manifest can contain the following properties:

Full Example

Extension Conditions declare requirements that should be permitted for the extension to be available. Many, but not all, Extension Types support Conditions.

.

Built-in conditions types

The following conditions are available out of the box, for all extension types that support Conditions.

• Umb.Condition.SectionAlias - Requires the current Section Alias to match the one specified.

• Umb.Condition.MenuAlias - Requires the current Menu Alias to match the one specified.

• Umb.Condition.WorkspaceAlias - Requires the current Workspace Alias to match the one specified.

• Umb.Condition.WorkspaceEntityType - Requires the current workspace to work on the given Entity Type. Examples: 'document', 'block' or 'user'.

• Umb.Condition.WorkspaceContentTypeAlias - Requires the current workspace to be based on a Content Type which Alias matches the one specified.

• Umb.Condition.Workspace.ContentHasProperties - Requires the Content Type of the current Workspace to have properties.

• Umb.Condition.WorkspaceHasCollection - Requires the current Workspace to have a Collection.

• Umb.Condition.WorkspaceEntityIsNew - Requires the current Workspace data to be new, not yet persisted on the server.

• Umb.Condition.EntityIsTrashed - Requires the current entity to be trashed.

• Umb.Condition.EntityIsNotTrashed - Requires the current entity to not be trashed.

• Umb.Condition.SectionUserPermission - Requires the current user to have permissions to the given Section Alias.

• Umb.Condition.UserPermission.Document - Requires the current user to have specific Document permissions. Example: 'Umb.Document.Save'

Make your own conditions

You can make your own Conditions by creating a class that implements the UmbExtensionCondition interface.

This has to be registered in the extension registry, shown below:

Finally, you can make use of the condition in your configuration. See an example of this below:

As can be seen in the code above, we never make use of match. We can do this by replacing the timeout with some other check.

With all that in place, the configuration can look like shown below:

Modal Types

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

Modal Token

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:

Make a custom Modal Element

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:

Open a modal

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.

Directly open a Modal

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.

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.

A global context manages the logic code from your Lit Element controllers.

Registration of a Global Context

You can register a global context like so:

{
    type: 'globalContext',
    alias: 'My.GlobalContext.Products',
    name: 'My Products Context',
    api: 'my-products.context.js',
}

The tree is a hierarchical structure of nodes and is registered in the Backoffice extension registry. A tree can be rendered anywhere in the Backoffice with the help of the umb-tree element.

Creating trees

To Create a Tree in a section of the Umbraco backoffice, you need to take multiple steps:

Registering a tree

The backoffice comes with two different tree item kinds out of the box: entity and fileSystem.

Tree Manifest:

// TODO: add interface
{
 "type": "tree",
 "alias": "My.Tree.Alias",
 "name": "My Tree",
 "meta": {
  "repositoryAlias": "My.Repository.Alias"
 }
},
{
 "type": "treeItem",
   "kind": "entity",
 "alias": "My.TreeItem.Alias",
 "name": "My Tree Item",
   "conditions": {
  "entityType": "my-entity-type",
 },
}

Rendering a tree

<umb-tree alias="My.Tree.Alias"></umb-tree>

Render a Custom Tree Item

The Tree Item Manifest

{
 "type": "treeItem",
 "alias": "Umb.TreeItem.Alias",
 "name": "My Tree Item",
 "element": "./my-tree-item.element.js",
 "conditions": {
  "entityType": "my-entity-type",
 },
};

The Tree Item Element

import { css, html, nothing } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UmbMyTreeItemContext, MyTreeItemDataModel } from './my-tree-item.context';

@customElement('my-tree-item')
export class MyTreeItemElement extends UmbElementMixin(LitElement) {
 private _item?: MyTreeItemDataModel;
 @property({ type: Object, attribute: false })
 public get item() {
  return this._item;
 }
 public set item(value: MyTreeItemDataModel | undefined) {
  this._item = value;
  this.#context.setTreeItem(value);
 }

 #context = new UmbMyTreeItemContext(this);

 render() {
  if (!this.item) return nothing;
  return html` <umb-tree-item-base> Some custom markup </umb-tree-item-base>`;
 }
}

export default MyTreeItemElement;

The Tree Item Context

// TODO: auto-generate this from the interface
export interface UmbTreeItemContext<T> {
 host: UmbControllerHostElement;
 unique?: string;
 type?: string;

 treeItem: Observable<T | undefined>;
 hasChildren: Observable<boolean>;
 isLoading: Observable<boolean>;
 isSelectable: Observable<boolean>;
 isSelected: Observable<boolean>;
 isActive: Observable<boolean>;
 hasActions: Observable<boolean>;
 path: Observable<string>;

 setTreeItem(treeItem: T | undefined): void;

 requestChildren(): Promise<{
  data: PagedResponse<T> | undefined;
  error: ProblemDetails | undefined;
  asObservable?: () => Observable<T[]>;
 }>;
 toggleContextMenu(): void;
 select(): void;
 deselect(): void;
 constructPath(pathname: string, entityType: string, unique: string): string;
}