BaseDialog class

Package:

@microsoft/sp-dialog

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.

Constructors

(constructor)(config)

Constructor for the BaseDialog class.

Properties

domElement	Use this property to access the container element provided by the framework for rendering.
isHidden	If the dialog is visually hidden.
isOpen	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.
isSecondary	If the dialog is a secondary dialog. This means that there is another dialog hidden behind this dialog.
secondaryDialogProvider	An active dialog is permitted to show a secondary dialog on top of itself. By design, only two layers of dialogs are permitted.

Methods

close()	Close the dialog.
onAfterClose()	This method is called after the dialog is visually closed and gives an opportunity for doing clean up.
onBeforeOpen()	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
render()	Renders the contents of the dialog.
show(options)	Request the framework to show this dialog.

Constructor Details

(constructor)(config)

Constructor for the BaseDialog class.

constructor(config?: IDialogConfiguration);

Parameters

config

IDialogConfiguration

the dialog configuration that affects how the dialog is displayed *

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()
  }

Property Details

domElement

Use this property to access the container element provided by the framework for rendering.

protected get domElement(): HTMLElement;

Property Value

HTMLElement

Remarks

See BaseDialog.render() for more information on rendering.

isHidden

If the dialog is visually hidden.

get isHidden(): boolean;

Property Value

boolean

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.

isOpen

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.

get isOpen(): boolean;

Property Value

boolean

isSecondary

If the dialog is a secondary dialog. This means that there is another dialog hidden behind this dialog.

get isSecondary(): boolean;

Property Value

boolean

secondaryDialogProvider

An active dialog is permitted to show a secondary dialog on top of itself. By design, only two layers of dialogs are permitted.

get secondaryDialogProvider(): ISecondaryDialogProvider | undefined;

Property Value

ISecondaryDialogProvider | undefined

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.

Method Details

close()

Close the dialog.

close(): Promise<void>;

Returns

Promise<void>

A promise that resolves when the dialog is visually closed, or if it was already closed

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.

onAfterClose()

This method is called after the dialog is visually closed and gives an opportunity for doing clean up.

protected onAfterClose(): void;

Returns

void

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.

onBeforeOpen()

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

protected onBeforeOpen(): Promise<void>;

Returns

Promise<void>

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.

Remarks

All resource allocations in onBeforeOpen() should be properly disposed in onAfterClose() to a avoid memory leak.

render()

Renders the contents of the dialog.

protected abstract render(): void;

Returns

void

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.

show(options)

Request the framework to show this dialog.

show(options?: IDialogShowOptions): Promise<void>;

Parameters

options

IDialogShowOptions

Dialog showing options. See IDialogShowOptions for more information.

Returns

Promise<void>

A promise that resolves once the dialog is successfully closed (after being shown). The promise rejects if the request is rejected or aborted.