Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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:
To create your own modal, read the Implementing a Custom Modal article before proceeding with this article.
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.
See the implementing a Confirm Dialog for a more concrete example.
Modal Route Registration
You can register modals with a route, making it possible to link directly to that specific modal. This also means the user can navigate back and forth in the browser history. This makes it an ideal solution for modals containing an editorial experience.
For a more concrete example, check out the Implementing a Confirm Dialog article.
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.
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.
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:
Extension Manifest and can be declared in multiple ways. One of these is to declare it as part of the Umbraco Package Manifest.
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.
Read more about the bundle
extension type in the Bundle article.
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.
Read more about the backofficeEntryPoint
extension type in the Entry Point article.
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.
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
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:
.
.
Follow the to create a header app and name it "header-app
" when using the guide.