DialogManager

Overview

DialogManager shows the modal dialogs of Now.js. alert, confirm and prompt return a Promise of the user's answer;
custom builds a dialog from your own options and returns the element so you can drive it. Dialogs stack, and the
keyboard always acts on the topmost one.

Use it when:

• You want to inform, ask for confirmation, or ask for a value instead of window.alert/confirm/prompt
• You need a small dialog with your own buttons

For windows with a lot of content, forms, or data binding, use Modal.

Features:

• Promise-based API (await DialogManager.confirm(...))
• Opens with focus on the default button, so Enter answers it · Escape closes · Tab stays inside the dialog
• Drag the dialog by its header
• Backdrop through BackdropManager, page scrolling locked while open
• Messages and button labels go through Now.translate (except in custom)

Access and Initialization

DialogManager ships in the core bundle (now.core.min.js). DialogManager (global) and Now.getManager('dialog') are
the same object. Now.init() calls DialogManager.init() for you with the dialog key of its config, so you never call
init() yourself.

await Now.init({
  dialog: {
    closeOnBackdrop: false,  // clicking outside does not close
    draggable: false
  }
});

Configuration

API Reference

DialogManager.alert(message, title?, options?)

Shows a message with a single OK button.

Returns: Promise<true> — resolves once the dialog closes, however it is closed

await DialogManager.alert('Saved', 'Success');

DialogManager.confirm(message, title?, options?)

Asks for confirmation with Cancel and Confirm buttons (Confirm is the default button).

Returns: Promise<boolean> — true on Confirm; false on Cancel, Escape, the × button or the backdrop

if (await DialogManager.confirm('Delete this item?', 'Confirm delete')) {
  await deleteItem();
}

DialogManager.prompt(message, defaultValue?, title?, options?)

Asks for a value through an <input type="text" class="dialog-input">, with Cancel and OK buttons.

Returns: Promise<string|null> — the input value on OK or Enter ('' when empty); null on Cancel, Escape, the × button or the backdrop

const name = await DialogManager.prompt('Folder name', 'New folder', 'Create folder');
if (name !== null) {
  await createFolder(name);
}

There is no placeholder or input-type option; use custom with your own template if you need one.

Shared options of alert, confirm, prompt

options is merged over what the method builds, so it can replace any key of custom.
The ones that are safe to pass are:

buttons replaces the buttons that give the answer (see Common Pitfalls).
Change button labels through the translations of the keys OK, Cancel and Confirm.

DialogManager.custom(options)

Builds and shows a dialog from your own options, returning the element instead of a Promise.

Returns: HTMLElement — the shown dialog

custom does not translate anything; pass Now.translate(...) yourself. This example wraps it in a Promise that
resolves however the dialog is closed:

function askLeave() {
  return new Promise(resolve => {
    let answer = 'stay';
    DialogManager.custom({
      title: Now.translate('Unsaved changes'),
      message: Now.translate('Leave this page?'),
      buttons: {
        leave: {text: Now.translate('Leave'), class: 'btn-primary', callback: () => { answer = 'leave'; }},
        stay: {text: Now.translate('Stay'), default: true, callback: () => { answer = 'stay'; }}
      },
      // dialog:closed fires on every way of closing, including Escape, the × button and the backdrop
      onClose: () => resolve(answer)
    });
  });
}

Buttons

buttons is an object of {key: config}; buttons appear in key order, each as <button type="button" class="btn ...">.

DialogManager.show(dialog)

Shows a dialog made with createDialog (an element, id, or selector): positions it, adds the backdrop and sets focus.
A dialog already showing is not shown twice.

Returns: HTMLElement|null — null when the dialog cannot be found

DialogManager.createDialog(options)

Builds a dialog from the same options as custom (except onShow / onClose) without
showing it.

Returns: HTMLElement

const dialog = DialogManager.createDialog({title: 'Details', message: detailEl});
dialog.addEventListener('dialog:closed', cleanup);
DialogManager.show(dialog);

DialogManager.close(dialog)

Closes one dialog (an element, id, or selector): removes the show class, adds hiding, hides the backdrop, removes the
dialog from the DOM after duration ms, then gives focus back to whatever had it before the dialog opened and dispatches
dialog:closed.

Closing with close() does not run any button callback.

DialogManager.closeAll()

Closes every open dialog.

DialogManager.bringToFront(dialog)

Raises a dialog (an element, id, or selector) to the top, both in z-index and in the order the keyboard acts on.

Other methods

Default Button and Keyboard

A dialog opens with focus already where the user acts first, so Enter answers it without reaching for the mouse:

The default button is the first footer button with default: true; without one it is the first .btn-primary, then
the first footer button. Only a dialog with no footer buttons at all leaves focus on the header close button.

DialogManager.custom({
  title: 'Unsaved changes',
  message: 'Leave this page?',
  buttons: {
    leave: {text: 'Leave', class: 'btn-primary', callback: () => leave()},
    stay: {text: 'Stay', default: true, callback: () => {}}  // Enter = Stay
  }
});

Stacking and Backdrop

• The first dialog takes its z-index from the CSS variable --z-index-alert (default 1100), or baseZIndex when the
  variable is absent; each stacked dialog adds 2
• Each dialog has its own backdrop (one below the dialog's z-index) from BackdropManager; clicking it closes only that
  dialog when closeOnBackdrop is on
• Escape closes one layer at a time, from the top
• Dragging is clamped to the window, and buttons in the header do not start a drag

Template

A template is the inner HTML of <div class="dialog" role="dialog" aria-modal="true">. DialogManager finds its parts by
class:

An unknown template name falls back to alert. Templates given to Now.init() are added to the built-in ones:

await Now.init({
  dialog: {
    templates: {
      notice: `
        <div class="dialog-header"><h2 class="dialog-title"></h2></div>
        <div class="dialog-body"></div>
        <div class="dialog-footer"></div>
      `
    }
  }
});

DialogManager.custom({template: 'notice', title: 'Notice', message: '...', buttons: {...}});

Events

DOM CustomEvents dispatched on the dialog element. They do not bubble, so listen on the dialog element itself (from
custom / createDialog, or through onShow / onClose) and read the values from event.detail.

const dialog = DialogManager.custom({title: 'T', message: 'M'});
dialog.addEventListener('dialog:closed', (e) => {
  console.log('closed', e.detail.dialog.id);
});

Where the Framework Uses It

These parts call DialogManager.confirm() for you:

CSS Styling

Styles live in Now/css/dialog.css (the close button is in components.css).

CSS variables you can override (variables.css, dark theme in theme-dark.css):

:root {
  --dialog-bg: var(--color-background);
  --dialog-text: var(--color-text);
  --dialog-border: rgba(0, 0, 0, 0.1);
  --dialog-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
  --z-index-alert: 1100;
}

If you change the transition time, set duration to match, or the dialog is removed before it finishes fading.

Common Pitfalls

⚠️ 1. Await the Promise

// ❌ Deletes at once without waiting for the answer
DialogManager.confirm('Delete?');
deleteItem();

// ✅
if (await DialogManager.confirm('Delete?')) {
  deleteItem();
}

⚠️ 2. prompt returns null on Cancel and '' on OK with nothing typed

const value = await DialogManager.prompt('Name');
if (value === null) return;   // cancelled
if (value === '') { ... }     // OK without typing

⚠️ 3. Build messages with user data as elements

A string message is HTML. What can run code is removed from it (DOMPurify when the page has it, otherwise <script>,
<iframe> and similar elements, on* attributes and script URLs), but markup in the data is still shown as markup. To show
text as text, pass an element filled with textContent.

// ❌ A name containing <b> or <a> changes what the dialog shows
await DialogManager.confirm(`Delete ${user.name}?`);

// ✅
const msg = document.createElement('p');
msg.textContent = `Delete ${user.name}?`;
await DialogManager.confirm(msg);

⚠️ 4. Passing buttons to alert/confirm/prompt loses the answer

Your buttons replace the ones that give the answer, so the Promise settles with the "closed" value (false, null) whichever
button is pressed. For other buttons or labels with their own answers, use custom.

⚠️ 5. custom does not translate

alert/confirm/prompt go through Now.translate, but custom, createDialog and button text do not; call
Now.translate() yourself.

Related Documentation

• BackdropManager - The dialog backdrop
• Modal - Windows with a lot of content or forms
• NotificationManager - Messages that need no answer
• I18nManager - Translations of messages and button labels