Loading...
Loading...
Loading...
Loading...
The declaration of an extension is done by an Extension Manifest, either registered via an Umbraco-Package Manifest or directly to the Extension Registry in JavaScript.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Getting started with backoffice setup and configurations
In this section you can find the common terms, concepts and guides used to extend the Umbraco backoffice.
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.
An overview of concepts on how to work with extension registration when extending the backoffice.
An overview of concepts on how to work with extension types when extending the backoffice.
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.
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 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 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:
Via a manifest JSON file on the server.
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 necessary properties that any extension manifest needs 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.
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.
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.
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 rely on a reference to other extensions.
The pages of this article describe all the extension types that Backoffice supports. Here is a list of the most common types:
You can declare new Extension Manifests in JavaScript at any given point.
Backoffice also comes with two Extension types which can be used to register more extensions.
bundle
to declare other Extension ManifestThe 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 from this Module will be registered in the Extension Registry.
backofficeEntryPoint
as your foundationThe backofficeEntryPoint
extension type is special, it can be used to 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, React, etc. You can use the backofficeEntryPoint
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.
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 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.
Example how to work with extension registry
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 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:
Below you can find an example of how to setup a Header App using the manifest file.
Create a manifest file named umbraco-package.json
at the root of the header-app
folder. Here we define and configure our dashboard.
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.
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:
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.
Add a reference to the .js file. Update the umbraco-package.json
with the following:
Replace the content of the src/my-element.ts file
with the following:
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:
Learn how to append and use Icons.
This article describes how to add and use more icons in your UI.
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.
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.
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.
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:
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:
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.
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.
Extension Manifest and can be declared in multiple ways. One of these is to declare it as part of the .
Read more about the bundle
extension type in the article.
Read more about the backofficeEntryPoint
extension type in the article.
.
.
Follow the to create a header app and name it "header-app
" when using the guide.
To create your own modal, read the before proceeding with this article.
For a more concrete example, check out the .
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.
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.
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.
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.
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:
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.
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).
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.
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.
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:
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
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 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.
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.
A kind extension provides the preset for other extensions to use
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 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.
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.
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 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 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 a JSON manifest
Register additional UI extensions in the entry point file
Extension conditions are used to determine if an extension should be used or not. Many of the Extension Types support conditions, but not all of them.
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.
All given conditions for an extension must be valid for an extension to be utilized.
In the following example we define the manifest for a Workspace Action, this action will only be available in the workspace with the alias My.Example.Workspace
.
The conditions are defined as an array of conditions. Each condition is an object with the following properties:
alias
- The alias of the condition to utilize.
...
- The rest of the properties of the object are specific to the condition.
In the above example the Umb.Condition.SectionAlias
condition is used, this condition takes a property match
which must be set to the alias of the section to match.
The following conditions are available out of the box, for all extension types that support conditions.
Umb.Condition.SectionAlias
- Checks if the current section alias matches the one specified.
Umb.Condition.WorkspaceAlias
- Checks if the current workspace alias matches the one specified.
You can make your own conditions by creating a class that implements the UmbExtensionCondition
interface.
This has to be registered in the extension registry like 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: