gentics-ui-core/components/modal/modal.service.d.ts

This is the common core framework for the Gentics CMS and Mesh UI, and other Angular applications.

import { ComponentRef, ComponentFactoryResolver, ElementRef, Type } from '@angular/core';
import { OverlayHostService } from '../overlay-host/overlay-host.service';
import { ModalDialog } from './modal-dialog.component';
import { BlankModal } from './blank-modal.component';
import { IModalInstance, IDialogConfig, IModalDialog, IModalOptions } from './modal-interfaces';
import * as i0 from "@angular/core";
/**
 * A promise-based service for creating modal windows and dialogs.
 * Depends on the [`<gtx-overlay-host>`](#/overlay-host) being present in the app.
 *
 * ## Return Values
 * All the public methods return the `IModalInstance` object:
 *
 * ```
 * interface IModalInstance {
 *     instance: IModalDialog;
 *     element: HTMLElement;
 *     open: () => Promise<any>;
 * }
 * ```
 * Calling the `open()` method returns a promise which will be resolved when the modal is closed
 * or rejected when a button is set to `shouldReject` or the modal calls the passed error handler.
 *
 * ## `.dialog()`
 * To create a basic dialog modal, use the `.dialog()` method. This accepts an `IDialogConfig` object:
 *
 * ```TypeScript
 * interface IDialogConfig {
 *   title: string;
 *   body?: string;
 *   buttons: {
 *       label: string;
 *       type?: 'default' | 'secondary' | 'success'| 'warning' | 'alert';
 *       flat?: boolean;
 *       // If specified, will be returned as the
 *       // value of the resolved promise (or the reason if rejected).
 *       returnValue?: any;
 *       // If true, clicking the button will cause
 *       // the promise to reject rather than resolve
 *       shouldReject?: boolean;
 * }[];
 * ```
 *
 * Example:
 * ```TypeScript
 * modalService.dialog({
 *   title: 'Are you sure?',
 *   body: 'Do you <em>really</em> want to delete this thing?',
 *   buttons: [
 *     { label: 'Delete', type: 'alert', returnValue: true },
 *     { label: 'Cancel', type: 'secondary', shouldReject: true }
 *   ]
 * }).then(modal => modal.open())
 *   .then(result => console.log('deleting...'))
 *   .catch(() => console.log('cancelled');
 * ```
 *
 * ## `.fromComponent()`
 * For more complex modals, a component can be passed to the `.fromComponent()` method which will then be
 * placed inside a modal window. The component must implement the IModalDialog interface, which allows the
 * ModalService to hook into a `closeFn` & `cancelFn` so it knows to close the modal and resolve the promise.
 * To forward errors from the modal to the caller, implement `registerErrorFn` from the IModalDialog interface.
 *
 * Example:
 * ```TypeScript
 * @Component({
 *   selector: 'my-modal-form',
 *   template: '...' // some big form
 * })
 * export class MyModalForm implements IModalDialog {
 *   // IModalDialog interface members
 *   closeFn: (val: any) => void;
 *   cancelFn: (val?: any) => void;
 *   registerCloseFn(close: (val: any) => void): void {
 *       this.closeFn = close;
 *   }
 *   registerCancelFn(cancel: (val?: any) => void): void {
 *       this.cancelFn = cancel;
 *   }
 *
 *   someLocalVariable: string;
 *
 *   // Bound to the form's submit event.
 *   onSubmitClick() : void {
 *      this.closeFn(this.form.value);
 *   }
 *
 *   // Bound to the "cancel" button in the template
 *   onCancelClick(): void {
 *      this.cancelFn();
 *   }
 * }
 * ```
 * The above component could then be used as follows:
 * ```TypeScript
 * modalService.fromComponent(MyModalForm, {}, { someLocalVariable: 'foo' })
 *   .then(modal => modal.open())
 *   .then(result => console.log(result));
 * ```
 *
 * ## Modal Options
 * All public methods take an optional options parameter to describe the behavior and appearance of the modal window
 * itself:
 * ```TypeScript
 * interface IModalOptions {
 *     onOpen?: Function;
 *     onClose?: Function;
 *     closeOnOverlayClick?: boolean;
 *     closeOnEscape?: boolean;
 *     width?: string;
 *     padding?: boolean;
 *     modalBodyClass?: string;
 * }
 * ```
 */
export declare class ModalService {
    private componentFactoryResolver;
    private _parentModalService;
    private openModalComponents;
    private getHostViewContainer;
    /**
     * Returns an array of ComponentRefs for each currently-opened modal.
     */
    get openModals(): ComponentRef<IModalDialog>[];
    constructor(componentFactoryResolver: ComponentFactoryResolver, overlayHostService: OverlayHostService, _parentModalService?: ModalService);
    /**
     * Create a new modal instance containing the specified component, optionally specifying "locals" which
     * will be defined on the component instance with the given value.
     */
    fromComponent<T extends IModalDialog>(component: Type<T>, options?: IModalOptions, locals?: {
        [K in keyof T]?: T[K];
    }): Promise<IModalInstance<T>>;
    /**
     * Create a new modal by appending the elementRef to a blank modal window. Primarily used internally
     * for the implementation of the declarative [Modal](#/modal) component.
     */
    fromElement(elementRef: ElementRef, options?: IModalOptions): Promise<IModalInstance<BlankModal>>;
    /**
     * Creates and displays a standard modal dialog.
     */
    dialog(config: IDialogConfig, options?: IModalOptions): Promise<IModalInstance<ModalDialog>>;
    private wrapComponentInModal;
    /**
     * Ensure that the component passed in implements IModalDialog.
     */
    private checkModalDialogInterface;
    /**
     * Creates the DynamicModalWrapper in place in the DOM and returns a reference to the
     * created component.
     */
    private createModalWrapper;
    /**
     * Decorate the ModalWrapper instance with the dismissFn and return that instance.
     */
    private getConfiguredModalWrapper;
    /**
     * Returns a promise which is bound to the closeFn and cancelFn of the dialog instance,
     * and will be resolved/rejected when either of those methods are invoked.
     */
    private createPromiseFromDialog;
    private invokeOnOpenCallback;
    private invokeOnCloseCallback;
    static ɵfac: i0.ɵɵFactoryDeclaration<ModalService, [null, null, { optional: true; skipSelf: true; }]>;
    static ɵprov: i0.ɵɵInjectableDeclaration<ModalService>;
}