@cargos/cs-modal

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.