How to Create User Input Fields in a Custom Analysis Tool

This article describes how to add input controls to a custom analysis tool so that users can select options and enter values.

Requirements

• A custom analysis tool that you created via Calculation > Custom Code.
• You have read How to Create a Custom Analysis Tool.

Method

Like Rules, input fields that appear in custom analysis tools are RuleForm objects which are treated as properties of a form variable. This GUI allows various methods of defining and interrogating controls.

There are various types of input controls that can be added to a form. Each has its own set of arguments but many of them are common. We will now go through these controls using the example at the start of this article. I have laid out each argument below on a separate line to make things clearer but this is not a requirement.

numericUpDown

form.numericUpDown({name: "number", 
label: "Choose a number:",
default_value: 1,
increment: 2,
minimum: 1,
maximum: 100,
prompt: "This is a numeric control"})

• We use form.numericUpDown to create a numeric field with up and down selectors.
• We add a reference name and category label to the left of the control.
• We are able to set the default value.
• We are also able to change the minimum, maximum, and increment selector values. Note, the default values for these parameters are 0, 100, and 1 respectively.
• Finally, we add an optional tooltip prompt.

checkBox

form.checkBox({name: "checkbox", 
label: "Tick me",
default_value: true,
prompt: "This is a checkbox control"})

• We use form.checkBox to create a checkbox selector.
• We add a reference name and category label to the left of the control.
• We are able to set the default value which is either true or false.
• Finally, we add an optional tooltip prompt.

textBox

form.textBox({name: "textbox", 
label: "Enter text:",
default_value: "*",
type: "text",
required: false,
expression: false,
multi: false,
prompt: "This is a textbox control"})

• We use form.textBox to create a text field.
• We add a reference name and category label to the left of the control.
• We are able to set the default value and the format type (i.e. text or number).
• We are also able to change the defaults from true for requiring a response and treating the input as an expression rather than a string that requires quotes.
• We can change the type of text box from a single-line text box to a multi-line box by changing multito true. This allows for the input of large amounts of text to the custom analysis tool. 
• Finally, we add an optional tooltip prompt.

comboBox

form.comboBox({name: "combobox", 
label: "Select an option:",
alternatives: ["Yes","No"],
default_value: "Yes",
required: false,
expression: false,
prompt: "This is a combo box control"})

• We use form.comboBox to create a combo box.
• We add a reference name and category label to the left of the control.
• We set the alternatives as an array of categories to choose from.
• We are able to set the default value which must be included in the alternatives array.
• We are also able to change the defaults from true for requiring a response and treating the input as an expression rather than a string that requires quotes.
• Finally, we add an optional tooltip prompt.

listBox

form.listBox({name: "listbox", 
label: "Select an option:",
alternatives: ["Option 1","Option 2"],
initialValues: ["Option 1"],
multiSelection: true,
required: false,
nItemsVisible: 2,
prompt: "This is a list box control"})

• We use form.listBox to create a list box.
• We add a reference name and category label to the left of the control.
• We set the alternatives as an array of categories to choose from. Note, if these labels differ from those in the source data pulled in via R, you can add a further argument to match the corresponding labels: names: ["Option1","Option2"]. Both arrays need to have the same number of items.
• We are able to set the initial values which must be included in the alternatives array. Note, if we use the names argument, these values must match this array instead. 
• We are also able to change the defaults for multiple selections, requiring a response, and the height of the input field (which is no more than 5 rows by default).
• Finally, we add an optional tooltip prompt.

dropBox

form.dropBox({name: "dropbox", 
label: "Select all options:",
types: ["Variable"],
multi: true,
min_inputs: 1,
max_inputs: 10,
height: 5,
duplicates: true,
required: false,
expression: false,
prompt: "This is a drop box control"})

• We use form.dropBox to create a drop box.
• We add a reference name and category label to the left of the control.
• We set the selection types argument to restrict what objects are able to be shown. Allowable objects include variables and variable sets from the Data Sources tree or tables, R calculations, and page controls from your document.
• We are able to set the control to accept multiple inputs.
• When multiple inputs are allowed, we can change the defaults for the minimum and maximum number of inputs, as well as the height of the input field (which is no more than 4 rows by default), and whether the same input is allowed to appear twice.
• We are also able to change the defaults from true for requiring a response and treating the input as an expression rather than a string that requires quotes.
• Finally, we add an optional tooltip prompt.

colorPicker

form.colorPicker({name: "colorpicker", 
label: "Select a color",
default_value: [255,0,0],
prompt: "This is a colorpicker control"})

• We use form.colorPicker to create a color picker selector.
• We add a reference name and category label to the left of the control.
• We are able to set the default value using either the HTML color hex value (#FF0000) or the RGB color value [255, 0, 0]. See JavaScript Color Table for examples.
• Finally, we add an optional tooltip prompt.

datePicker

form.datePicker({name: "datepicker", 
label: "Select a date",
default_value: "2021-01-01",
prompt: "This is a datepicker control"})

• We use form.datePicker to create a date picker selector.
• We add a reference name and category label to the left of the control.
• We are able to set the default value in the YYYY-MM-DD date format.
• Finally, we add an optional tooltip prompt.

dataEntry

form.dataEntry({name: "dataentry", 
label: "Enter data:",
edit_label: "Edit data:",
required: false,
default_value: [["Brand A","Brand B"],["1","2"]],
prompt: "This is a data entry control"})

• We use form.dataEntry to create a data entry spreadsheet.
• We add a reference name and category label to the left of the control. Note, the default label is Add Data...
• We are able to set the default content via a nested array in the format of[[row1-col1,row1-col2][row2-col1,row2-col2]].
• We are also able to change the "edit" label from the default of Edit Data..., which appears after editing the spreadsheet, and whether the input requires data entry.
• Finally, we add an optional tooltip prompt.

Set controls

Unlike with Rules, for custom analysis tools, we don't need to declare each control first and then pass these through as an array to form.setInputControls(), and then add the lineBreakAfter parameter. By omitting this function, Displayr will automatically layout the controls in a vertical tabular layout (labels on the left, controls on the right), in the order in which the controls were added, which is normally what is desired. See also How to Create User Input Fields in a Rule.

Next

How to Set Conditional Controls in a Custom Analysis Tool

Later

How to Set Object Types in DropBox Controls in Custom Analysis Tools

How to Reference Controls in a Custom Analysis Tool Using R

See Also

How to Create a Custom Analysis Tool

How to Create an Auto-Updating Custom Analysis Tool

How to Create User Input Fields in a Rule