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

Introduction

This article describes how to set the input type for dropBox user controls in a custom analysis tool. This includes variables, variable sets, tables, R items and page controls.

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.

Method

DropBox control types

Drop box controls can pull in variables and variable sets from the Data Sets tree or tables, R calculations and page controls from your document. These objects are referenced as follows:

• Variable (i.e. for the variable type)
• VariableSet (i.e. for the structure of combined variables)
• Question (i.e. for all other combined variable properties such as Usable as a filter, Usable as a weight and Hidden except in the data tree)
• Table (i.e. for default tables)
• RItem (i.e. for R-based calculations, tables and visualizations)
• Control (i.e. for any controls added to a page)

It’s important to note here that the names of these objects are case-insensitive and don't care about spaces or hyphens. The primary types may even be abbreviated in some instances so any prefix of Variables, Questions and RItems is acceptable.

For example, v or var could be used for Variables, q or quest for Questions, or r or R for RItems.

Control labels for variables

• For variables, the format of the label displayed in the control is dictated by its Structure, that is, whether it is part of a multiple-variable set.
• For single-variable questions, the Label is shown.
• For multiple-variable sets, the combined Label and the variable Label are shown, separated by a colon.
• When returning variables, the variable Name is included in square brackets.
• When multiple data sets are loaded in your document, the name of the data set will also be included in square brackets.

Filtering by subtype

The dropBox command allows users to place restrictions on the sort of inputs they accept. This information is specified using the types parameter when constructing a drop box control. These types can in turn be restricted to their respective subtypes by adding a comma-separated list of all the allowed subtypes as an array.

For example, Variable is restricted to the union of Numeric, Categorical and Ordered Categorical subtypes in the following example:

form.dropBox({label: "Categorical or Numeric Variables:", types: ["Variable:Numeric,Categorical,Ordered Categorical"]})

These types may also be restricted to those which are tagged as hidden, a filter or a weight, by adding the corresponding restrictions. Prefixing one of these restrictions with ! will instead apply a NOT condition to this restriction.

So, for example, Variable:!hidden will accept all non-hidden variables, while Variable:filter,!weight will accept either any variable which is a filter or any variable that is not a weight. Note, this is different to Variable:filter:!weight which instead would return any variable that is a filter and is also not a weight.

The key difference here is using a colon essentially treats the condition as AND while the comma treats it as OR.

Below are some further examples of ways to filter by subtype:

Any Nominal - Multi variable set or any Categorical or Ordered Categorical variable:

types: ["VariableSet: NominalMulti", "Var: Categorical, OrderedCategorical"]

Any Ordinal - Multi variable set:

types: ["VariableSet: OrdinalMulti"]

Any filter which is not hidden or any R item:

types: ["q:!hidden:filter", "R"]

Any variable set which is neither a Binary - Multi nor Numeric:

types: ["VariableSet:!BinaryMulti:!Numeric"]

Any R calculation whose object has a class of matrix:

types: ["RItem:matrix"]

Any Date control in the document:

types: ["Control:date"]

Any Date, List box, Combo box or Text box control in the document:

types: ["Control:date,listbox,combobox,textbox"]

Next

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

How to Set Conditional Controls in a Custom Analysis Tool