Form for Defined Values

The Form widget allows you to filter and input data in your data app. By defining one or more Python variables or static values, you can render an interactive form for user input.

If you want to filter a data source (tabular data), consider using the Form for Data Sources.

This is an example of a form:

Basic usage

The first thing you need to do is configure the output variable name (prefixed with $), such as $out. By default, every form comes configured with an output variable that will store all the selected values. You can change the name if you prefer.

Next, you need to add Elements, which are the main building blocks of the form. To add elements, go to the Elements section and start adding the selectors you want to include in the form. For each element, specify the Element Name, Type, and the Selector you want to use.

• Name: Defines the name of the element. This name should be unique within the entire data app, as it will be used as a global parameter.
• Type: Defines the data type of the element (e.g., String, Number, Boolean).
• Selector: Defines the type of selector used from a predefined list (e.g., Dropdown, Checkbox).

Some types of selectors, such as dropdowns, will require you to define Options. You can specify these options in the box by separating them with commas or by binding a Python variable (prefixed with $) containing your options.

After you have filled in all the required fields, you can click the Submit button to save the output to the selected variable. You can then use this output in your Python code or display it in a table, chart, or KPI widget.

info

By default, all selectors are included in the form as required fields. This means that the execution of the notebook will stop until all required fields are filled.

If you do not want the execution to stop, you can either have no required fields or set default values for all required fields.

Retrieving selected values

Each time the form is submitted, the selected values are stored in the context as Python variables.

The Output Variable will be stored in the Python context as a dictionary containing the selected values.

In addition to this dictionary, one variable per element is created with the structure of the Output Variable followed by the Name of each selector. For example, a widget with an output variable named out1 and a selector named name will add a variable named out1_name to your context.

Dependencies

If you want to add dependencies between selectors, you have three options:

1. Change Their Options: If a variable used in the Options of a selector is changed in another block, the selector will be reinitialized to its default value.

2. Reset on Selector Change: Use the field called Reset on Selector Change to indicate the names of one or more elements from other selectors (separated by commas) that, when changed, will reset the current selector to its default value.

3. Bind a Variable: You can bind a variable to the element. This binding works both ways: every time the variable is modified, the element will update, and vice versa.

Supported form selectors

Dropdowns

Widgets that allow users to select options from a list by clicking on a drop-down menu.

• Dropdown
• Multiple Dropdown

Boolean

Interactive elements for choosing between two options, typically representing true or false states.

• Checkbox
• Switch

Dates

Widgets for selecting dates or date ranges for various purposes, such as filtering data or setting appointments.

• Date Selector
• Date Range
• Date and Time Range
• Month Range
• Year Range

Text

Input fields for users to enter text data.

• Text Field: For single-line entries.
• Text Area: For multi-line entries.

Sliders

Interface elements that allow users to select a value or a range within a specified range by moving a slider handle.

• Number Slider
• Range Slider

Radio

Widgets for selecting a single option from a list or multiple options from a list, typically presented as radio buttons or checkboxes.

• Radio Button
• Radio Button Group
• Multiple Checkboxes

Setting initial values from URL parameters

You can pre-fill form elements by binding them to variables initialized from URL query parameters. This allows sharing links with pre-configured forms (e.g., ?category=Electronics&date_range=2023-01-01_2023-12-31).

Implementation steps

1. Capture URL Parameters in Early Block: In a Python block before your form widget, initialize variables using MINEO_SELECTORS:

   # Capture URL parameters with fallback defaults
   initial_category = MINEO_SELECTORS.get('category', 'All')
   initial_date_range = MINEO_SELECTORS.get('date_range', '2023-01-01_2023-12-31')

2. Then use any of those variables as Variable binding in your widget.

API reference

Basic

Setting Name	Type	Description	Default
Output Variable	string	The variable to store the output (prefixed with $).

Elements

Configuration for each element added to the form.

Basic

Setting Name	Type	Description	Default
Name	string	The identifier name for the element. This should be unique within the data app.
Type	enum	The data type of the element (String, Number, Boolean, etc.).	String
Selector	enum	The type of selector to use (e.g., Dropdown, Checkbox).
Options	Comma-separated values or Python variable	Options for dropdowns or selection inputs. You can enter values separated by commas or bind a Python variable containing a list of values (prefixed with $).
Label	string	The label to display in the form.	<Name>
Help Text	string	Help text displayed in the selector before selecting any value.
Required	boolean	Whether the input is required in the form.	true
Order	No order | Ascending | Descending	Data sorting for the options.	No order
Default Value	string	The default value for the input.
Reset on Selector Change	string	Names of other selectors (separated by commas) that, when changed, will reset the current selector to its default value.
Variable Binding	Python variable	The Python variable to bind to this element (two-way binding).

Layout

Setting Name	Type	Description	Default
Span	number	Number of grid cells for this item (1–24).	6
Offset	number	Number of grid cells to offset this item (0–24).	0

Format

Setting Name	Type	Description	Default
Suffix	string	The suffix for the value.
Numeral Format	string	The format to use for the value. See Numeral.js for more information.

Style

Customize the typography of the selector.

Setting Name	Type	Description	Default
Label Style	object	Style settings for the label.
Value Style	object	Style settings for the input value.

Format

Format options for the form.

General

Setting Name	Type	Description	Default
Horizontal Gutter	number	Horizontal space between form elements, in pixels (8–48).	24
Vertical Gutter	number	Vertical space between form elements, in pixels (8–48).	24
Size	enum	Size of the elements (Small, Middle, Large).	Middle
Alignment	enum	Vertical alignment of the form (Top, Middle, Bottom).	Middle
Title Layout	enum	Layout for the title (label) of each input (Top, Inline).	Top
General Span	number	Default grid cells for each item (1–24).	6
General Offset	number	Default grid offset for each item (0–24).	0
Label Style	object	Style settings for all labels.
Value Style	object	Style settings for all values.

Buttons

Setting Name	Type	Description	Default
Submit Mode	enum	Mode to submit the form (Submit Button, Submit on Change).	Submit Button
Submit Button Label	string	The label for the submit button.	Submit
Show Reset Button	boolean	Whether to display a button to reset the form.	false
Reset Button Label	string	The label for the reset button.
Align	enum	Alignment for the buttons (Start, End, Center).	Start
Span	number	Grid cells for the buttons (1–24).	6
Offset	number	Grid offset for the buttons (0–24).	0

---

See also

• All widgets — browse the full widget catalog.
• Form for data sources — filter a query instead of defining static values.