How to Set Conditional Controls in a Custom Analysis Tool

This article describes how to create conditional controls in a custom analysis tool that only appears when specific selections have been made.

Requirements

• A custom analysis tool that you created via Calculation > Custom Code.
• You have read How to Create a Custom Analysis Tool and How to Create User Input Fields in a Custom Analysis Tool.
• Depending on the inputs, you may need a Displayr license.

Method

In some cases, GUI (Graphical User Interface) controls may only be relevant to the user if they have specified a particular option first. Controls that are not relevant to the current selections may then be hidden from view so as not to make an unnecessarily large or confusing form. For example, you may have a drop box to choose from several versions of regression methods, and depending on your selection in this box, you may need to specify other options or parameters that are relevant to the selected regression which are not relevant to other regressions.

Creating conditional input controls

The approach for conditional scenarios is to use if...else statements and other logic in the JavaScript form code to control when a control should appear.

Important things to note:

• It is not possible to interrogate variables, variable sets, tables, or R calculations selected in the form via JavaScript. The form is not capable of making decisions based on the type of input (e.g. Variable Type) of an object selected in a drop box.
• It is also not possible to refer to optional controls using substitution functions, like QInputs(). See How to Reference Controls in a Custom Analysis Tool Using R.

To achieve this in a form:

• The control whose value determines whether or not other options are shown must be declared explicitly as a JavaScript variable in the form code (i.e. with var).
• The getValue() method is used to obtain the currently-selected value of the control where only a single selection is possible, and getValues(), which returns an array, when multiple selections are possible.
• Place the lines which create optional controls within an if statement that refers back to the value obtained in the previous step.

In the below example, our first control is a combo box called "combo1" which has been declared as my_option.

The second control, a checkbox called "check1", is only then shown when we select "Option 2":

var my_option = form.comboBox({name: "combo1", label: "Choose an option:", alternatives:["Option 1", "Option 2"]});
if (my_option.getValue() == "Option 2") {
form.checkBox({name: "check1", label: "Check me", default: false}); 
}

Referencing conditional input controls

When a GUI control is not shown on the form then it does not exist and it does not provide any value to R. As a result, the corresponding R code must be written in such a way as to never attempt to obtain the value of the control when the control does not exist, as this will generate an error and prevent the item from running. You can still refer to the name of the control but your code must never try to evaluate it. Instead, you must use R code that can anticipate the presence or absence of the condition.

Using our previous example, we would wrap any code to be applied to "check1" within a condition for "combo1" which replicates when the checkbox would be shown:

if (combo1 == "Option 2") {
    ... do something
} else {
    ... do something
} 

Alternatively, we can use the exist function to see if our checkbox is present:

if (exists("check1")) TRUE else FALSE

Next

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

Later

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 Custom Analysis Tool