React Dialog Manager

Manage dialogs throughout the react application. React Dialog Manager gives you a clear declarative API to easily handle the dialog's behaviour.

• Installation
• Getting Started
• Examples
• API
• todo
• Contribution

Installation

using npm:

npm install --save react-dialog-manager

Getting Started

React Dialog Manager gives you great functionalities and flexibility to handle the dialogs of your react projects. Let's start with the following implementaiton.

import React from 'react';
import {createDialogManager, DialogManagerComponent} from 'react-dialog-manager';
 
const dialogManager = createDialogManager();
const dialog = dialogManager.createDialog({
    title: 'The Dialog Title',
    body: <TestForm  />
});
 
class App extends React.Component{
 
    constructor(props){
        super(props);
    }
 
    onOpenBtnClicked(){
        dialog.open();
    }
 
    onCloseBtnClicked(){
        dialog.close();
    }
 
    render(){
        return (
            <div className="App">
                <div>
                    <button onClick={this.onOpenBtnClicked.bind(this)}>Open Dialog</button>
                    <button onClick={this.onCloseBtnClicked.bind(this)}>Close Dialog</button>
                </div>
                <DialogManagerComponent manager={dialogManager} />
            </div>
        );
    }
}
 
function TestForm(props){
    /* dialog is passed within props */
    let {dialog} = props;
    return (
        <form>
            <input type="text" />
        </form>
    );
}
 
export default App;

From the previous implementation we can get some points;

• <DialogManagerComponent /> this ReactComponent is imported from react-dialog-manager and it's recommended to be at higher level in the application as shown in previous snippet. This component takes only one prop which is manager.

// dialogManager comes from createDialogManager or getLastDMInstance
<DialogManagerComponent manager={dialogManager} />

• createDialogManager this function is also imported from react-dialog-manager to create a DialogManager instace with two main params.

let setting = {}; // setting for manager
let instanceName = 'base_dialogs_manager'; // acts as id or key. just used for identification.
const dialogManager = createDialogManager(setting, instanceName);

Note, Sometimes, we use dialogManager in different places through our app to create dialogs so instead of making a seperate singleton object to handle this process, we can use getLastDMInstance function which also is exported from react-dialog-manager.

• createDialog once you have already created a dialogManager, you can create as much as you need of dialogs. You can, easily, interact with dialog throuth API.

const dialogManager = createDialogManager();
let definition = {}; // definition of the dialog like its title, its header, its body ... etc.
const dialog = dialogManager.createDialog(definition);
 // open the dialog
dialog.open();
 // close the dialog
dialog.close();

Expamples

Let's go throght some examples.

• Basic Example

import React from 'react';
import {
    createDialogManager,
    DialogManagerComponent
 } from 'react-dialog-manager';
 
 
const dialogManager = createDialogManager({}, 'BASE_DM');
const dialogA = dialogManager.createDialog({
    title: 'The Dialog Title',
    body: (
        <div>
            <p>Hello World</p>
        </div>
        )
});
 
class App extends React.Component{
 
    constructor(props){
        super(props);
    }
 
    onBtnAClicked(){
        dialogA.open();
    }
 
    onBtnBClicked(){
        let definition = {
            title: 'Dialog B',
            body: 'the body content'
        };
        let dialogInstanceName = 'DIALOG_B';
        /* will get dialogInstance of 'DIALOG_B'. In case of not existing -> create new one */
        dialogManager.getLastDialogInstance(definition, dialogInstanceName).open();
    }
 
    render(){
        return (
            <div className="App">
                <div>
                    <button onClick={this.onBtnAClicked.bind(this)}>Open Dialog A</button>
                    <button onClick={this.onBtnBClicked.bind(this)}>Open Dialog B</button>
                </div>
                <DialogManagerComponent manager={dialogManager} />
            </div>
        );
    }
}
 
export default App;

• Nested Dialogs Example

const dialogManager = createDialogManager({}, 'BASE_DM');
const dialogA = dialogManager.createDialog({
    title: 'The Dialog Title',
    body: <DialogBody />,
    close_by_overlay: false /* will not close when clicking on overlay layer */
});
 
class App extends React.Component{
 
    onBtnAClicked(){
        dialogA.open();
    }
 
    render(){
        return (
            <div className="App">
                <div>
                    <button onClick={this.onBtnAClicked.bind(this)}>Open Dialog</button>
                </div>
                <DialogManagerComponent manager={dialogManager} />
            </div>
        );
    }
}
 
function DialogBody(props){
    return (
        <div>
            <button 
                onClick={() => {
                    dialogManager.getLastDialogInstance({
                        title: 'I am nested dialog',
                        body: <div>Awesome!</div>
                    }, 'NESTED_DAILOG').open();
                }}
            >
                Open Nested Dialog
            </button>
        </div>
    );
}
 
export default App;

• Open - Close Handlers Examples

const dialogManager = createDialogManager({}, 'BASE_DM');
 
/* will not open beacuse of the before_open handler returns false */
const dialogA = dialogManager.createDialog({
    before_open: (d)=>{
        return false;
    }
});
 
/* will console.log 'on dialog opened' after dialog opening */
const dialogB = dialogManager.createDialog({
    on_open: (d)=>{
        console.log('on dialog opened');
    }
});
 
/* will not close after clicking on done button beacuse of the before_done handler returns false */
const dialogC = dialogManager.createDialog({
    before_done: (d)=>{
        console.log('e.g. form validation');
        return false;
    }
});

API

Modules

react-dialog-manager

This module is responsible for handling the instantiation of DialogManager and also, exporting the DialogManagerComponent

• DialogManager
  • new DialogManager(setting, [instanceName])
  • .createDialog(definition, [instanceName]) ⇒ Dialog
  • .getDialogs() ⇒ Array
  • .getInstanceName() ⇒ string
  • .getLastDialogInstance(definition, [instanceName]) ⇒ Dialog
  • .removeDialog(dialog)
• Dialog
  • new Dialog(definition, dialogMananger, [instanceName])
  • .before(eventName, handler)
  • .close()
  • .done()
  • .getBeforeHandlersOf(eventName) ⇒ function | Array.<function()>
  • .getBody() ⇒ ReactComponent | string
  • .getHandlersOf(eventName) ⇒ function | Array.<function()>
  • .getInstanceName() ⇒ string
  • .getOverlayStyle() ⇒ Object
  • .getStyle() ⇒ Object
  • .getTitle() ⇒ string
  • .getZIndex() ⇒ int
  • .isOpened() ⇒ boolean
  • .on(eventName, handler)
  • .open()
  • .set(definition, [value])
  • .setBody(body)
  • .setStyle(style)
  • .setTitle(title)
  • .setZIndex(zIndex)

react-dialog-manager

This module is responsible for handling the instantiation of DialogManager and also, exporting the DialogManagerComponent

• react-dialog-manager
  • .DialogManagerComponent
  • .createDialogManager(setting, instanceName) ⇒ DialogManager
  • .getDMInstances() ⇒ Array
  • .getLastDMInstance(setting, instanceName) ⇒ DialogManager

---

react-dialog-manager.DialogManagerComponent

Params

• DialogManagerComponent ReactComponent

Example

const dm = createDialogManager();
<DialogManagerComponent dialogManager="dm" />

---

react-dialog-manager.createDialogManager(setting, instanceName) ⇒ DialogManager

It will instantiate a new instance of DialogManager and store it as last instance.

Returns: DialogManager - dialogManager
Params

• setting Object
• instanceName Sting - The name used to identify the DialogManager instance. It's helpful wheu you call getLastDMInstance with the same instanceName

---

react-dialog-manager.getDMInstances() ⇒ Array

Returns: Array - intances

---

react-dialog-manager.getLastDMInstance(setting, instanceName) ⇒ DialogManager

Returns the last instance of DialogManger with the same provided instanceName param. In case of, there is no previous instance, it instantiates new one and returns it.

Returns: DialogManager - dialogManager
Params

• setting Object
• instanceName Sting = ''

---

DialogManager

• DialogManager
  • new DialogManager(setting, [instanceName])
  • dialogManager.createDialog(definition, [instanceName]) ⇒ Dialog
  • dialogManager.getDialogs() ⇒ Array
  • dialogManager.getInstanceName() ⇒ string
  • dialogManager.getLastDialogInstance(definition, [instanceName]) ⇒ Dialog
  • dialogManager.removeDialog(dialog)

---

new DialogManager(setting, [instanceName])

The instantiation of this class is done by createDialogManager

Params

• setting Object - Setting for the dialogs manager.
  • [.initial_z_index] int = 1000 - The start point where the z-indices of dialogs with begin. Each new dialog the initial_z_index will be incremented. For example; first dialog will have initial_z_index, second one will have initial_z_index + 1 and so on.
• [instanceName] string - The name of DialogManager instance

Example

import {createDialogManager} from 'react-dialog-manager';
 
const dm = createDialogManager({}, 'baseDM');

---

dialogManager.createDialog(definition, [instanceName]) ⇒ Dialog

Creates new dialog instance, and stores (pushs) it into the dialogs.

Returns: Dialog - dialog
Params

• definition Object - The definition of the new Dialog
• [instanceName] string - The (id) name of the new dialog instance

---

dialogManager.getDialogs() ⇒ Array

Retireve the dialogs that have been created.

Returns: Array - dialogs

---

dialogManager.getInstanceName() ⇒ string

Returns: string - instanceName - The name of dialogManager instance

---

dialogManager.getLastDialogInstance(definition, [instanceName]) ⇒ Dialog

Returns the last dialog instance of the provided instanceName. In case of there is no previous one with the provided instnaceName, we will create new dialog instance with the provide instancName.

Returns: Dialog - dialog
Params

• definition Object - The definition of the new Dialog
• [instanceName] string - The (id) name of the new dialog instance

---

dialogManager.removeDialog(dialog)

Removes (splices) the dialog instance from dialogs,

Params

• dialog Dialog

---

Dialog

• Dialog
  • new Dialog(definition, dialogMananger, [instanceName])
  • dialog.before(eventName, handler)
  • dialog.close()
  • dialog.done()
  • dialog.getBeforeHandlersOf(eventName) ⇒ function | Array.<function()>
  • dialog.getBody() ⇒ ReactComponent | string
  • dialog.getHandlersOf(eventName) ⇒ function | Array.<function()>
  • dialog.getInstanceName() ⇒ string
  • dialog.getOverlayStyle() ⇒ Object
  • dialog.getStyle() ⇒ Object
  • dialog.getTitle() ⇒ string
  • dialog.getZIndex() ⇒ int
  • dialog.isOpened() ⇒ boolean
  • dialog.on(eventName, handler)
  • dialog.open()
  • dialog.set(definition, [value])
  • dialog.setBody(body)
  • dialog.setStyle(style)
  • dialog.setTitle(title)
  • dialog.setZIndex(zIndex)

---

new Dialog(definition, dialogMananger, [instanceName])

The instantiation of this class is done by createDialog of DialogManager

Params

• definition Object - The definition of the dialog. By definition, we mean the properties like title, header, body ... etc.
  • .title string - The dialog's title.
  • [.allow_header] boolean = false - Whether allowing the header part of the dialog or not.
  • [.header] ReactElement - Sometimes, you might want to set custom header component. In this case the title will be ignore. You are responsible to set the title within the custom header.
  • [.body] ReactElement | string - The body component of the dialog. This ReactElement body will recieve the dialog within its props.
  • [.before_open] function | Array.<function()> - The handler(s) that will be invoked before dialog opening. It must return true to open the dialog, otherwise it will not.
  • [.on_open] function | Array.<function()> - The handler(s) that will be invoked once the dialog has been opened.
  • [.before_done] function | Array.<function()> - The handler(s) that will be invoked before dialog done (clicking on done button). It must return true to done the dialog, otherwise it will not.
  • [.on_done] function | Array.<function()> - The handler(s) that will be invoked once the dialog has been done.
  • [.before_close] function | Array.<function()> - The handler(s) that will be invoked before dialog closing. It must return true to close the dialog, otherwise it will not.
  • [.on_close] function | Array.<function()> - The handler(s) that will be invoked once the dialog has been closed.
  • [.close_by_overlay] boolean = true - Close the dialog when clicking on overlay layer or not.
  • [.style] Object - The style object for the dialog.
• dialogMananger DialogManager - This param is being passed by outter dialogManager during dm.createDialog({}).
• [instanceName] string - The (id) name of the dialog instance.

Example

import {createDialogManager} from 'react-dialog-manager';
 
const dm = createDialogManager({}, 'baseDM');
const dialog = dm.createDialog({});

---

dialog.before(eventName, handler)

Add event handler(s) before (open - done - close) actions.

Params

• eventName string - One of (open - done - close) event names.
• handler function | Array.<function()> - Event handler(s) that will be invoked with the dialog parameter before performing the corresponding action. Note, each handler must return true to go farther and execute the next steps.

Example

dialog.before('open', (dialog) => true );
dialog.before('done', [(dialog) => true, (dialog) => true] );

---

dialog.close()

First, we invoke all attached-event-handlers of before_close. All handlers should return true to go furhter and close (hide) the dialog.

---

dialog.done()

Done with the dialog as if you press the done button of the dialog.

---

dialog.getBeforeHandlersOf(eventName) ⇒ function | Array.<function()>

Returns: function | Array.<function()> - handler - Event handler(s) that will be invoked with the dialog parameter before performing the corresponding action.
Params

• eventName string - One of (open - done - close) event names.

---

dialog.getBody() ⇒ ReactComponent | string

Returns: ReactComponent | string - body

---

dialog.getHandlersOf(eventName) ⇒ function | Array.<function()>

Returns: function | Array.<function()> - handler - Event handler(s) that will be invoked with the dialog parameter once the corresponding action is performed.
Params

• eventName string - One of (open - done - close) event names.

---

dialog.getInstanceName() ⇒ string

Returns: string - instanceName - The name of dialog instance

---

dialog.getOverlayStyle() ⇒ Object

Returns: Object - overlayStyle

---

dialog.getStyle() ⇒ Object

Returns: Object - style - The (z-index) of the dialog.

---

dialog.getTitle() ⇒ string

Returns: string - title - The dialog's title.

---

dialog.getZIndex() ⇒ int

Returns: int - zIndex - The (z-index) of the dialog.

---

dialog.isOpened() ⇒ boolean

retrieve the (open/shown) state of dialog

Returns: boolean - IS_OPENED

---

dialog.on(eventName, handler)

Add event handler(s) once (open - done - close) actions are performed.

Params

• eventName string - One of (open - done - close) event names.
• handler function | Array.<function()> - Event handler(s) that will be invoked with the dialog parameter once the corresponding action is performed.

Example

dialog.on('done', (dialog) => console.log('dialog has been done') );
dialog.on('close', [(dialog) => console.log('dialog has been closed'), (dialog) => true] );

---

dialog.open()

First, we invoke all attached-event-handlers of before_open. All handlers should return true to go furhter and open (show) the dialog.

---

dialog.set(definition, [value])

set definition for the dialog

Params

• definition Object | string - Set the definition of the Dialog. You can set one property with the corresponding value.
• [value] * - In case of setting one property of definition, you could add the corresponding value.

Example

let dialogManager = createDialogsManager();
let dialog = dialogManager.createDialog();
dialog.set({
    title: 'Hello World!',
    body: 'good morning'
});
dialog.set('title', 'New Title Here');

---

dialog.setBody(body)

Params

• body ReactComponent | string - Set dialog's body.

---

dialog.setStyle(style)

Params

• style Object - The style of the dialog.

---

dialog.setTitle(title)

Params

• title string - Set the dialog's title.

---

dialog.setZIndex(zIndex)

Params

• zIndex int - The (z-index) of the dialog. Usually, manipulated by dialogManager.

---

todo

• manage WAI & scrolling
• manage keyboard interaction
• add more functionalities and options
• improve docs
• write some examples & demos
• make some styles & css
• add effects & animation features
• design logo & add some demo pics

Contribution

All of contribution will be appreciated. Remember to write test cases and documented code.