User Interface Helpers

JupyterLab comes with helpers to show or request simple information from a user. Those speed up development and ensure a common look and feel.

Dialogs

Message Dialogs

Helper functions to show a message to the user are available in the apputils package. These dialogs return a Promise resolving when the user dismisses the dialog.

There is one helper:

  • showErrorMessage : show an error message dialog.

Input Dialogs

Helper functions to request a single input from the user are available in the apputils package within the InputDialog namespace. There are four helpers:

  • getBoolean : request a boolean through a checkbox.

  • getItem : request a item from a list; the list may be editable.

  • getNumber : request a number; if the user input is not a valid number, NaN is returned.

  • getText : request a short text.

All dialogs are built on the standard Dialog. Therefore the helper functions each return a Promise resolving in a 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);
});

File Dialogs

Two helper functions to ask a user to open a file or a directory are available in the filebrowser package under the namespace FileDialog.

Here is an example to request a file.

const dialog = FileDialog.getExistingDirectory({
  iconRegistry, // IIconRegistry
  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({
  iconRegistry, // IIconRegistry
  manager // IDocumentManager
});

const result = await dialog;

if(result.button.accept){
  let folders = result.value;
}

Note

The document manager and the icon registry can be obtained in a plugin by requesting IFileBrowserFactory token. The manager will be accessed through factory.defaultBrowser.model.manager and the iconRegistry through factory.defaultBrowser.model.iconRegistry.