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 goesyui_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.
opts.before_close is a guard. The modal asks it before each close that the
user starts: the Escape key, the background, the arrow or the X, and the Back
of the browser. Return false to stop the close. close() does not ask the
guard: it always closes. opts.on_close runs one time, after the modal goes.
When the guard asks a question first (for example, “all changes will be
lost”), return the promise of the question (since gobj-ui 7.26.38). The modal
stays open. When the Back of the browser started the close, the modal gets its
history entry back after the question. If the guard returns false after it
opens the question, the modal puts its entry back at once, above the entry of
the question: the next Back goes to the modal and not to the question, and the
modal asks again.
What the promise settles with is the answer (since gobj-ui 7.26.42): true
closes the modal, as a true returned at once does. Anything else is a veto:
undefined, false, or a rejection, which is logged. Before 7.26.42 any
promise was a veto, so an async guard that answered true left a modal that
nobody could close.
before_close: async () => {
return await draft_is_saved(); // true closes; false keeps the modal open
}An async guard closes the modal with return true, not with return;. An
async guard that ends with return; settles with undefined, and
undefined is a veto. When such a guard opened nothing through the shell, no
question is on the screen and the modal does not close. The modal then writes
a warning in the log (since gobj-ui 7.26.43): “before_close settled with
undefined and asked nothing”. When the guard asked a question, undefined is
its “no”, and the log gets nothing.
before_close: async () => {
if(!gobj_read_bool_attr(form, "edited")) {
return true; // not `return;`: that keeps the modal open
}
return yui_shell_confirm_yesno(shell, "all changes will be lost", {t: t});
}const sheet = yui_shell_show_modal(shell, $body, {
dialog: true,
title: "device settings",
t: t,
before_close: () => {
if(!gobj_read_bool_attr(form, "edited")) {
return true;
}
return yui_shell_confirm_yesnocancel(shell, "all changes will be lost", {t: t})
.then((answer) => {
if(answer === "yes") {
gobj_send_event(gobj, "EV_CLOSE_SHEET", {}, gobj); // its action calls sheet.close()
}
});
},
on_close: () => {
gobj_send_event(gobj, "EV_SHEET_CLOSED", {}, gobj); // its action destroys the form
}
});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".