How to Create User Input Fields in a Rule

Introduction

This article describes how to add input controls to a Rule form so that users can select options and enter values.

 

Requirements

• A table with a Rule applied.
• This article assumes you are already in the Automate > Custom Rule or Edit Rule > Edit JavaScript Rule view specified in How to Use Rules in Q and How to Customize a Rule.
• You have read How to Create a Custom Rule.

 

Method

Input fields that appear in Rules are RuleForm objects which are treated as properties of a form variable. This Rule form allows various methods of defining and interrogating controls.

 

Let's begin by setting the heading of the form as Custom Rule:

form.setHeading("Custom Rule");

 

Set up controls for user input

There are two basic types of variables that can be declared in a form: controls and labels.

 

Controls are created using the basic format of form.newControlType() whereby various arguments are available based on the control type. Labels, on the other hand, can be positioned before or after a control by using form.newLabel(label).

 

By default each variable will appear on the same row in your form unless you add a line break like below:

control_name.lineBreakAfter = true

Importantly, all controls must have unique names, except for labels, which have no names.

 

There are various types of input controls that can be added to a form. Each has their 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.

 

newNumberBox(name)

var numberLabel = form.newLabel("Enter a number:");
var numberControl = form.newNumberBox("number");
numberControl.setDefault(1);
numberControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newNumberBox to create a numeric field.
• We are able to set the default value.
• Finally, we add a line break so the next control appears in a different row.

newNumericUpDown(name)

var numericLabel = form.newLabel("Choose a number:");
var numericControl = form.newNumericUpDown("numeric");
numericControl.setDefault(10);
numericControl.setMinimum(1);
numericControl.setIncrement(1);
numericControl.setMaximum(100);
numericControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newNumericUpDown to create a numeric field with up and down selectors.
• We are able to set the default, minimum and maximum values, as well as set the increments when using the selectors. 
• Finally, we add a line break so the next control appears in a different row.

newTextBox(name)

var textLabel = form.newLabel("Enter text:");
var textControl = form.newTextBox("text");
textControl.setDefault('*');
textControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newTextBox to create a text field.
• We are able to set the default value.
• Finally, we add a line break so the next control appears in a different row.

newComboBox(name, [categories])

var comboLabel = form.newLabel("Select an option:")
var comboControl = form.newComboBox("combo", ["Yes","No"]);
comboControl.setDefault("Yes");
comboControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newComboBox to create a combo box with an array of categories to choose from.
• We are able to set the default value which must be included in the categories array.
• Finally, we add a line break so the next control appears in a different row.

newStatisticPicker(name)

var statLabel = form.newLabel("Choose a statistic:");
var statControl = form.newStatisticPicker("stat")
statControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newStatisticPicker to create a combo box with a list of all available statistics.
• The primary statistic on your table will be selected by default.
• Finally, we add a line break so the next control appears in a different row.

newColorPicker(name)

var colorLabel = form.newLabel("Select a color:")
var colorControl = form.newColorPicker("color");
colorControl.setDefault([255,0,0]);
colorControl.lineBreakAfter = true;

• We first add a label so it will be positioned to the left of our control.
• We then use form.newColorPicker to create a color picker selector.
• 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 a line break so the next control appears in a different row.

newCheckBox(name, label)

var checkControl = form.newCheckBox("check", "Tick me");
checkControl.setDefault(true);

• We first use form.newCheckBox to create a checkbox selector with a category label.
• We are able to set the default value which is either true or false.

 

Set controls

After creating all the input fields for our form, we now need to place them inside an array to pass to the form.setInputControls() function.

The order of the items within the array will be the order they are displayed in the form. The labels and controls need to both be referenced by name:

var form_controls = [numberLabel,numberControl,numericLabel,numericControl,textLabel,textControl,comboLabel,comboControl,statLabel,statControl,colorLabel,colorControl,checkControl];
form.setInputControls(form_controls);

A further option is to display a preview of a control's selection at the bottom of the form. This can be achieved by using the form.setOutputControls() function:

form.setOutputControls([colorControl]);

Note, controls will not appear in your form unless passed to one of these functions.

 

Validate and reference input fields

Once you have set up your Rule form controls, the next step is applying validations and pulling the values from the input fields.

 

To force a user input to have a value, where a default has not been set, you can append the requireValue() property to the control name:

numberControl.requireValue()

You can then, for example, include this value in the summary that appears on the Rules tab:

var val = numberControl.requireValue();
form.setSummary("Perform rule when n < " + val);

 

To return each of the values for our controls, we use the getValue() property:

numberControl.getValue()
numericControl.getValue()
textControl.getValue()
comboControl.getValue()
statControl.getValue()
colorControl.getValue()
checkControl.getValue()

 

Next

How to Add Table Validations to Rules

 

Later

How to Reference and Calculate Tables in a Rule

How to Add Table Spans Using a Rule

How to Add a Custom Table Footnote

How to Custom Sort Tables

 

See Also

How to Use Rules in Q

How to Customize a Rule

How to Create a Custom Rule

How to Access Statistics from a Table in a Rule