Library: modal

modal module is a library to control a modal dialog box singleton, which is a container to host other content. Only one modal can be shown a time. It is a foundation of reno-modal.

Usage

In a module-enabled environment (like Babel) it can be accessed like that:

import * as modal from '@researchnow/reno/src/utils/modal';

In global-based environments (like a browser) it is frequently mapped to Reno.utils.modal.

open(options)

This function shows a modal box. It takes the following arguments:

• options is an object with the following properties:
  • content is a value accepted by hyperHTML as a possible content of a modal. For example, it can be a string or a DOM node.
    • If it is a DOM node, it will be appended to a popup, then discarded.
  • document is an optional document for a modal. The default: the current document.
  • loading is an optional value accepted by hyperHTML as a placeholder, which can be used to load an asynchronous content.
    • If it is a DOM node, it can be appended to a popup, then discarded.
  • title is an optional value accepted by hyperHTML as a title content. If not specified a modal box will have no title.
    • If it is a DOM node, it can be appended to a popup, then discarded.
  • buttons is an optional value accepted by hyperHTML or an array of strings as a button line. If not specified a modal box will have no buttons.
    • If it is a DOM node, it can be appended to a popup, then discarded.
    • If it is an array of strings, each item will be used to generate a button.
      • If a button text starts with one of these symbols: '!', '1', '2', or '3', it will be removed and a button will use a CSS class from these corresponding groups: caution, primary, secondary, or tertiary.
      • Otherwise, if a button text is "ok" or "cancel", it will use the corresponding buttons. (All comparisons are case-insensitive).
  • size is an optional string, which specifies a modal box size. It can be one of: "small", "medium", "large", "x-large". The default: "medium".
    • The sizes are defined by CSS. Currently, they are: small — 400 pixels, medium — 600, large — 900, x-large — 1200.
  • buttonStyle is an optional string suffix for a button CSS class. It is used to generate buttons from an array of strings (see buttons above). It can be one of these: "" (an empty string for small buttons, the default), "medium" for medium buttons, and "large" for large buttons.
  • customClass is an optional string, which specifies a custom CSS class for a modal box. The default: none.
  • eventHandler(evt) is an optional function, which is called when a user clicks a button or closes a modal. It takes one argument: an original event object. The default does nothing.

open() uses a DOM node with the reno-modal-container identifier attached to a document. If it is not there, <div id="reno-modal-container"> is created and attached to the body. Usually, the container is absolutely positioned. The exact snippet is:

<div id="reno-modal-container">
  <div class="reno-modal-background"></div>
  <div class="reno-modal-content">
    <div class="reno-modal"></div>
  </div>
</div>

.reno-modal is the node where all other content goes: a title, a content, and buttons.

Make sure that if you pass DOM nodes as content, loading, title, and/or buttons they can be discarded. If you use existing DOM nodes and plan on reusing them, do not forget to clone them first.

close(doc)

This function hides a modal. It takes the following arguments:

• doc is an optional document, which should be used to find a modal. The default: document.

isOpen(doc)

This function returns a boolean value: truthy when a modal is created and open or falsy otherwise. It takes the following arguments:

• doc is an optional document, which should be used to find a modal. The default: document.

CSS

The following CSS classes are used by modals:

• On body:
  • reno-modal-open is used when there is a visible modal.
  • reno-modal-close is used when a modal is closed.
    • This CSS class is assigned only when a modal is closed. Before showing any modals it is not present.
    • It is better to use reno-modal-open and its absence for styling open modals, and surroundings.

The default styling can be found in https://github.com/researchnow/reno/blob/master/src/styles/modal.scss

Examples

This example is similar to the demo: https://researchnow.github.io/reno/pages/component-modal.html

Reno.utils.modal.open({
  size: 'small',
  title: hyperHTML.wire()`<strong>Super</strong> simple dialog`,
  content: hyperHTML.wire()`Hello, <em>world</em>!`,
  buttons: ['OK', 'Cancel', '!Delete'],
  eventHandler: e => {
    alert('You pressed ' + e.target.innerText);
    Reno.utils.modal.close();
  }
});