Angular cs-modal

This library was generated with [Angular CLI].

Getting started

Step 1: Install cs-modal:

NPM

npm install --save @cargos/cs-modal

Step 2: Import the CsModalModule:

import { CsModalModule } from '@cargos/cs-modal';

@NgModule({
  declarations: [AppComponent],
  imports: [CsModalModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

Step 3: Import the csModal in AppComponent and initialize the settings:

import { csModal, Modal } from '@cargos/cs-modal';

export class AppComponent {

  public settingsModal: Observable<Modal>;

  constructor() {
    this.settingsModal = csModal.getSettings();
  }

}

Step 4: Declare cs-modal component in app.component.html:

<cs-modal [settings]="settingsModal"></cs-modal>

Step 5: Include style dependencies and a theme:

In angular.json, add to your project's styles array:

"styles": [
  "node_modules/material-icons/iconfont/material-icons.css",
  "node_modules/@cargos/cs-modal/styles/modal.css",
  "node_modules/@cargos/cs-modal/styles/sprintpass.theme.css"
]

Note: Only sprintpass.theme is available at the moment.

Settings

ModalParams<T> accepts the following options. T is an optional generic parameter representing the Angular component injected as modal content — it propagates type-safe access to modal.contentInstance in all callbacks.

| Key | Type | Default | Description | | ------------- | ------------- | ------------- | ------------- | | title | string | '' | Modal title text | | titleClass | string | '' | CSS class applied to the title | | titleAlign | 'left' ⎮ 'center' ⎮ 'right' | 'center' | Title alignment | | content | ModalContent | '' | Modal body: string, component class, or async function | | contentAlign | 'left' ⎮ 'center' ⎮ 'right' | 'center' | Content alignment | | type | 'default' ⎮ 'warning' ⎮ 'error' ⎮ 'success' ⎮ 'info' | 'default' | Visual style variant | | spinner | 'dots' ⎮ 'circle' | 'dots' | Spinner style for async content | | buttons | ButtonOptions<T>[] | [] | Action buttons | | buttonsAlign | 'left' ⎮ 'center' ⎮ 'right' ⎮ 'space-evenly' | 'center' | Buttons alignment | | iconName | string | '' | Material icon name | | iconFontClass | string | 'material-icons' | Icon font class | | iconAlign | 'left' ⎮ 'center' ⎮ 'right' | 'center' | Icon alignment | | bgTheme | 'black' ⎮ 'white' | 'black' | Overlay background color | | theme | 'sprintpass' | 'sprintpass' | Visual theme | | animation | 'scale' ⎮ 'fade' | 'fade' | Open animation | | closeAnimation | 'scale' ⎮ 'fade' | 'fade' | Close animation | | closeIcon | boolean ⎮ ModalCallback<T> | null | Show close icon. true closes the modal, a function overrides the behaviour | | closeIconName | string | 'close' | Material icon name for the close button | | columnClass | 'xsmall' ⎮ 'small' ⎮ 'medium' ⎮ 'large' ⎮ 'cover' | 'small' | Modal width | | fontSize | 'small' ⎮ 'medium' ⎮ 'large' | 'small' | Base font size inside the modal | | autoClose | number | 0 | Auto-close delay in milliseconds (0 = disabled) | | autoCloseAction | ModalCallback<T> ⎮ string | '' | Callback or label executed on auto-close | | backgroundDismiss | boolean ⎮ ModalCallback<T> | null | Dismiss on overlay click. true closes, a function overrides | | backgroundDismissAnimation | 'none' ⎮ 'shake' | 'shake' | Animation when dismissal is blocked | | escapeKey | boolean ⎮ ModalCallback<T> | null | Dismiss on Escape key. true closes, a function overrides | | maximize | boolean | false | Show maximize button | | onContentReady | ModalVoidCallback<T> | null | Called when the dynamic component is ready | | onContentError | ModalVoidCallback<T> | null | Called when the dynamic component fails to load | | zIndex | number | 1000 | CSS z-index of the modal |

Callback types

// Base type — T is the injected component, R is the return type
type ModalCallback<T = DynamicComponent, R = unknown> = (modal?: Modal<T>) => R;

type ModalVoidCallback<T>             = ModalCallback<T, void>;
type ModalBooleanCallback<T>          = ModalCallback<T, boolean>;
type ModalStringCallback<T>           = ModalCallback<T, string>;
type ModalObservableCallback<T>       = ModalCallback<T, Observable<unknown>>;
type ModalObservableStringCallback<T> = ModalCallback<T, Observable<string>>;

Methods

| Name | Signature | Description | | ------------- | ------------- | ------------- | | confirm | confirm<T>(settings: ModalParams<T>): Modal<T> | Open a modal | | success | success<T>(settings: ModalParams<T> \| string): Modal<T> | Open a success modal | | warning | warning<T>(settings: ModalParams<T> \| string): Modal<T> | Open a warning modal | | error | error<T>(settings: ModalParams<T> \| string): Modal<T> | Open an error modal | | close | close(): void | Close the current modal |

How to use

Basic usage

import { csModal } from '@cargos/cs-modal';

export class MyComponent {

  /* Optional: close the modal when the component is destroyed */
  ngOnDestroy() {
    csModal.close();
  }

  showModal() {
    csModal.confirm({
      title: 'Confirm',
      content: 'Are you sure?'
    });
  }

}

With a dynamic component (typed)

import { csModal, Modal, ButtonFactory } from '@cargos/cs-modal';
import { MyFormComponent } from './my-form.component';

csModal.confirm<MyFormComponent>({
  content: { componentClass: MyFormComponent },
  buttons: [
    ButtonFactory<MyFormComponent>('confirm', {
      action: ({ contentInstance }) => {
        return contentInstance.isFormValid();
      }
    })
  ],
  onContentReady: ({ contentInstance }) => {
    contentInstance.init();
  }
});

Further help

Coming soon.