This article describes how to set headings and arrange input controls within groups and pages for custom analysis tools.
Requirements
- A custom analysis tool that you created via Calculation > Custom Code.
- You have read How to Create a Custom Analysis Tool.
Please note this requires the Data Stories module or a Displayr license.
Method
Similar to Rules, the input fields that appear in an R-based custom analysis tool via its R graphical interface form are RuleForm objects which are treated as properties of a form
variable. The same functions can therefore be used here with the addition of new functions. This uses JavaScript code and is placed under Data > Input JavaScript.
Headings
The standard Ruleform
functionality includes the setHeading
function for displaying a heading above the controls and the setSummary
function for displaying summary text below the controls. You can add these by simply specifying the text within the argument brackets:
form.setHeading("Example Custom Analysis Tool")
form.setSummary("This is where you can provide a summary of what this tool does")
Groups
When many controls are required on the Data tab of the object Inspector, it is preferable to organize these controls into groups or separate pages rather than presenting the user with a long list.
You can easily group controls on a page by using the group
command. The position of this command in your code is important as all subsequent control items will be grouped together until it encounters another group
command.
Here, we will include one control within the first group and 2 within the second group:
form.group("Group A");
form.dropBox({label: "Variable set drop-down", types:["VariableSet"]})
form.group("Group B");
form.dropBox({label: "Variable drop-down", types:["Variables"]})
form.numericUpDown({label: "Numeric Up down"})
Groups also have an optional argument whereby you can explicitly contract a group to hide its controls or expand a contracted group to reveal its controls. In this example, we could set Group A to explicitly expand by updating the code to the following:
form.group({label: "Group A", expanded: true })
Note that if no expanded argument is entered then Displayr will set this argument based on an internal heuristic.
Pages
A further method of organizing input controls is to create a new page or tab using the page
command. This page will be positioned to the right of the existing General tab with its own set of controls.
Here, we have created a new page called New Page with a text box control on it:
form.page("New Page");
form.textBox({label: "Text Box"})
Next
How to Create User Input Fields in a Custom Analysis Tool
Later
How to Set Conditional Controls in a Custom Analysis Tool
How to Set Object Types in DropBox Controls in Custom Analysis Tools
How to Reference Controls in a Custom Analysis Tool Using R