openModal

How to use

openModal method takes an object as an argument. This object should contain at least the component key which should point to your Modal component. You could also add a props key pointing to an objecting containing extra properties that will be passed down the modal component.

import { Plugin } from '@root'
import MyModal from '@components/MyModal'

const App = () => {
    const handleOpenMyModal = useCallback(() => {
        Plugin.openModal({
            component: MyModal,
            props: {
                // pass down custom props to MyModal component
            }
        })
    }, [])
    
    return (
        <div>
            <button onClick={handleOpenMyModal}>
                {'Open my modal'}
            </button>
        </div>
    )
}

Properties

Name	typeof	default	Description
size	String	NORMAL	The size of your modal, check out available sizes below
menu	Component || Node	null	A custom component to be rendered in the header of the modal
title	String	undefined	A title for the modal to be displayed in the header
customStyle	String || Object || Styled-Component's style	undefined	Custom css style for the modal
withHeader	Boolean	true	A flag if Dashboard should render a header with a close icon
closeOnClickOutside	Boolean	false	A flag if Dashboard should close the modal if a click happened outside of the modal context

Sizes

Dashboard comes with a range of predefined sizes you'll be able to choose from in order to render your modal.

Choose your size by first retrieve the available ones form the PluginAPI

import { Plugin } from '@root'

const modalSizes = Plugin.MODALSIZE

Name	size
AUTO	Depends on your modal actual size, width: unset, height: unset
NORMAL	max-height: 93%, max-width: 1024px
WIDE	max-width: 85%, max-height: 93%
FULL	max-width: 100%, max-height: 100%

Multiple modals

Before Dashboard 4.1, modals used to be rendered by calling Plugin.modal.open(...) And that allowed the plugins to render one modal at a time, but with the new ModalAPI, Dashboard supports opening multiple modals at the same time without un-mounting the previous ones.

For example, if you call the deprecated method Plugin.modal.open(...) while you have a modal already rendered, Dashboard will un-mount the rendered modal, and mount the new one. When them a user closes the modal, Dashboard will close the current opened one without going back to the previous one

With the new API Dashboard will stack the modals on top of each other every time Plugin.openModal(...) has been called

So to open multiple modals, simply call Plugin.openModal(...) with your new modal properties

Confirm before close

You can tell Dashboard to display a confirm prompt to the user, when the user tries to close your modal This could be appropriate to do if your modal has changes that will get lost, or still processing some data.

Dashboard will look into your modal component ref and check if the ref has aonBeforeClose() method. If so Dashboard will call the method and wait for it to resolve or reject, therefore it should return a promise.

If onBeforeClose() resolves then Dashboard will close the modal right away. If it's rejected, Dashboard will display a dialog to the user to confirm closing the modal, or cancel.

You can specify the dialog message along with the dialog button labels. You also can register callbacks to see what action the user took, onConfirm/onCancel

The object you reject with, will be the dialog params

Dialog params

Param	Typeof	Required	Description
message	String	*	A message to be displayed to the user within the dialog
localizations	Object		Button labels localization strings
onCancel	Function		On cancel callback will be called when the user clicks on Cancel button or closes the dialog
onConfirm	Function		On confirm callback will be called when the user clicks on Confirm button

Example

import {
    Plugin
} from '@root'

import {
    useRef,
    forwardRef,
    useImperativeHandle
} from 'react'

const MyModal = (props, ref) => {
    const hasChanges = useRef()
    
    useImperativeHandle(ref, () => ({
        onBeforeClose: () => {
            return new Promise((resolve, reject) => {
                if (hasChanges.current) {
                    reject({
                        message: 'Are you sure you want to cancel?'
                        localizations: {
                            cancel: 'Continue editing',
                            confirm: 'Discard my changes'
                        },
                        onCancel: () => {},
                        onConfirm: () => {}
                    })
                } else {
                    resolve()
                }
            })
        }
    }))
    
    return (
        <div>
            <p>{'My awesome modal'}</p>
        </div>
    )
}

export default forwardRef(MyModal)