docs/source/extension/ui_helpers.md
% Copyright (c) Jupyter Development Team.
% Distributed under the terms of the Modified BSD License.
JupyterLab comes with helpers to show or request simple information from a user. Those speed up development and ensure a common look and feel.
To display a generic dialog, use {ts:function}apputils.showDialog function from @jupyterlab/apputils.
The options available are:
showDialog({
title: 'Dialog title', // Can be text or a react element
body: 'Dialog body', // Can be text, a widget or a react element
host: document.body, // Parent element for rendering the dialog
buttons: [
// List of buttons
{
label: 'my button', // Button label
caption: 'my button title', // Button title
className: 'my-button', // Additional button CSS class
accept: true, // Whether this button will discard or accept the dialog
displayType: 'default' // applies 'default' or 'warn' styles
}
],
checkbox: {
// Optional checkbox in the dialog footer
label: 'check me', // Checkbox label
caption: "check me I'magic", // Checkbox title
className: 'my-checkbox', // Additional checkbox CSS class
checked: true // Default checkbox state
},
defaultButton: 0, // Index of the default button
focusNodeSelector: '.my-input', // Selector for focussing an input element when dialog opens
hasClose: false, // Whether to display a close button or not
renderer: undefined // To define customized dialog structure
});
:::{note} If no options are specified, the dialog will only contain OK and Cancel buttons. :::
Use the {ts:namespace}apputils.Dialog helpers from {ts:module}apputils to
get consistent labels, styling and behavior:
apputils.Dialog.okButton: creates an accept button (accept: true) with a default localized Ok label.apputils.Dialog.cancelButton: creates a reject button (accept: false) with a default localized Cancel label.apputils.Dialog.warnButton: creates a warning-styled button (displayType: 'warn'); acceptance and label still follow {ts:function}apputils.Dialog.createButton.apputils.Dialog.createButton: generic helper; if accept is omitted it defaults to true, and the default label is Ok for accept buttons and Cancel otherwise.You only need to provide label when you want custom text.
Helper functions to show a message to the user are available in the {ts:module}apputils package.
These dialogs return a Promise resolving when the user dismisses the dialog.
There is one helper:
apputils.showErrorMessage : show an error message dialog.Helper functions to request a single input from the user are available in the apputils
package within the {ts:namespace}apputils.InputDialog namespace. There are four helpers:
apputils.InputDialog.getBoolean : request a boolean through a checkbox.apputils.InputDialog.getItem : request a item from a list; the list may be editable.apputils.InputDialog.getNumber : request a number; if the user input is not a valid number, NaN is returned.apputils.InputDialog.getText : request a short text.apputils.InputDialog.getPassword : request a short password.All dialogs are built on the standard {ts:namespace}apputils.Dialog namespace using the {ts:class}apputils.Dialog class.
Therefore the helper functions each return a Promise resolving in a {ts:interface}apputils.Dialog.IResult object.
// Request a boolean
InputDialog.getBoolean({ title: 'Check or not?' }).then(value => {
console.log('boolean ' + value.value);
});
// Request a choice from a list
InputDialog.getItem({
title: 'Pick a choice',
items: ['1', '2']
}).then(value => {
console.log('item ' + value.value);
});
// Request a choice from a list or specify your own choice
InputDialog.getItem({
title: 'Pick a choice or write your own',
items: ['1', '2'],
editable: true
}).then(value => {
console.log('editable item ' + value.value);
});
// Request a number
InputDialog.getNumber({ title: 'How much?' }).then(value => {
console.log('number ' + value.value);
});
// Request a text
InputDialog.getText({ title: 'Provide a text' }).then(value => {
console.log('text ' + value.value);
});
// Request a text
InputDialog.getPassword({ title: 'Input password' }).then(value => {
console.log('A password was input');
});
:::{note} Try these helpers in a browser playground:
Load Current File As Extension.<script type="text/plain" id="jp-plugin-playground-source-ui-helpers">
import { JupyterFrontEnd, JupyterFrontEndPlugin } from '@jupyterlab/application';
import {
Dialog,
ICommandPalette,
InputDialog,
MainAreaWidget,
Notification,
showDialog
} from '@jupyterlab/apputils';
import { FileDialog, IDefaultFileBrowser } from '@jupyterlab/filebrowser';
import { Widget } from '@lumino/widgets';
const plugin: JupyterFrontEndPlugin<void> = {
id: 'ui-helpers-demo:plugin',
autoStart: true,
requires: [ICommandPalette, IDefaultFileBrowser],
activate: (
app: JupyterFrontEnd,
palette: ICommandPalette,
defaultBrowser: IDefaultFileBrowser
) => {
const dialogCommand = 'ui-helpers-demo:dialog';
const inputCommand = 'ui-helpers-demo:input';
const notificationCommand = 'ui-helpers-demo:notification';
const openFileDialogCommand = 'ui-helpers-demo:file-dialog-open';
const openFolderDialogCommand = 'ui-helpers-demo:file-dialog-folder';
const openPanelCommand = 'ui-helpers-demo:open-panel';
const runDialog = async () => {
await showDialog({
title: 'UI Helpers Demo',
body: 'This dialog is shown from an interactive documentation example.',
buttons: [Dialog.cancelButton(), Dialog.okButton({ label: 'Sounds good' })]
});
};
const runInput = async () => {
const result = await InputDialog.getText({
title: 'What should the notification say?'
});
if (result.button.accept && result.value) {
Notification.info(result.value, { autoClose: 3000 });
}
};
const runNotification = () => {
Notification.success('This is a success notification from the docs demo.', {
autoClose: 3000
});
};
const runOpenFilesDialog = async () => {
const result = await FileDialog.getOpenFiles({
manager: defaultBrowser.model.manager
});
if (result.button.accept) {
Notification.info(`Selected ${result.value.length} item(s).`, {
autoClose: 3000
});
}
};
const runOpenFolderDialog = async () => {
const result = await FileDialog.getExistingDirectory({
manager: defaultBrowser.model.manager
});
if (result.button.accept) {
const selectedPaths = result.value.map(item => item.path);
const message =
selectedPaths.length === 1
? `Selected folder: ${selectedPaths[0]}`
: `Selected folders: ${selectedPaths.join(', ')}`;
Notification.info(message, { autoClose: 3000 });
}
};
let panel: MainAreaWidget<Widget> | null = null;
const createActionButton = (
label: string,
action: () => Promise<void> | void
): HTMLButtonElement => {
const button = document.createElement('button');
button.type = 'button';
button.textContent = label;
button.style.padding = '0.4rem 0.75rem';
button.style.border = '1px solid var(--jp-border-color2)';
button.style.borderRadius = '6px';
button.style.background = 'var(--jp-layout-color1)';
button.style.cursor = 'pointer';
button.addEventListener('click', () => {
void Promise.resolve(action()).catch(error => {
console.error(error);
Notification.error('Demo action failed.', { autoClose: 4000 });
});
});
return button;
};
const ensurePanel = (): MainAreaWidget<Widget> => {
if (panel && !panel.isDisposed) {
return panel;
}
const content = new Widget();
const intro = document.createElement('p');
intro.textContent =
'Use these buttons to preview dialogs, notifications, and file dialogs.';
intro.style.margin = '0 0 0.75rem 0';
content.node.style.padding = '1rem';
content.node.appendChild(intro);
const actions = document.createElement('div');
actions.style.display = 'grid';
actions.style.gridTemplateColumns = 'repeat(auto-fit, minmax(220px, 1fr))';
actions.style.gap = '0.5rem';
actions.appendChild(createActionButton('Show Dialog', runDialog));
actions.appendChild(createActionButton('Ask For Text', runInput));
actions.appendChild(createActionButton('Show Notification', runNotification));
actions.appendChild(createActionButton('Open Files Dialog', runOpenFilesDialog));
actions.appendChild(createActionButton('Open Folder Dialog', runOpenFolderDialog));
content.node.appendChild(actions);
panel = new MainAreaWidget({ content });
panel.id = 'ui-helpers-demo:panel';
panel.title.label = 'UI Helpers Playground';
panel.title.closable = true;
return panel;
};
app.commands.addCommand(dialogCommand, {
label: 'UI Helpers Demo: Show Dialog',
execute: runDialog
});
app.commands.addCommand(inputCommand, {
label: 'UI Helpers Demo: Ask For Text',
execute: runInput
});
app.commands.addCommand(notificationCommand, {
label: 'UI Helpers Demo: Notify',
execute: runNotification
});
app.commands.addCommand(openFileDialogCommand, {
label: 'UI Helpers Demo: Open Files Dialog',
execute: runOpenFilesDialog
});
app.commands.addCommand(openFolderDialogCommand, {
label: 'UI Helpers Demo: Open Folder Dialog',
execute: runOpenFolderDialog
});
app.commands.addCommand(openPanelCommand, {
label: 'UI Helpers Demo: Open Playground Panel',
execute: () => {
const widget = ensurePanel();
if (!widget.isAttached) {
app.shell.add(widget, 'main');
}
app.shell.activateById(widget.id);
}
});
palette.addItem({ command: openPanelCommand, category: 'User Interface Helpers' });
palette.addItem({ command: dialogCommand, category: 'User Interface Helpers' });
palette.addItem({ command: inputCommand, category: 'User Interface Helpers' });
palette.addItem({ command: notificationCommand, category: 'User Interface Helpers' });
palette.addItem({ command: openFileDialogCommand, category: 'User Interface Helpers' });
palette.addItem({ command: openFolderDialogCommand, category: 'User Interface Helpers' });
void app.restored.then(() => {
void app.commands.execute(openPanelCommand);
});
}
};
export default plugin;
</script>
<div
class="jp-plugin-playground-embed"
data-playground-hide="all"
data-playground-source-id="jp-plugin-playground-source-ui-helpers"
data-playground-file-name="index.ts"
data-playground-title="User interface helpers interactive example"
data-playground-description="Interactive dialogs + notifications example."
></div>
Two helper functions to ask a user to open a file or a folder are
available in the {ts:module}filebrowser package under the namespace {ts:namespace}filebrowser.FileDialog.
Here is an example to request a file.
const dialog = FileDialog.getOpenFiles({
manager, // IDocumentManager
filter: model => model.type == 'notebook' // optional (model: Contents.IModel) => boolean
});
const result = await dialog;
if (result.button.accept) {
let files = result.value;
}
And for a folder.
const dialog = FileDialog.getExistingDirectory({
manager // IDocumentManager
});
const result = await dialog;
if (result.button.accept) {
let folders = result.value;
}
:::{note}
The document manager can be obtained in a plugin by
requesting {ts:variable}filebrowser.IDefaultFileBrowser token.
The manager will be accessed through
defaultBrowser.model.manager.
:::
JupyterLab has a notifications manager that can add, update or dismiss notifications. That feature
is provided by the @jupyterlab/apputils package.
:::{warning} It is a good practice to limit the number of notifications sent to respect the user's focus. Therefore by default, the notification won't be displayed to the user. But the status bar will indicate that a new notification arrived. So the user can click on the indicator to see all notifications.
Try adding a button Do not show me again for recurrent notifications to allow users to quickly
filter notifications that matters for them.
:::
A notification is described by the following element:
{
/**
* Notification message
*
* ### Notes
* Message can only be plain text with a maximum length of 140 characters.
*/
message: string;
/**
* Notification type
*/
type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
/**
* Notification options
*/
options?: {
/**
* Autoclosing behavior - false (not closing automatically)
* or number (time in milliseconds before hiding the notification)
*
* Set to zero if you want the notification to be retained in the notification
* center but not displayed as toast. This is the default behavior.
*/
autoClose?: number | false;
/**
* List of associated actions
*/
actions?: Array<IAction>;
/**
* Data associated with a notification
*/
data?: T;
};
}
At creation, a notification will receive an unique identifier.
Actions can be linked to a notification but the interface depends on how the notification is handled.
There are two ways of interacting with notifications: through an API or through commands. The only difference is that actions linked to a notification can have an arbitrary callback when using the API. But only a command can be set as an action when using the command call for creating a notification.
To create notification, you need to provide a message and you can use the following helpers
to set the type automatically (or use notify to set the type manually):
/**
* Helper function to emit an error notification.
*/
Notification.error(message: string, options?: IOptions): string;
/**
* Helper function to emit an info notification.
*/
Notification.info(message: string, options?: IOptions): string;
/**
* Helper function to emit a success notification.
*/
Notification.success(message: string, options?: IOptions): string;
/**
* Helper function to emit a warning notification.
*/
Notification.warning(message: string, options?: IOptions): string;
/**
* Helper function to emit a in-progress notification. Then
* it will update it with a error or success notification
* depending on the promise resolution.
*/
Notification.promise(
promise: Promise,
{
pending: { message: string, options?: IOptions },
/**
* If not set `options.data` will be set to the promise result.
*/
success: { message: (result, data) => string, options?: IOptions },
/**
* If not set `options.data` will be set to the promise rejection error.
*/
error: { message: (reason, data) => string, options?: IOptions }
}
): string;
/**
* Helper function to emit a notification.
*/
Notification.emit(
message: string,
type: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default' = 'default',
options?: IOptions
): string;
When using the API, an action is defined by:
{
/**
* The action label.
*
* This should be a short description.
*/
label: string;
/**
* Callback function to trigger
*
* ### Notes
* By default execution of the callback will close the toast
* and dismiss the notification. You can prevent this by calling
* `event.preventDefault()` in the callback.
*/
callback: (event: MouseEvent) => void;
/**
* The action caption.
*
* This can be a longer description of the action.
*/
caption?: string;
/**
* The action display type.
*
* This will be used to modify the action button style.
*/
displayType?: 'default' | 'accent' | 'warn' | 'link';
}
You can update a notification using:
Notification.update({
id: string;
message: string;
type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
autoClose?: number | false;
actions?: Array<IAction>;
data?: ReadonlyJsonValue;
}): boolean;
:::{note} Once updated the notification will be moved at the begin of the notification stack. :::
And you can dismiss a notification (if you provide an id) or all
notifications using:
Notification.dismiss(id?: string): void;
:::{note} Dismissing a notification will remove it from the list of notifications without knowing if the user has seen it or not. Therefore it is recommended to not dismiss a notification. :::
There are three commands available.
'apputils:notify' to create a notification:
commands.execute('apputils:notify', {
message: string;
type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
options?: {
autoClose?: number | false;
actions?: Array<IAction>;
data?: T;
};
});
The result is the notification unique identifier.
An action is defined by:
{
/**
* The action label.
*
* This should be a short description.
*/
label: string;
/**
* Callback command id to trigger
*/
commandId: string;
/**
* Command arguments
*/
args?: ReadonlyJsonObject;
/**
* The action caption.
*
* This can be a longer description of the action.
*/
caption?: string;
/**
* The action display type.
*
* This will be used to modify the action button style.
*/
displayType?: 'default' | 'accent' | 'warn' | 'link';
}
'apputils:update-notification' to update a notification:
commands.execute('apputils:update-notification', {
id: string;
message: string;
type?: 'info' | 'in-progress' | 'success' | 'warning' | 'error' | 'default';
autoClose?: number | false;
actions?: Array<IAction>;
data?: T;
});
The result is a boolean indicating if the update was successful. In particular, updating an absent notification will fail.
'apputils:dismiss-notification' to dismiss a notification:
commands.execute('apputils:dismiss-notification', {
id: string;
});
:::{note} Dismissing a notification will remove it from the list of notifications without knowing if the user has seen it or not. Therefore it is recommended to not dismiss a notification. :::