You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-types/modals/README.md
+46-44Lines changed: 46 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,51 +6,55 @@ description: >-
6
6
7
7
# Modals
8
8
9
-
{% hint style="warning" %}
10
-
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.
11
-
{% endhint %}
12
-
13
9
## **Modal Types**
14
10
15
-
The Dialog modal appears in the middle of the screen. and the Sidebar Modal slide in from the right.
11
+
The Dialog modal appears in the middle of the screen and the Sidebar Modal slides in from the right.
16
12
17
-
## Modal Token
13
+
## Open a Modal
18
14
19
-
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.
15
+
A modal can be opened in two ways: either directly at runtime or by registering a route for the modal. Registering a route allows deep-linking to the modal, which may be preferred in certain scenarios. Otherwise, opening the modal directly is a simpler option.
20
16
21
-
This can also come with defaults, for example, settings for the modal type and size.
17
+
### Directly open via the Open Modal method
22
18
23
-
This is an example of a Modal Token declaration:
19
+
<preclass="language-ts"data-title="my-element.ts"><codeclass="lang-ts">import { customElement, html } from '@umbraco-cms/backoffice/external/lit';
20
+
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
21
+
import { MY_MODAL_TOKEN } from './my-modal.token.js';
22
+
import { umbOpenModal } from '@umbraco-cms/backoffice/modal';
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:
49
+
The Promise returned by `umbOpenModal` is handled for potential rejection. This occurs when the Model is closed without submitting. Use this behavior to carry out a certain action if the modal is cancelled. In this case, `undefined` is returned when the Modal is cancelled (rejected).
50
+
51
+
See the [Confirm Modal article](confirm-dialog.md) for an example.
52
+
53
+
### Directly open via the Modal Manager Context
54
+
55
+
For full control, open a modal via the **Modal Manager Context.** This is what the Open Modal method uses behind the scenes. Using the context directly gives you a bit more control and understanding of the system.
56
+
57
+
First, consume the `UMB_MODAL_MANAGER_CONTEXT` , then use the modal manager context to open a modal. The following example shows how to consume the Modal Manager Context:
@@ -72,13 +76,7 @@ export class MyElement extends UmbElementMixin(LitElement) {
72
76
}
73
77
```
74
78
75
-
#### Open a modal
76
-
77
-
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.
78
-
79
-
#### Directly open a Modal
80
-
81
-
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.
79
+
In this case, the modal token from the previous example is used. It accepts a key as input data and returns the new key if the modal is submitted.
[See the implementing a Confirm Dialog for a more concrete example.](confirm-dialog.md)
96
+
[See the implementing a Confirm Dialog for an example.](confirm-dialog.md)
99
97
100
-
**Modal Route Registration**
98
+
### Modal Route Registration
101
99
102
100
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.
103
101
104
-
For a more concrete example, check out the [Implementing a Confirm Dialog article](route-registration.md).
102
+
For a more concrete example, check out the [Modal Route Registration article](route-registration.md).
103
+
104
+
## Make a custom Modal
105
+
106
+
To create your modal, read the [Implementing a Custom Modal article](custom-modals.md).
New modals can be added to the system via the extension registry. This article
4
-
goes through how this is done.
2
+
description: New modals can be added to the system via the extension registry.
5
3
---
6
4
7
5
# Custom Modals
8
6
9
-
{% hint style="warning" %}
10
-
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.
11
-
{% endhint %}
12
-
13
-
There are two parts to creating a custom modal:
14
-
15
-
* First, you need to create a modal element which you need to register in the extension registry. 
16
-
* Second, you need to create and export a modal token.
17
-
18
-
## Create a modal token
19
-
20
-
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.
13
+
After completing these steps, refer to the example on how to open the modal.
42
14
43
15
## Create a modal element
44
16
45
-
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.
17
+
A modal element is a web component that is used to render a 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.
46
18
47
-
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.
19
+
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.
48
20
49
21
{% code title="my-modal.element.ts" %}
50
22
```ts
@@ -55,7 +27,7 @@ import type { UmbModalContext } from '@umbraco-cms/backoffice/modal';
@@ -84,57 +56,84 @@ export default class MyDialogElement
84
56
`;
85
57
}
86
58
}
59
+
60
+
exportconst element =MyDialogElement;
87
61
```
88
62
{% endcode %}
89
63
90
-
## Register in the extension registry
64
+
The class must be exported as an `element` or `default` for the Extension Registry to be able to pick up the class.
65
+
66
+
## Declare an Extension Manifest
91
67
92
68
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.
93
69
94
-
```json
70
+
```typescript
95
71
{
96
-
"type": "modal",
97
-
"alias": "My.Modal",
98
-
"name": "My Modal",
99
-
"element": "../path/to/my-modal.element.js"
72
+
type: 'modal',
73
+
alias: 'My.Modal',
74
+
name: 'My Modal',
75
+
element: '../path/to/my-modal.element.js'
100
76
}
101
77
```
102
78
103
-
## Open the modal
79
+
## Create a modal token
80
+
81
+
{% hint style="info" %}
82
+
For type safety, it's recommended to use Modal Tokens. Using a Modal Token gives knowledge about the data that can be parsed to the Modal and as well as the type of the value coming back when submitted.
83
+
{% endhint %}
104
84
105
-
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:
85
+
A Modal Token works as a constant that identifies the modal. It is used to open the modal and knows the types of the modal data and modal value. As well, it can contain a preset, containing default data and modal options.
86
+
87
+
The first argument passed to `UmbModalToken` is the extension alias; the second is the preset configuration.
106
88
107
-
{% code title="my-element.ts" %}
108
89
```ts
109
-
import { customElement, html } from'@umbraco-cms/backoffice/external/lit';
The Promise of `umbOpenModal` is caught if it gets rejected. This is because if the Model gets closed without submission, the Promise is rejected. YThis can be used to carry out a certain action if the modal is cancelled. In this case, `undefined` is returned when the Modal is cancelled (rejected).
Copy file name to clipboardExpand all lines: 16/umbraco-cms/customizing/extending-overview/extension-types/modals/route-registration.md
+8-7Lines changed: 8 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,11 @@
1
-
# Route Registration
1
+
---
2
+
description: >-
3
+
You can register modals with a route, making it possible to link directly to
4
+
that specific modal. This also means the user can navigate back and forth in
5
+
the browser history
6
+
---
2
7
3
-
{% hint style="warning" %}
4
-
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.
5
-
{% endhint %}
6
-
7
-
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. 
8
+
# Modal Route Registration
8
9
9
10
A modal can be registered via the `UmbModalRouteRegistrationController`. The registration accepts a modal token (or extension alias).
10
11
@@ -30,7 +31,7 @@ The registration holds an instance of its `UmbModalHandler` when the modal is ac
30
31
31
32
**Additional features of the route Registration:**
32
33
33
-
* Adds unique parts to the path. 
34
+
* Adds unique parts to the path.
34
35
* A modal registered in a dashboard can be setup in few steps
35
36
* A modal registered in a property editor needs to become specific for the property and the variant of that property.
0 commit comments