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...
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.
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.
Follow the Vite Package Setup to create a header app and name it "header-app
" when using the guide.
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:
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.
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.
To create your own modal, read the before proceeding with this article.
For a more concrete example, check out the .
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
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.
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.
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:
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