Widgets

Define widget with YAML

Widget name is a variable name

Definition of the widget (in params) starts with the widget name. It should correspond to the variable in the code (in the notebook). The name should be a valid Python variable.

In the below example, the variable_name is the name of variable in the code and it is a widget name:

params:
    variable_name:
        input: text
        label: Please provide the text

Widget input type

The widget is selected by input type. It can be: text, slider, range, select, checkbox, numeric, file.

Widget label

For each widget we need to define a label. It will be a text displayed above (or near) the widget.

Widget default value

You can set a default value of the widget by setting the value. The format of the value depends on the input type:

  • for text a value should be a string, example value: example text,
  • for slider a value should be a number, example: value: 5,
  • for range a value should be a list with two numbers, example value: [3,6],
  • for select with mutli: False a value should be a string, example value: hey,
  • for select with multi: True a value should be a list of strings, example value: [cześć, hi, hello],
  • for checkbox a value should be a boolean (True or False), example: value: True,
  • for numeric a value should be a number, example: value: 10.2.
  • for file a value is not needed.

The rest of the parameters depend on the widget input type.

Widgets

Text

Available parameters:

  • input: text - defines the text widget,
  • label - the label above the widget,
  • value - the default value of the widget, should be a string,
  • rows - the number of rows in the text area (default is set to 1),

Example YAML:

params:
    my_variable:
        input: text
        label: This is text label
        value: some text
        rows: 2

The widget view:

Mercury Text Widget

Slider

Available parameters:

  • input: slider - defines the slider widget,
  • label - the label above the widget,
  • value - the default value of the widget, should be a number,
  • min - the minimum value for the slider (default is set to 0),
  • max - the maximum value for the slider (default is set to 100).

Example YAML:

params:
    my_variable:
        input: slider
        label: This is slider label
        value: 5
        min: 0
        max: 10

The slider view:

Mercury Slider

Range

Available parameters:

  • input: range - defines the range widget,
  • label - the label above the widget,
  • value - the default value of the widget, should be list of two numbers, for example: [3, 6],
  • min - the minimum value for the slider (default is set to 0),
  • max - the maximum value for the slider (default is set to 100).

Example YAML:

params:
    range_variable:
        input: range
        label: This is range label
        value: [3,6]
        min: 0
        max: 10

Mercury Range

Select

Available parameters:

  • input: select - defines the select widget,
  • label - the label above the widget,
  • multi - a boolean value that decides if the user can select several options (default is set to False).
  • for mutli: False a value should be a string, example value: hey,
  • for multi: True a value should be a list of strings, example value: [cześć, hi, hello],
  • choices - a list with available choices.

Example YAML:

params:
    select_variable:
        label: This is select label
        input: select
        value: Cześć
        choices: [Cześć, Hi, Hello]
        multi: False

The select view:

Mercury Select

Checkbox

Available parameters.

  • input: checkbox - defines the checkbox widget,
  • label - the label above the widget,
  • value - should be a boolean (True or False), example: value: True,

Example YAML:

params:
    checkbox_variable:
        label: This is checkbox label
        input: checkbox
        value: True

The checkbox view:

Mercury Checkbox

Numeric

Available parameters:

  • input: numeric - defines the numeric widget,
  • label - the label above the widget,
  • value - should be a number, example: value: 5.5.
  • min - a minimum allowed value (default set to 0),
  • max - a maximum allowed value (default set to 100),
  • step - a step value (default set to 1).
params:
    numeric_variable:
        label: This is numeric label
        input: numeric
        value: 5.5
        min: 0
        max: 10
        step: 0.1

The numeric view

Mercury Numeric

File Upload

Available parameters:

  • input: file - defines the file widget,
  • label - the label above the widget,
  • maxFileSize - a maximum allowed file size (default set to 100MB). The file size should be defined as a string with MB or KB at the end.
params:
    filename:
        label: This is file label
        input: file
        maxFileSize: 1MB

The file upload view:

Mercury File

The uploaded file name will be passed to the notebook as a string. The uploaded file will be copied to the same directory as the notebook. After notebook execution, the uploaded file will be removed.

Example YAML

The example YAML with several widgets:

---
title: My notebook
author: Piotr
description: My first notebook in Mercury
params:
    my_variable:
        label: This is slider label
        input: slider
        value: 5
        min: 0
        max: 10
    range_variable:
        label: This is range label
        input: range
        value: [3,6]
        min: 0
        max: 10    
    select_variable:
        label: This is select label
        input: select
        value: Cześć
        choices: [Cześć, Hi, Hello]
        multi: False
    checkbox_variable:
        label: This is checkbox label
        input: checkbox
        value: True
    numeric_variable:
        label: This is numeric label
        input: numeric
        value: 5.5
        min: 0
        max: 10
        step: 0.1
---

Widgets rendered from above YAML config:

Mercury widgets

Widgets to variables

To use widgets as variables in the code simply define the variable with the same name as the widget name. You can also assign the same default value as defined in the YAML. Please define all variables in one cell (it can be below the cell with YAML config).

When the user interacts with widgets and clicks the Run button, the code with variables will be updated with user selected values.

Example:

Mercury Variables