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.

Output widgets

You can specify Markdown text in the sidebar. The syntax is as following:

params:
    some_text:
        output: markdown
        value: | 
            ## header

            This is Markdown text in the sidebar. 

            - one
            - two
            - three

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:

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:

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

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:

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:

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. There will be no minimum if not set.
• max - a maximum allowed value. There will be no maximum if not set.
• 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

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:

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:

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: