@microsoft/sp-dialog/lib/BaseDialog.d.ts

SharePoint Framework support for displaying dialog boxes

import type { Guid } from '@microsoft/sp-core-library';
import type { IDialogConfiguration, IDialogShowOptions } from './IDialog';
import type { ISecondaryDialogProvider } from './SecondaryDialogProvider';
/**
 * The states for our internal state machine that manages dialogs
 *
 * @internal
 */
export declare enum _DialogState {
    /**
     * State: New
     * Description: The dialog state after construction
     * Next Possible States: Pending
     */
    New = 0,
    /**
     * State: Pending
     * Description: The dialog manager has acknowledged the request to show
     * Next Possible States: Rejected, Aborted, Approved
     */
    Pending = 1,
    /**
     * State: Rejected
     * Description: The dialog manager has rejected the request to show
     * Next Possible States: Pending (by sending a new request)
     */
    Rejected = 2,
    /**
     * State: Aborted
     * Description: The dialog has aborted its request to show
     * Next Possible States: Pending (by sending a new request)
     */
    Aborted = 3,
    /**
     * State: Approved
     * Description: The dialog manager has approved the request to show
     * Next Possible States: Open
     */
    Approved = 4,
    /**
     * State: Open
     * Description: The dialog is visually open
     * Next Possible States: Closed, Hidden
     */
    Open = 5,
    /**
     * State: Closed
     * Description: The dialog is closed (can only happen after Open)
     * Next Possible States: Pending (by sending a new request)
     */
    Closed = 6,
    /**
     * State: Hidden
     * Description: The dialog is hidden behind a secondary dialog
     * Next Possible States: Open
     */
    Hidden = 7
}
/**
 * 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.
 *
 * @public
 */
export default abstract class BaseDialog {
    private static readonly _logSource;
    private _closedWhileRendering;
    private _config;
    private _domElement;
    private _isSecondary;
    private _renderPromise;
    private _requestId;
    private _secondaryDialogProvider;
    private _state;
    /**
     * 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()
     *   }
     * ```
     *
     * @param config - the dialog configuration that affects how the dialog is displayed   *
     */
    constructor(config?: IDialogConfiguration);
    /**
     * The dialog configuration
     *
     * @internal
     */
    get _configuration(): IDialogConfiguration;
    /**
     * If the dialog is a secondary dialog. This means that there is another dialog hidden behind this dialog.
     */
    get isSecondary(): boolean;
    /**
     * 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;
    /**
     * 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.
     */
    get isHidden(): boolean;
    /**
     * 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.
     */
    get secondaryDialogProvider(): ISecondaryDialogProvider | undefined;
    /**
     * Request the framework to show this dialog.
     *
     * @returns A promise that resolves once the dialog is successfully closed (after being shown).
     * The promise rejects if the request is rejected or aborted.
     *
     * @param options - Dialog showing options.  See {@link IDialogShowOptions} for more information.
     */
    show(options?: IDialogShowOptions): Promise<void>;
    /**
     * 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.
     *
     * @returns A promise that resolves when the dialog is visually closed, or if it was already closed
     */
    close(): Promise<void>;
    /**
     * Called by the manager after the modal is open to render the dialog content.
     * This internally calls onBeforeOpen() and returns a promise that resolves only if the render was successful.
     * If onBeforeOpen() is rejected or dialog is closed while rendering, the returned promise will reject.
     *
     * @internal
     */
    _render(container: HTMLElement): Promise<void>;
    /**
     * Called by the manager to change the state of the dialog.
     * Note: State management is all done by the manager using this method. Do not call this method from this class.
     * If you want to do something upon state change, do it in this method by checking the newState.
     *
     * @internal
     */
    _setState(newState: _DialogState): void;
    /**
     * Called by the manager to acknowledging a show request and sets some parameters that active dialogs need
     *
     * @param requestId - A Guid which is unique string for the manager to identify the request for this dialog
     * @param isSecondary - If the dialog is secondary (called via secondary dialog API)
     *
     * @internal
     */
    _requestAck(requestId: Guid, isSecondary?: boolean): void;
    /**
     * 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.
     */
    protected abstract render(): void;
    /**
     * Use this property to access the container element provided by the framework for rendering.
     *
     * @remarks
     * See {@link BaseDialog.render} for more information on rendering.
     */
    protected get domElement(): HTMLElement;
    /**
     * 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.
     *
     * @returns 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.
     */
    protected onBeforeOpen(): Promise<void>;
    /**
     * 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.
     */
    protected onAfterClose(): void;
    /**
     * A dialog is active if it is in one of these states:
     *  - The framework has approved to show it and has started the opening process
     *  - It is open and showing
     *  - It is visually hidden behind a secondary dialog
     *
     * When a dialog is active, the framework considers that dialog to have permission to show until it is closed.
     */
    private get _isActive();
}
//# sourceMappingURL=BaseDialog.d.ts.map