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 has to be initiated via an Umbraco Package JSON file on the server. This will be your starting point, which enables you to register one or more extensions.

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.

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. Here is a list of the most common types:

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 supports the use of the following fields:

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

• conditions - Define one or more conditions which must be permitted for the extension to become available. Extension Conditions.

• kind - Define a kind-alias of which this manifest should be based upon. Kinds acts like a preset for your manifest. Extension Kinds.

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

Registration

An Extension Manifest can be declared in multiple ways.

The primary way is to declare it as part of the Umbraco Package Manifest.

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

A typical use case is to declare one main Extension Manifest as part of the Umbraco Package Manifest. Such main Extension Manifest would be using one of the following types:

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.

Read more about the bundle extension type in the Bundle article.

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.

Read more about the backofficeEntryPoint extension type in the Entry Point article.

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:

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

const manifest = {
    type: '...',
    ...
};

umbExtensionsRegistry.register(extension);

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

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.

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

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.

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

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

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.

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

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.

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

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.

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.

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 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:

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

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.

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.

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.

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:

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

{
    "name": "Name of your package",
    "extensions: [
        {
         "type": "backofficeEntryPoint",
         "alias": "My.EntryPoint",
         "js": "/App_Plugins/YourFolder/index.js"
        }
    ]
}

Register additional UI extensions in the entry point file

import { extensionRegistry } from "@umbraco-cms/extension-registry"

const manifest = {
  {
    type: '', // type of extension
    alias: '', // unique alias for the extension
    elementName: '', // unique name of the custom element
    js: '', // path to the javascript resource
    meta: {
      // additional props for the extension type
    }
  }
};

extensionRegistry.register(extension);

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.

    {
		"name": "My Package Name",
		"version": "1.0.0",
		"extensions": [
			{
				"type": "bundle",
				"alias": "My.Package.Bundle",
				"name": "My Package Bundle",
				"js": "/App_Plugins/my-package/manifests.js"
			}
		]
	}

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

export const manifests: Array<ManifestTypes> = [
	{
		type: 'dashboard',
		name: 'Example Dashboard',
		alias: 'example.dashboard.demo',
		element: () => import('./demo-dashboard.js'),
		weight: 900,
		meta: {
			label: 'Demo example',
			pathname: 'demo-example',
		},
	},
	// ... insert as many manifests as you like
]

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

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

Read about utilizing conditions in Manifests.

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

<a href="#make-your-own-conditions" id="make-your-own-conditions"></a>

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

import {
  ManifestCondition,
  UmbConditionConfigBase,
  UmbConditionControllerArguments,
  UmbExtensionCondition
} from '@umbraco-cms/backoffice/extension-api';
import { UmbConditionBase } from '@umbraco-cms/backoffice/extension-registry';
import { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export type MyExtensionConditionConfig = UmbConditionConfigBase & {
  match: string;
};

export class MyExtensionCondition extends UmbConditionBase<MyExtensionConditionConfig> implements UmbExtensionCondition {
  constructor(host: UmbControllerHost, args: UmbConditionControllerArguments<MyExtensionConditionConfig>) {
    super(host, args);

    // enable extension after 10 seconds
    setTimeout(() => {
      this.permitted = true;
      args.onChange();
    }, 10000);
  }
}

// Declare the Condition Configuration Type in the global UmbExtensionConditionConfigMap interface:
declare global {
    interface UmbExtensionConditionConfigMap {
        MyExtensionConditionConfig: MyExtensionCondition;
    }
}

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

export const manifest: ManifestCondition = {
 type: 'condition',
 name: 'My Condition',
 alias: 'My.Condition.CustomName',
 api: MyExtensionCondition,
};

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

{
 type: 'workspaceAction',
 name: 'example-workspace-action',
 alias: 'My.Example.WorkspaceAction',
 elementName: 'my-workspace-action-element',
 conditions: [
  {
    alias: 'Umb.Condition.SectionAlias',
    match: 'My.Example.Workspace'
  },
  {
    alias: 'My.Condition.CustomName'
  }
 ]
}

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.

// ...

export class MyExtensionCondition extends UmbConditionBase<MyExtensionConditionConfig> implements UmbExtensionCondition {
  constructor(host: UmbControllerHost, args: UmbConditionControllerArguments<MyExtensionConditionConfig>) {
    super(host, args);

    if (args.config.match === 'Yes') {
      this.permitted = true;
      args.onChange();
    }
  }
}

// ...

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

{
 // ...
 conditions: [
  // ...
  {
    alias: 'My.Condition.CustomName',
    match: 'Yes'
  }
 ]
}

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 Header App 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.

...

const manifest: ManifestKind = {
	type: 'kind',
	alias: 'Umb.Kind.MyButtonKind',
	matchType: 'headerApp',
	matchKind: 'button',
	manifest: {
		...
	},
};

...

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.

...

const manifest = {
	type: 'headerApp',
	kind: 'button',
	...
};

...

Kind example

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

import { ManifestHeaderAppButtonKind, umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';
import { ManifestKind } from '@umbraco-cms/backoffice/extension-api';

const manifest: ManifestKind<ManifestHeaderAppButtonKind> = {
  type: 'kind',
  alias: 'Umb.Kind.MyButtonKind',
  matchType: 'headerApp',
  matchKind: 'button',
  manifest: {
    elementName: 'umb-header-app-button',
  },
};

umbExtensionsRegistry.register(manifest);

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.

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

const manifest = {
	type: 'headerApp',
	kind: 'button',
	name: 'My Header App Example',
	alias: 'My.HeaderApp.Example',
	meta: {
		label: 'My Example',
		icon: 'icon-home',
		href: '/some/path/to/open/when/clicked',
	},
};

extensionRegistry.register(extension);

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 Section Views 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.

You can try and create a custom dashboard as a way on getting started on this topic.

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.

{
  "type": "dashboard",
  "alias": "my.welcome.dashboard",
  "name": "My Welcome Dashboard",
  "element": "/App_Plugins/WelcomeDashboard/dashboard.js",
  "weight": -1,
  "meta": {
    "label": "Welcome Dashboard",
    "pathname": "welcome-dashboard"
  }
}

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

You can specify conditions for when the dashboard should be displayed. This is done by adding a conditions property to the manifest. Ideally, we would like the dashboard to be shown only in a specific section. This can be done by specifying the condition called Umb.Condition.SectionAlias and providing the alias of the section you want the dashboard to be displayed on:

"conditions": [
  {
    "alias": "Umb.Condition.SectionAlias",
    "match": "Umb.Section.Content"
  }
]

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

Properties

The dashboard manifest can contain the following properties:

Full Example

{
  "type": "dashboard",
  "alias": "my.welcome.dashboard",
  "name": "My Welcome Dashboard",
  "element": "/App_Plugins/WelcomeDashboard/dashboard.js",
  "weight": -1,
  "meta": {
    "label": "Welcome Dashboard",
    "pathname": "welcome-dashboard"
  },
  "conditions": [
    {
      "alias": "Umb.Condition.SectionAlias",
      "match": "Umb.Section.Content"
    }
  ]
}

You can learn about creating a custom dashboard in the tutorials section. Here you will learn how to build the dashboard itself as a Web Component.

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

Registering an Entity Bulk Action

import { extensionRegistry } from '@umbraco-cms/extension-registry';
import { MyEntityBulkAction } from './entity-bulk-action';

const manifest = {
 type: 'entityBulkAction',
 alias: 'My.EntityBulkAction',
 name: 'My Entity Bulk Action',
 weight: 10,
 api: MyEntityBulkAction,
 meta: {
  icon: 'icon-add',
  label: 'My Entity Bulk Action',
  repositoryAlias: 'My.Repository',
 },
 conditions: [
  {
   alias: 'Umb.Condition.CollectionAlias',
   match: 'my-collection-alias',
  },
 ],
};

extensionRegistry.register(manifest);

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.

import { UmbEntityBulkActionBase } from '@umbraco-cms/entity-action';
import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api';
import { MyRepository } from './my-repository';

export class MyEntityBulkAction extends UmbEntityBulkActionBase<MyRepository> {
 constructor(host: UmbControllerHostElement, repositoryAlias: string, selection: Array<string>) {
  super(host, repositoryAlias, selection);
 }

 async execute() {
  await this.repository?.myBulkAction(this.selection);
 }
}

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

import { extensionRegistry } from '@umbraco-cms/extension-registry';
import { MyEntityAction } from './entity-action';

const manifest = {
	type: 'entityAction',
	alias: 'My.EntityAction',
	name: 'My Entity Action',
	weight: 10,
	api: MyEntityAction,
	forEntityTypes: ['my-entity'],
	meta: {
		icon: 'icon-add',
		label: 'My Entity Action',
		repositoryAlias: 'My.Repository',
	},
};

extensionRegistry.register(manifest);

Default Element

interface UmbEntityActionElement {}

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:

import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action';
import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api';
import type { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);
	}

	async getHref() {
		return 'my-link/path-to-something';
	}
}

Example of providing a execute method:

import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action';
import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api';
import type { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);
	}

	async execute() {
		await this.repository.myAction(this.unique);
	}
}

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

import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action';
import { UmbContextConsumerController } from '@umbraco-cms/controller';
import { UMB_MODAL_SERVICE_CONTEXT } from '@umbraco-cms/modal';
import { MyRepository } from './my-repository';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
	constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) {
		super(host, repositoryAlias, unique);

		new UmbContextConsumerController(this.host, UMB_MODAL_SERVICE_CONTEXT, (instance) => {
			this.#modalService = instance;
		});
	}
  ...
}

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.

If you have created a package using a custom entity action, please consider providing an update to this documentation page. You can do this via a PR to the documentation repository. This will allow other developers to discover and avoid using the same permission letter.

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:

{
    "type": "entityUserPermission",
    "alias": "Umb.UserPermission.Document.Rollback",
    "name": "Document Rollback User Permission",
    "meta": {
      "entityType": "document",
      "verbs": ["Umb.Document.Rollback"],
      "labelKey": "actions_rollback",
      "descriptionKey": "actionDescriptions_rollback",
      "group": "administration",
    },
  },

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

{
    "type": "userGranularPermission",
    "alias": "Umb.UserGranularPermission.Document",
    "name": "Document Granular User Permission",
    "element": "element.js",
    "meta": {
      "schemaType": "DocumentPermissionPresentationModel",
      "label": "Documents",
      "description": "Assign permissions to specific documents",
    },
  },

The Umbraco backoffice consists of Sections. Section is the main division shown in the top navigation.

For example, when you load the backoffice, you'll see the 'Content' section, 'Settings' section, and so on.

You can create your own sections to extend Umbraco with room for more features.

Creating a section

Manifests

Create a section by defining a manifest for it:

Once registered, you will be able to select this action for your User Group Permissions. Once that is permitted, you can view your section.

Extend with Sidebar, Dashboards and more

Once a section is registered, it can be extended like any other section.

Here is a list of appropriate extensions to append to your section:

Manifest with empty element

If you prefer full control over the content of your section you can choose to define an element for the content of your section.

If you like to have full control, you can define an element like this:

The element file must have an element or default export, or specify the element name in the elementName field.

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:

Rendering a tree

Render a Custom Tree Item

The Tree Item Manifest

The Tree Item Element

The Tree Item Context

Extending the Tree Item Context base

We provide a base class for the tree item context. This class provides some default implementations for the context. You can extend this class to overwrite any of the default implementations.

Section Sidebar Apps

Manifest

Default Element

Menu Sidebar App

Sidebar Menu:

• The Backoffice comes with a menu sidebar app that can be used to create a menu in the sidebar.

• To register a new menu sidebar app, add the following to your manifest

• The menu sidebar app will reference a menu that you have registered in the menu with a menu manifest

Manifest

Default Element

Adding Items to an existing menu

This will make it possible to compose a sidebar menu from multiple Apps:

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:

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.

Example of Workspace

Example of Workspace Context

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

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

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

Creating a custom Section View

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

Manifest

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

Lit Element

Creating the Section View Element using a Lit Element.

my-section.element.ts:

The extension registry is an open system, which can hold any Extension Manifest Type. This article describes how you can declare your types. Types can be declared for re-useability/maintainability or to open up for other package extensions.

Manifest Type Declaration

A Manifest Type is declared via a TypeScript Interface, like shown below:

Registering Localization

When registering localizations to a language, you must add a new manifest to the Extension API. The manifest can be added through the umbraco-package.json file. Usually, the localization keys are provided through a JavaScript module. In this example, we will use a file named en.js:

The Localization file

The localization files for the UI are JavaScript modules with a default export containing a key-value structure organized in sections.

The sections and keys will be formatted into a map in Umbraco with the format section_key1 and section_key2. These form the unique key they are requested.

If you do not have many translations, you can also choose to include them directly in the meta-object:

In this case, the en.js file is not required and we can remove the "js" property from the manifest. Only strings can be used in the meta-object.

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

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

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

1. 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:

Extension Manifest Kind enables declarations to be based upon a preset Manifest.

This is used for maintainability or to inherit existing features.

Manifest Kind Declaration

A Kind is utilized by declaring it in the kind field of a Manifest:

By declaring a kind, the Manifest will inherit fields of the defined Kind.

A typical use case is a Kind that provides an element, but requires additional meta fields, to fulfill the needs of its element.

In the following example, a manifest using the type 'headerApp' utilizes the 'button' kind. This brings an element and requires some additional information as part of the meta object.

Adding the metadata provides the ability to use and configure existing functionality to a specific need.

Learn more

Learn more about Kinds and how to create your own:

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

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.

Default Element

Extension Manifest Conditions enable you to declare requirements for an Extension before it becomes available.

Utilizing Conditions in your Manifest

Conditions are referenced via their alias. The Declaration of a Condition is shown in the following example:

By declaring a condition the extension will become available only once the condition is permitted.

The example above requires the nearest Workspaces Alias to be equal to 'Umb.Workspace.Document'.

When declaring multiple conditions all of them must be permitted for the extension to be available.

Condition Configuration

The conditions are defined as an array of condition configurations. Each entry can contain the following properties:

• alias- The alias of the condition to utilize.

• ... - The rest of the properties of the object are specific to the condition configuration.

Learn more

Learn about built-in conditions and how to create your own: