Introduction
Many features available in Displayr's menus are built with R code and have been connected to a graphical user interface (GUI) so that you can select various options via controls. This is often referred to as a Standard R widget. This article describes how to use these R-based analysis tools.
Requirements
An R-based analysis output that has been created via the menus.
Method
R-based analysis tools provide the user with controls on the Inputs tab of the object inspector. An example is shown below:
Controls are used as inputs or parameters to the underlying R code. These controls can be placed in collapsible groups or added as an additional page similar to Inputs and Properties.
Each control can be restricted to specific types of items (e.g. variables, tables or R calculations), specific types of data (e.g. text or numeric) and number of selections. They can also take the form of different control types, such as checkboxes, combo boxes, list boxes, color pickers, and data entry spreadsheets.
Note, the input controls are created via JavaScript code shown in the Properties > INPUTS JAVASCRIPT code box of the object inspector. The underlying R code is similarly found under Properties > R CODE. Both fields are editable.
Entering values in a control
Most of the controls act in the way that users have come to expect from modern user interfaces. Controls which are invalid in some way are outlined in red. The most common reason is that the control is a required field and it does not yet have a value.
Using text box controls
When entering or changing a value of a text box, you should click with the mouse somewhere else on the interface to signal that you have finished entering the text. Otherwise, the text box will wait patiently for you to continue your typing.
Making selections in a drop box
Drop box controls have special functionality. To select objects in this control type, click in the field. This will bring up a list of values in your project that can be used in the control. You will then be able to select one or more of these by ticking the relevant boxes. Clicking anywhere outside of the check-list will close it and the variables will have been added to the drop box.
- Some controls accept only a single input, while others may accept multiple inputs. Normally drop box controls which only take a single input have a height equal to a single row; multi-valued ones have greater heights (often 4 rows high).
- If you select a value in a single-valued drop box, then it will replace any value which is already there. If you select objects in a multi-valued drop box, then it will insert the new value into the list.
- Items may be reordered by dragging them within the control.
- Depending on underlying restrictions, some multi-valued drop boxes may disallow duplicate values. If you select the same value on the drop box, then only its position in the list will change. In other cases, a drop box may allow the same value to reappear in the list more than once.
- For multi-valued drop boxes, you can additionally select a range of variables by clicking a single item, holding down SHIFT and then selecting the final item.
Removing values from a drop box
When you hover the mouse over a multi-valued drop box, a cross will appear next to the value under your mouse. A Clear button is also available at the bottom of the control.
Pressing on the cross will remove the corresponding value, while pressing on the Clear button will remove all values in the control.
If a single-valued drop box is marked as a required field, there is no way of removing the value once it has been selected. Instead, you may replace it with a new value by selecting the new value in its place. However, if it is not required, then the value may be deleted in the same way as for multi-valued drop boxes.
Entering data into a data entry control
To enter data into a data entry control, you must first click the red Enter Data (or equivalent) button, enter the data into the spreadsheet layout by typing or pasting, and then press OK.
Execution
Whenever a value has been changed in one of these controls, the code which creates these controls is re-run. This is because sometimes the value of one control might necessitate more or fewer inputs. Once this has been re-run, each of the controls are checked to see whether any of the values entered into them are invalid. For example, one control may require only numbers, but perhaps some non-number information has been entered.
When you have invalid controls, messages are displayed next to them, and you are given the chance to fix up any issues. When there are no longer any invalid controls (for example, when all information has been entered), the corresponding R code is run, making use of the inputs you've entered. If you make any changes to any control, then the process is repeated, resulting in the R code being re-run.
See Also
How to Create a Custom Analysis Tool