Form for data sources

The Form widget enables you to incorporate user interactivity into your data app. This widget allows you to configure various inputs, and it will then generate an interactive form for users to employ in filtering the data.

For uses when you don't want to filter a data source and just let the user choose or input from a defined set of values, you may use the Form for defined values

Basic usage

To use the Form widget, you need a Widget Query linked to some data source. Once you have your query, create a Form widget and configure its Input variable field. This widget works by filtering the input query and generating a new query result in the configured output variable. You may choose which columns you want in the result with the Output columns configuration. If no output columns are specified all be included in the output query.

Now, go to the 'Filters' tab, and start adding the columns you want to include in the form. For each item, you will select the column name and then the Selector you want to use for it.

When you have configured all your columns, save and you will see the form rendered in the widget. Now, if you fill all the fields, you can click on the Submit button to save the output on the selected variable. You can use this output on your Python code, or display it in a Table, Chart or KPI widget.

info

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

tip

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

Retrieve selected values

In addition to the resulting query that you will get in the Output variable of the widget. You may want to use any of the individually selected values of your configured filters. For that Widget form will add to the notebook context one variable per configured filter in the widget.

After the form is submitted you can read the value selected on other widgets or on the python code.

The variable names are constructed using the Output variable and the name of each filter (the column name).

For instance , a widget with an output variable named 'out1' and a filter for the column 'name' will add a variable named 'out1_name' to your context.

API reference

Basic

Setting name	Type	Description	Default
Input variable	widget query variable	The input query that will be filtered. You will need a configured widget query for some data source.
Output columns	string	The columns desired in the output query after filtering.
Output variable	string	The variable to store the output.

Filters

Configuration for each element added to the form.

Basic

Setting name	Type	Description	Default
Column	string	The column name in the data source.
Type	string Readonly	The column type.
Label	string	The label to show in the form.	<column_name>
Selector	Dropdown | Bool: as checkbox | Date selector: from | Date selector: to | Date selector: same day | Date range picker: dates | Date range picker: months | Date range picker: years | Date range picker: date and time | Multiple	The input type to use	Select
Visible	boolean	Whether to include the column in the form.	true
Placeholder	string	The placeholder to show in the input.
Default value	string	The default value for the input.
Default select all	boolean	Whether to select all options by default.	false
Required	boolean	Whether the input is required in the form.	true
Order	No order | Ascending order | Descending order	Data sorting for the column elements.	No order
Dependencies	string/column_name[]	Columns that this selector depends on. Changes on those dependencies will refresh the selector
Span	1-24	Number of grid cells for this item	6
Offset	0-24	Number of grid cells to offset this item	0

Format

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

Events

Setting name	Type	Description	Default
Submit mode	submit button | submit on change	The mode to submit the form.	submit button
Submit button label	string	The label for the submit button.	Submit
Show reset button	boolean	Whether to show a button to reset the form.	false
Reset button label	string	The label for the reset button.

Format

Format options for the form.

General

Setting name	Type	Description	Default
Title layout	Top | Inline	The layout for the title (label) of each input	Top
Horizontal gutter	8 | 16 | 24 | 32 | 40 | 48	The horizontal gutter between the form elements, in pixels.	24
Vertical gutter	8 | 16 | 24 | 32 | 40 | 48	The vertical gutter between the form elements, in pixels.	24
Debug grid	boolean	Whether to show the grid for the form.	false

Buttons

Setting name	Type	Description	Default
Align	Start | End | Center	The alignment for the buttons	Start
Span	1-24	Number of grid cells for the buttons	6
Offset	0-24	Number of grid cells to offset the buttons	0

See also

• All widgets — browse the full widget catalog.
• Query — build the query this form filters.