# Popup (alert / confirm / prompt)

Links: [Home](../index.md)

Modal dialogs over a full-screen overlay: `alert()` with any number of buttons, `confirm()` (yes / no), `prompt()` (one text input) and a bare `popup()` you fill with your own DOM. Written by SGApps.IO; depends only on the framework's `extensions/prototype` (the `_()` DOM chain) and `uri-load` (for `elements/popup/style.css`).

## Loading the Module

```js
Application.require("elements/popup").then(function (Popup) {
    // Popup is a plain object: { popup, alert, prompt, confirm }
    Popup.alert('Saved', 'Your document has been saved.');
});
```

**Dependencies:** `extensions/prototype`, `uri-load`. The module links `elements/popup/style.css` (overlay, layout) when it loads. The dialog's look -- buttons, spacing, the icon font, the fade / bounce animation -- comes from the class names of the SGApps **RegalRoyal** theme (`rr-button`, `rr-block-space`, `rr-widget-box`, `rr-text-danger`, `websymbols`, `animated fadeIn` / `bounceIn`, `regal-royal--dark-theme`); with the theme stylesheet on the page (`https://sgapps.io/addons/RegalRoyal/styles/less/style.less.cache.css`) the dialogs look as in the playground, without it they get the browser's default buttons and no animation. The module works either way.

## The dialog structure

Every dialog is one `<table>` overlay appended to `document.body` by `show()` and removed by `hide()`:

```html
<table class="module__widget_popup rr-not-mobile">      popup.space   -- fixed, full screen, z-index 30199999, white 89 % + texture
  <tbody><tr><td>                                        -- the backdrop: click handling (see onOutsideClick)
    <div class="regal-royal">                            popup.body    -- the dialog box (50 % width, 350-800 px), theme classes go here
      <div class="module__widget_popup_controls"></div>  popup.header
      <div class="module__widget_popup_content"></div>   popup.content / popup.container -- your content, max-height 80vh, scrolls
      <div class="module__widget_popup_footer"></div>    popup.footer  -- the buttons
    </div>
  </td></tr></tbody>
</table>
```

## API

### `Popup.popup([node], [showOnLoad])`

Builds a bare dialog and returns the **popup object**.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `node` | `HTMLElement` | -- | Appended into `popup.content` when given |
| `showOnLoad` | `boolean` | `true` | `false` builds the dialog without showing it; `true` or omitted calls `show()` right away |

```js
var content = document.createElement('div');
content.innerHTML = '<h3>Custom content</h3><p>Any DOM goes here.</p>';
var popup = Popup.popup(content);                 // shown immediately
popup.footer.appendChild(closeButton);            // build your own buttons
popup.theme('dark');
```

#### The popup object

| Member | Type | Description |
|---|---|---|
| `show()` | method | Appends the overlay to `document.body` (no-op when already attached) |
| `hide()` | method | Removes the overlay from the DOM (the object stays usable, `show()` brings it back) |
| `theme(name)` | method | `'light'` -- `regal-royal` on the body, dark class removed; `'dark'` -- adds `regal-royal--dark-theme`; `'clean'` -- removes both classes. Anything else is ignored |
| `space` | `HTMLTableElement` | The overlay (`.module__widget_popup`) |
| `body` | `HTMLDivElement` | The dialog box (`.regal-royal`) -- getter |
| `header` | `HTMLDivElement` | `.module__widget_popup_controls` -- getter |
| `content`, `container` | `HTMLDivElement` | `.module__widget_popup_content` -- `content` is a getter, `container` the same node as a plain property |
| `footer` | `HTMLDivElement` | `.module__widget_popup_footer` -- getter |
| `onOutsideClick` | `boolean` or `function(popup, isBackdrop)` | Click handling on the backdrop cell, see below. Default `true` for `popup()`, `false` for `alert()` / `confirm()` / `prompt()` |

`header`, `content`, `body` and `footer` also have **setters, which do not work** (a string is silently dropped, a node is inserted as the text `[object HTMLElement]`). Always write through the getters: `popup.content.innerHTML = '...'`, `popup.footer.appendChild(button)`.

#### `onOutsideClick`

The `<td>` that fills the overlay listens to `click`:

| `popup.onOutsideClick` | Effect of a click |
|---|---|
| `false` | a click on the backdrop itself (outside the dialog box) calls `hide()`; clicks inside the box do nothing |
| `true` | nothing (the dialog can only be closed by its buttons or by `hide()`) |
| `function` | called for **every** click inside the overlay, inside the box included: `fn.call(td, popup, isBackdrop)` with `isBackdrop === true` when the click hit the backdrop -- decide yourself what to do |

`popup()` starts with `true` (backdrop clicks ignored); `alert()` (and therefore `confirm()` / `prompt()`) sets it to the **negation** of its `onOutsideClick` configuration key, so an alert closes on a backdrop click by default.

### `Popup.alert(title, [text], [callback])` / `Popup.alert(config)`

Builds a dialog with an icon, a title, a text and a row of buttons, shows it and returns the popup object (extended with `attachButton()` and `buttons`).

The first two arguments are flexible: a **string** is the title / text, an **Element** is inserted as is, a **function** becomes the callback of a single OK button, and a plain **object** is merged into the configuration -- so `alert('Title', 'Text')`, `alert('Title', 'Text', onOk)`, `alert({ title: ..., buttons: [...] })` and `alert(titleNode, { theme: 'dark' })` are all valid.

| Config key | Type | Default | Description |
|---|---|---|---|
| `title` | string, Element | `""` | Title line. With `html: true` a string is inserted as HTML |
| `text` | string, Element, `false` | `""` | Body text (a string is wrapped in `<center>`); with `html: true` inserted as HTML |
| `icon` | string, Element | `"N"` | A **websymbols glyph**: `"<char> [colour]"`, e.g. `"N danger"` -- the first token is the glyph, the second becomes the class `rr-text-<colour>` (`regular` when omitted). An Element is inserted as is; with `html: true` the string is inserted as HTML. Falsy: no icon |
| `theme` | string | `""` | Passed to `popup.theme()` when set: `'light'`, `'dark'`, `'clean'` |
| `buttons` | Array | `[{ text: 'OK', callback: hide, focused: true }]` | Button configurations, see `attachButton()`. An empty array gives a dialog without buttons |
| `html` | boolean | `false` | Insert `title`, `text` and `icon` strings as HTML instead of text |
| `focus` | boolean | `true` | Focus the button whose configuration has `focused: true` after showing |
| `focusWindow` | boolean | `true` | Call `window.focus()` after showing |
| `animate` | boolean | `true` | Add `animated fadeIn` to the overlay and `animated bounceIn` to the box (theme classes; the icon also gets `rotateInDownLeft`) |
| `visible` | boolean | `true` | Show the dialog now; `false` builds it hidden -- call `popup.show()` later |
| `onOutsideClick` | boolean, function | `false` | Close on a backdrop click? `true` **and omitted**: a click on the backdrop (outside the box) closes the dialog; `false`: backdrop clicks are ignored; a function is stored as is and called with `(popup, isBackdrop)` for every click in the overlay. (A boolean you pass is stored **negated** in `popup.onOutsideClick`, where `false` means "closes" -- see above; the default configuration is that internal `false`, hence "omitted" behaves like `true`) |

The generated content, inside `popup.content`:

```html
<div class="rr-block-24">
  <div class="rr-block-space">
    <span attr-icon="websymbols" rr-icon class="rr-text-danger animated ...">N</span>   <!-- icon -->
    <div class="rr-block-space">Delete 3 files?</div>                                   <!-- title -->
    <div class="rr-widget-box"></div>
    <div class="rr-block-space"><center>This cannot be undone.</center></div>          <!-- text -->
  </div>
</div>
```

#### `popup.attachButton(buttonConfig)` and `popup.buttons`

`alert()` runs every entry of `config.buttons` through `attachButton()`; you can call it later to add more.

| Button config key | Type | Default | Description |
|---|---|---|---|
| `text` | string, Element | `""` | Label |
| `callback` | `function (event, button)` | `function () { this.hide(); }` | Called with `this` = the popup object. Its return value is returned from the click handler (return `false` to cancel the event's default) |
| `className` | string | `""` | Extra class(es) on the `<button class="rr-button">`, e.g. `rr-button-danger`, `rr-button-info` |
| `focused` | boolean | `false` | Focused after `show()` when `config.focus` is on |

Returns a **button object**: `{ config, node, attach(), remove(), hide(), show(), focus() }` -- `node` is the `<button>`, `remove()` detaches it and drops it from `config.buttons`, `attach()` re-appends it to the footer. `popup.buttons` is the array of button objects created from the configuration.

### `Popup.prompt(title, [defaultValue], [callback])`

An `alert()` with a title line, one text input (`.module__widget_popup_row_input`, focused and selected) and **OK** / **Cancel** buttons.

| Parameter | Description |
|---|---|
| `title` | Text above the input |
| `defaultValue` | Initial value of the input |
| `callback(value, event, button)` | Called with `this` = the popup object; `value` is the input's value on **OK** and `undefined` on **Cancel**. Return `false` to keep the dialog open (validation) |

Returns the popup object.

### `Popup.confirm(title, [callback])`

An `alert()` with a centred title (a string is wrapped in a centred `<div>`; an Element or configuration object is passed through), no text, and **OK** / **No** buttons.

| Parameter | Description |
|---|---|
| `title` | Question |
| `callback(answer, event, button)` | `answer` is `true` for OK, `false` for No; `this` = the popup object. Return `false` to keep the dialog open |

Returns the popup object.

## Use Cases

### A confirmation with a dangerous action

```js
Application.require("elements/popup").then(function (Popup) {
    Popup.alert({
        title: 'Delete 3 files?',
        text: 'This cannot be undone.',
        icon: 'N danger',
        theme: 'dark',
        buttons: [
            { text: 'Delete', className: 'rr-button-danger', callback: function () { deleteFiles(); this.hide(); } },
            { text: 'Keep', focused: true }          // default callback: hide
        ]
    });
});
```

### Validate a prompt before closing it

```js
Application.require("elements/popup").then(function (Popup) {
    Popup.prompt('Project name', 'my-project', function (value) {
        if (value === undefined) return;             // Cancel: let it close
        if (!/^[a-z0-9-]+$/.test(value)) {
            this.content.querySelector('input').style.borderColor = 'red';
            return false;                            // keep the dialog open
        }
        createProject(value);
    });
});
```

### A dialog with a form and your own footer

```js
Application.require("elements/popup").then(function (Popup) {
    var popup = Popup.popup(null, false);           // built hidden
    popup.content.innerHTML = '<h3>Sign in</h3><input name="user" placeholder="user"><input name="pass" type="password">';

    var ok = document.createElement('button');
    ok.className = 'rr-button rr-button-info';
    ok.textContent = 'Sign in';
    ok.onclick = function () { login(popup.content.querySelector('[name=user]').value); popup.hide(); };
    popup.footer.appendChild(ok);

    popup.onOutsideClick = function (p, isBackdrop) { if (isBackdrop) p.hide(); };
    popup.show();
});
```

### An alert that reports through the Notify manager

```js
Application.require(["popup :: elements/popup", "notify :: elements/notify"]).then(function (libs) {
    var notify = libs.notify();
    document.body.appendChild(notify.node());
    // notify.alert / confirm / prompt / popup forward to the Popup module
    notify.confirm('Publish?', function (answer) {
        notify.info(answer ? 'Published' : 'Kept as draft');
    });
});
```

## Bundled examples: `elements/popup/user/login` and `.../registration`

`elements/popup/user/login.js` and `elements/popup/user/registration.js` (with their `template.html`) are sign-in and sign-up forms built on `Popup.alert({ visible: false, buttons: [] })`: they load Google reCAPTCHA, fill `popup.content.innerHTML` with the template, validate the fields, call a user resource and emit `Application.emit('API::user:logined', ...)`. They require `elements/google-re-capcha` and `resources/user`, which are **not part of this repository** -- treat them as reference code for a form dialog, not as loadable modules (they are not registered in `lib.js`).

## Notes

- Several dialogs can be open at once; each `show()` appends another overlay on top of the previous ones.
- `hide()` only detaches the overlay; keep the popup object to `show()` it again with its content intact.
- The `content`, `header`, `body`, `footer` **setters are broken** (see above) -- use the getters and normal DOM calls.
- With `focus: true` the `focused` button is focused after `show()`; keyboard users can then press Enter. Nothing closes the dialog on Escape -- add a `keydown` listener yourself.
- Live demo: [playground](playground.html#module=popup ':ignore :target=_blank').