/
basedialog.yml
223 lines (216 loc) · 10.6 KB
/
basedialog.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
### YamlMime:TSType
name: BaseDialog
uid: '@microsoft/sp-dialog!BaseDialog:class'
package: '@microsoft/sp-dialog!'
fullName: BaseDialog
summary: >-
The base class for implementing dialogs in SharePoint Framework. This provides a supported way for showing dialogs to
the user inside SharePoint Framework components.
remarks: >-
Extend this class to create dialogs for SharePoint Framework. By following the guidelines in implementation, the
framework can ensure that the dialogs are shown in a user-friendly manner. While the content of the dialog is
controlled by this class by implementing the render method, the framework can decide when to show the dialog and how
to render the overlay and modal. The application on the page can also have control on allowing dialogs to show. Refer
to the documentation of the individual methods and properties to learn more about how to extend and use this class.
isPreview: false
isDeprecated: false
type: class
constructors:
- name: (constructor)(config)
uid: '@microsoft/sp-dialog!BaseDialog:constructor(1)'
package: '@microsoft/sp-dialog!'
fullName: (constructor)(config)
summary: Constructor for the `BaseDialog` class.
remarks: >-
It is important to keep the constructor lightweight. Use `onBeforeOpen()` for doing heavy-weight initialization
that is needed for rendering the dialog such as resource allocations and asynchronous calls to fetch data. You can
use the constructor to set initial parameters of your dialog such as references to resources in your application.
The reason for this is that dialogs are usually constructed upon a UI event e.g. a button click, but the dialog
may not always be shown right after construction. Keeping the constructor lightweight ensures smooth user
experience and avoids doing throw-away work in case the dialog is not shown later e.g. if the framework rejects
it. Another benefit of doing this is avoiding memory leaks by doing all the allocations and disposals in symmetric
`onBeforeOpen()` and `onAfterClose()` events. If you allocate resources in the constructor, you have a memory leak
because there is no guarantee onAfterClose() will get called, and onAfterClose() is your only opportunity to
dispose.
Example:
```
constructor(cacheReference: any) {
super();
this._cache = cacheReference; // This is okay. Keeping a reference to my internal cache.
this._cache.refresh(); // This is bad practice.
// If you need to refresh the cache (or fetch data) for rendering, do it in onBeforeOpen()
}
```
isPreview: false
isDeprecated: false
syntax:
content: 'constructor(config?: IDialogConfiguration);'
parameters:
- id: config
description: the dialog configuration that affects how the dialog is displayed \*
type: '<xref uid="@microsoft/sp-dialog!IDialogConfiguration:interface" />'
properties:
- name: domElement
uid: '@microsoft/sp-dialog!BaseDialog#domElement:member'
package: '@microsoft/sp-dialog!'
fullName: domElement
summary: Use this property to access the container element provided by the framework for rendering.
remarks: >-
See [BaseDialog.render()](xref:@microsoft/sp-dialog!BaseDialog%23render:member(1)) for more information on
rendering.
isPreview: false
isDeprecated: false
syntax:
content: 'protected get domElement(): HTMLElement;'
return:
type: HTMLElement
- name: isHidden
uid: '@microsoft/sp-dialog!BaseDialog#isHidden:member'
package: '@microsoft/sp-dialog!'
fullName: isHidden
summary: If the dialog is visually hidden.
remarks: >-
This happens when the dialog goes behind a secondary dialog. Note that this is different from closed, because the
dialog still has the permission to show and will eventually unhide. This returns false if the dialog is closed.
isPreview: false
isDeprecated: false
syntax:
content: 'get isHidden(): boolean;'
return:
type: boolean
- name: isOpen
uid: '@microsoft/sp-dialog!BaseDialog#isOpen:member'
package: '@microsoft/sp-dialog!'
fullName: isOpen
summary: >-
If the dialog is visually open. This returns true during onBeforeOpen() because there is a visual component. It
returns false when the dialog is hidden.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'get isOpen(): boolean;'
return:
type: boolean
- name: isSecondary
uid: '@microsoft/sp-dialog!BaseDialog#isSecondary:member'
package: '@microsoft/sp-dialog!'
fullName: isSecondary
summary: If the dialog is a secondary dialog. This means that there is another dialog hidden behind this dialog.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'get isSecondary(): boolean;'
return:
type: boolean
- name: secondaryDialogProvider
uid: '@microsoft/sp-dialog!BaseDialog#secondaryDialogProvider:member'
package: '@microsoft/sp-dialog!'
fullName: secondaryDialogProvider
summary: >-
An active dialog is permitted to show a secondary dialog on top of itself. By design, only two layers of dialogs
are permitted.
remarks: >-
Secondary dialogs do not have to wait for permission and will immediately be shown or rejected. All calls to show
a secondary dialog reject while there is already a secondary dialog showing. This property may be undefined if a
secondary dialog is not available i.e. the current dialog is secondary itself or the dialog is not active.
isPreview: false
isDeprecated: false
syntax:
content: 'get secondaryDialogProvider(): ISecondaryDialogProvider | undefined;'
return:
type: '<xref uid="@microsoft/sp-dialog!ISecondaryDialogProvider:interface" /> | undefined'
methods:
- name: close()
uid: '@microsoft/sp-dialog!BaseDialog#close:member(1)'
package: '@microsoft/sp-dialog!'
fullName: close()
summary: Close the dialog.
remarks: >-
This will void the permission to show for this dialog. Every dialog should have a mechanism to eventually close to
avoid blocking the user interface. If called on an inactive dialog it will abort the request to show.
isPreview: false
isDeprecated: false
syntax:
content: 'close(): Promise<void>;'
return:
type: Promise<void>
description: 'A promise that resolves when the dialog is visually closed, or if it was already closed'
- name: onAfterClose()
uid: '@microsoft/sp-dialog!BaseDialog#onAfterClose:member(1)'
package: '@microsoft/sp-dialog!'
fullName: onAfterClose()
summary: This method is called after the dialog is visually closed and gives an opportunity for doing clean up.
remarks: >-
The dialog lifecycle completes after closing and there should be no resources left inside the object. Even though
the dialog may be revived again for a new lifecycle using show() method, this is considered a whole new lifecycle
that should reallocate its own resources. If there are any resources that you would like to keep for multiple
lifecycles, consider allocating it outside the dialog object and passing its reference to the dialog constructor.
isPreview: false
isDeprecated: false
syntax:
content: 'protected onAfterClose(): void;'
return:
type: void
description: ''
- name: onBeforeOpen()
uid: '@microsoft/sp-dialog!BaseDialog#onBeforeOpen:member(1)'
package: '@microsoft/sp-dialog!'
fullName: onBeforeOpen()
summary: >-
This method is called before the render method and can be overridden to make preparations for rendering. The
loading indicator is displayed during the lifetime of this method. virtual
remarks: All resource allocations in onBeforeOpen() should be properly disposed in `onAfterClose()` to a avoid memory leak.
isPreview: false
isDeprecated: false
syntax:
content: 'protected onBeforeOpen(): Promise<void>;'
return:
type: Promise<void>
description: >-
A promise that resolves when the operations are done and the dialog is ready to render. If the promise is
rejected, the dialog will not be rendered and `onAfterClose()` will not be called.
- name: render()
uid: '@microsoft/sp-dialog!BaseDialog#render:member(1)'
package: '@microsoft/sp-dialog!'
fullName: render()
summary: Renders the contents of the dialog.
remarks: >-
The `render` method must be implemented to render the content of the dialog in the container element provided by
the framework. Use `this.domElement` to access this container. The container is inside a modal rendered in the
center of the page on top of a dark overlay.
The render method is called once after the modal element is created and opened. It is recommended to use
`onBeforeOpen()` for doing non-UI operations for your rendering that might take a long time. This will ensure that
the framework can show a friendly UI such as a spinner to let the user know that the dialog is being prepared. If
you choose to do your initialization or other costly operations inside render method, make sure to have a friendly
UI so the user is informed about the state of your dialog. Otherwise, an empty element is shown to the user which
is a bad user experience practice.
isPreview: false
isDeprecated: false
syntax:
content: 'protected abstract render(): void;'
return:
type: void
description: ''
- name: show(options)
uid: '@microsoft/sp-dialog!BaseDialog#show:member(1)'
package: '@microsoft/sp-dialog!'
fullName: show(options)
summary: Request the framework to show this dialog.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'show(options?: IDialogShowOptions): Promise<void>;'
parameters:
- id: options
description: >-
Dialog showing options. See [IDialogShowOptions](xref:@microsoft/sp-dialog!IDialogShowOptions:interface) for
more information.
type: '<xref uid="@microsoft/sp-dialog!IDialogShowOptions:interface" />'
return:
type: Promise<void>
description: >-
A promise that resolves once the dialog is successfully closed (after being shown). The promise rejects if the
request is rejected or aborted.