RuleForm

This feature is new in Q 4.8.

RuleForm

Provides Rules with methods for defining and interrogating controls. These controls will be shown to the user when the user creates or edits a Rule. Appears to Rule code as the form variable.

checkBox(arguments)

Creates a new labelled checkBox control. Note that the label is shown on the left. If you would prefer that the label is shown to the right of the checkBox, use the old-style form.newCheckBox(). If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for the tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.

Returns:

A new ScriptLabelledCheckBox object.

colorPicker(arguments)

Creates a new labelled control which allows the user to select a color. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.

Returns:

A new ScriptLabelledColorPicker object.

comboBox(arguments)

Creates a new labelled control to allow the user to select an item. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "alternatives": An array of strings to show in the drop down. "types": A list of allowed values (an array of strings). These may be 'Variable', 'Question' or 'Table'. "required": A flag indicating whether an input is required in order to be valid. Default: true. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: false. "prompt": The text (an html string) for the placeholder and the tooltip. Default: determined from "types". "error": The text (an html string) to be displayed if an unacceptable choice is made. Default: determined from "types". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page. Note that only one of "alternatives" and "types" should be specified.

Returns:

A new ScriptLabelledComboBox object.

controlInvalid(control, message)

Immediately aborts execution of the script and marks the specified control as invalid.

control	The control that the error relates to.
message	A message to show with that control.

dataEntry(arguments)

Creates a new labelled dataEntry control. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). If you omit this then the button will be automatically labelled. "edit_label": A label which replaces "label" when data has been added to the control. If you omit this then the button will be automatically labelled. "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for the tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page. "large_data_error": The error message text to be shown to the user if they attempt to include too many rows or columns in this data entry field, which defaults to "You may enter a table that is at most {0} x {1}. If you need to enter more data then upload it as a CSV file." if not set.

Returns:

A new ScriptLabelledDataEntry object.

datePicker(arguments)

Creates a new labelled control which allows the user to select a date. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "prompt": The text (an html string) for tooltip. Default: none. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.

Returns:

A new ScriptLabelledDatePicker object.

dropBox(arguments)

Creates a new labelled control to allow the user to drop input data dragged from elsewhere in the project.

May only be used in R Controls.

If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

"types" has the form of:

[Variable|Question|Table|RItem](:!*comma-separated-subtypes)?(:!*comma-separated-[hidden|filter|weight])

where the first part dictates the basic type, the second part modifies for subtypes, and the third further modifies for question tags. The second and third parts are optional and may be repeated as many times as desired.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "types": A list of allowed values (an array of strings). These may be 'Variable', 'Question' or 'Table'. "multi": A flag to indicate whether the control can accept more than one input. Default: false. "required": A flag indicating whether an input is required in order to be valid. Default: true. "min_inputs": The minimum number of inputs required. Default: if "required" then 1 otherwise 0. "max_inputs": The maximum number of inputs allowed. Default: no maximum. "height": The vertical size of the dropBox (in lines). Default: min(max_inputs, 4). "duplicates": A flag indicating whether the control permits the same input to appear twice. Default: false. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: true. "prompt": The text (an html string) for the placeholder and the tooltip. Default: determined from "types". "error": The text (an html string) to be displayed if an unacceptable input is being dragged into the dropBox. Default: determined from "types". "invalid": The text (an html string) indicating that the input is invalid. Default: "". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.

Returns:

A new ScriptLabelledDropBox object.

listBox(arguments)

Creates a new labelled control to allow the user to select one or more items from a list.

May only be used in R Controls.

If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "alternatives": An array of strings to show in the list box. "names": An array of strings corresponding to the alternatives which should be used as the actual output to R. "multiSelection": A flag to indicate whether the control should allow multiple selections. Default: false. "nItemsVisible": The maximum height of the control (in lines). Default: 5. "initialValues": A list of values corresponding to names if present or alternatives that is used to preset the selection. Default: none. "required": A flag indicating whether an input is required in order to be valid. Default: true. "prompt": The text (an html string) for the tooltip. Default: none. "error": The text (an html string) to be displayed if the control is required and not entered. Default: [Label] is required. "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page. Note that if both "alternatives" and "names" are specified they should be the same length.

Returns:

A new ScriptLabelledListBox object.

newCheckBox(control_name, text)

Creates a new control to show a checkbox. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
text	The text to show with the checkbox.
Returns:	A new ScriptCheckBox object.

newColorPicker(control_name)

Creates a new control to allow the user to select a color. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptColorPicker object.

newComboBox(control_name, alternatives, editable)

Creates a new control to allow the user to select an item. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
alternatives	An array of strings to show in the drop down.
editable	A boolean indicating whether the combobox can be edited by the user directly.
Returns:	A new ScriptComboBox object.

newDatePicker(control_name)

Creates a new control to allow the user to specify a date

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptDatePicker object.

newLabel(text)

Creates a new control that shows a few words of text. The text will only appear if given back to the form via setInputControls() or setOutputControls().

text	The string to show.
Returns:	A new ScriptLabel object.

newNumberBox(control_name)

Creates a new control to allow the user to enter a number. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptNumberBox object.

newNumericUpDown(control_name)

Creates a new control to allow the user to enter a number. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptNumericUpDown object.

newStatisticPicker(control_name)

Creates a new control to allow the user to select a statistic. See the ScriptStatisticPicker object for details. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptStatisticPicker object.

newTextBox(control_name)

Creates a new control to allow the user to enter text. The control will only appear if given back to the form via setInputControls() or setOutputControls().

control_name	A unique name for the control. It must not contain spaces or punctuation, nor begin with a number.
Returns:	A new ScriptTextBox object.

numericUpDown(arguments)

Creates a new labelled control to allow the user to enter a number. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "increment": The amount by which the number is raised or lowered when the up and down arrow buttons are pressed. Default is 1. "minimum": The minimum value for this number. Default is 0. "maximum": The maximum value for this number. Default is 100. "prompt": The text (an html string) for the tooltip. Default: none.

Returns:

A new ScriptLabelledNumericUpDown object.

ruleNotApplicable(because)

Immediately aborts execution of the Rule because it is not applicable to the data it is being run on. Other Rules applied to the item will continue to run.

because	Text that will be embedded in a message such as "This Rule is invalid because XXXX.", where your text replaces XXXX.
Example:	form.ruleNotApplicable("need at least two non-empty cells to calculate standard deviation")

setHeading(heading, options)

Provides the text to be shown before any input controls when the user creates or edits the Rule. It should help the user understand the purpose of the input controls.

heading	A string.
options	An optional dictionary of arguments to pass to the function: "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Example:	form.setHeading("Highlights cells with low n:");

setInputControls(controls)

Sets the list of controls that will appear in the form's top section. These are the main inputs to control what the Rule will do.

controls

An array of controls created by the other functions in this object.

setItemName(name)

Sets the name of the table/plot to which the rule is applied.

name	The new name for the table/plot.
Example:	form.setItemName('some new name');

setOutputColor(color)

Provides the color to be shown next to this Rule when it is listed. Call this if your control is highlighting using just a single color.

color	A color, probably returned form a ScriptColorPicker object.
Example:	form.setOutputColor(colorPicker.requireValue());

setOutputColors(colors)

Provides the two colors to be shown next to this Rule when it is listed. Call this if your control is highlighting using a blend between two or three colors.

colors	An array containing two or three colors.
Example:	form.setOutputColors([colorFromPicker.requireValue(), colorToPicker.requireValue()]);

setOutputControls(controls)

Sets the list of controls that will appear in the form's bottom section, after the label "Preview:". These controls are used to control the highlighting (if any) that the Rule will apply.

controls

An array of controls created by the other functions in this object.

setSummary(summary, options)

Provides the text to be shown next to this Rule when it is listed. It should concisely describe what the script does.

summary	A string.
options	An optional dictionary of arguments to pass to the function: "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.
Example:	form.setSummary("Highlights cells with n less than "+minimumN);

setTranslation(name_en, name_override)

Override the name of one of the statistics that appears on this table/plot. This is equivalent to changing the Output Text in Table/Plot Options.

name_en	English text that is normally used.
name_override	The text to use instead of the original. If null the default text is restored.
Example:	form.setTranslation('Column n', 'col n'));

textBox(arguments)

Creates a new control to allow the user to enter text. If setInputControls() is present, then then control will only appear if it is listed in the array given to setInputControls(), otherwise it will appear automatically.

arguments

A dictionary of arguments to pass to the function: "label": A label which appears adjacent to the control (a string). "name": The name of the control (a string). If not specified, one will be automatically created. "type": The name of the type used to validate the text (can only be "number" at the moment). Default: no validation. "required": A flag indicating whether an input is required in order to be valid. Default: true. "expression": Whether this output of this is to be treated as an expression, or requires quoting. Default: false. "prompt": The text (an html string) for the placeholder and the tooltip. Default: based on "type". "error": The text (an html string) to be displayed if an unacceptable input is given. Default: based on "type". "invalid": The text (an html string) indicating that the input is invalid. Default: "". "page": The name of the page in the Inspector to place the control on. The default is set by calling form.page, which in turn defaults to "Inputs". "group": The name of the group in the Inspector to place the control on. The default is set by calling form.group, which in turn defaults to "", which is an unnamed group at the top of the page.

Returns:

A new ScriptTextBox object.

type

Returns the name we use to refer to this class in the documentation.