gobj-ui: Dialogs and notifications

Dialogs and notifications¶

Source code: src/shell_modals.js

Every function takes the shell as its first parameter.

Notifications¶

A notification goes into the layer of the shell and goes away on its own after opts.timeout milliseconds. The default is 5000, and a value of 0 keeps it until somebody closes it. Each one gives {close} back.

Only one notification shows a given text at a time (since 7.25.7). When a string message of the same kind is already on screen, the call does not add a second one. But each call keeps its own {close} and its own time (since 7.25.8): the notification stays until every call has closed its {close} or timed out. The close button of the notification removes it for every call. A message made of elements is always added.

let first = yui_shell_show_error(shell, "the connection dropped");       // 5 s
let again = yui_shell_show_error(shell, "the connection dropped",
                                 {timeout: 0});                          // no time limit
// one notification on screen
first.close();      // it stays: `again` holds it
again.close();      // it goes

yui_shell_show_info(shell, message, opts)¶

Shows a message of information.

yui_shell_show_warning(shell, message, opts)¶

Shows a warning.

yui_shell_show_error(shell, message, opts)¶

Shows an error.

Modal¶

yui_shell_show_modal(shell, content, opts)¶

Puts an overlay in the layer of the modals. content accepts a string, which the function draws inside a box, or an element, which it draws as it is.

Returns {close}. The caller decides when to close it. A click on the background, the button of close and the Escape key close it too.

Confirmation¶

Each one gives a promise back. The buttons carry a label that the caller can change.

A label is an i18n key. The button translates it with opts.t (the translator of the app) and uses it three times: as its text, its title and its aria-label. So give lower-case keys that the locales of the app define, and give opts.t. The default labels are keys too (since gobj-ui 7.25.16): "ok", "yes", "no", "delete" and "cancel". Before that release they were "OK", "Yes", "No", "Delete" and "Cancel", which no locale can hold, so the buttons stayed in English in every language. An app that shows these dialogs defines the five keys; its validate-locales script asks for them.

import {t} from "i18next";

// The defaults: the app's locales define "yes" and "no"
yui_shell_confirm_yesno(shell, "remove this connection?", {t: t})
    .then((yes) => {
        if(yes) {
            gobj_send_event(gobj, "EV_REMOVE_CONNECTION", {id: conn_id}, gobj);
        }
    });

// Own labels: keys again
yui_shell_confirm_danger(shell, "delete account", {
    t:             t,
    confirm_label: "delete",
    cancel_label:  "cancel"
});

// en.js of the app
"yes": "Yes", "no": "No", "ok": "OK", "delete": "Delete", "cancel": "Cancel",
"remove this connection?": "Remove this connection?",

yui_install_ask_once() (the offer to install the app) asks "install this app" when the app gives no opts.message, and answers with "install" and "not now". Before 7.25.16 its default question was "Install this app?".

yui_shell_confirm_ok(shell, message, opts)¶

Shows a message with one button. The promise gives undefined back. opts.ok_label changes the label; the default is "ok".

yui_shell_confirm_yesno(shell, message, opts)¶

Asks a question with two answers. The promise gives true for yes. opts.yes_label and opts.no_label change the labels; the defaults are "yes" and "no".

yui_shell_confirm_yesnocancel(shell, message, opts)¶

Asks a question with three answers. The promise gives "yes", "no" or "cancel". The labels are opts.yes_label, opts.no_label and opts.cancel_label; the defaults are "yes", "no" and "cancel".

Use it when the third answer is a real one. A question such as “play all” has three answers and not two: add, replace, or cancel.

yui_shell_confirm_danger(shell, message, opts)¶

Asks a destructive question. The promise gives true only when the user presses the red button. opts.confirm_label and opts.cancel_label change the labels, and the defaults are "delete" and "cancel".