How to Create User Input Prompts in QScripts

This article describes how to create prompts in a QScript for the user to enter values, confirm options, and make selections.

Requirements

• A Displayr Enterprise user license, which includes the ability to add custom analysis menu items.
• The importdata.zip file which includes the Phone data set that we will use for this article.
• You have read How to Create a Custom QScript and How to Work with Variables via QScript.
• You are using the QScript Editor method from How to Use QScripts in Displayr. User prompts cannot be run in QScripts when using the Displayr API. This must be used via the QScript menu from the Report tree > Calculation > QScript.

Method

By default, basic prompts can be used without referencing any additional QScript libraries. Here are some examples.

General

1. Text or value

prompt("Enter a value");

2. Boolean (true/false)

askYesNo("Do you wish to continue?")

3. Confirmation

confirm("The script will now run")

Selection Functions

1. Select one

var choices = ['Option 1','Option 2'];
var selection = selectOne("Choose one:", choices);

• choices stores all the items you want to display in your list box.
• selectOne returns the index of the chosen item (i.e. 0 = Option 1 and 1 = Option 2).

2. Select many

var choices = ['Option 1','Option 2'];
var selections = selectMany("Choose any:", choices);

• choices stores all the items you want to display in your list box.
• selectMany returns the index of the chosen items as an array (i.e. [0] = Option 1, [1] = Option 2, and [0,1] = both Option 1 and Option 2).

Displayr has its own JavaScript library of selection functions called QScript Selection Functions for calling variables and variable sets. The following are some of the main functions from this library, and all require the line below at the top of your code:

includeWeb('QScript Selection Functions')

In each example, you must first declare the variable (set) to use in the prompt. 

3. Select single variable set (or question) by combined label

var questions = project.dataFiles[0].questions;
var selection = selectOneQuestion("Please select a variable set",questions);

• questions stores all variable sets in the data set.
• selectOneQuestion returns a question object.

4. Select multiple variable sets (or questions) by combined label

var questions = project.dataFiles[0].questions;
var selection = selectManyQuestions("Please select multiple variable sets",questions).questions;

• questions stores all variable sets in the data set.
• selectManyQuestions returns a question object when .questions is appended.

5. Select single variable by individual label

var variables = project.dataFiles[0].variables;
var selection = selectOneVariableByLabel("Please select one variable",variables);

• variables stores all variables in the data set.
• selectOneVariableByLabel returns a variable object by default, but will return the selected label if .label is appended.

6. Select multiple variables by individual labels

var variables = project.dataFiles[0].variables;
var selection = selectManyVariablesByLabel("Please select multiple variables",variables);

• variables stores all variables in the data set.
• selectOneVariableByLabel returns a variable object by default, but will return the selected labels if .labels is appended.

Next

How to Create Diagnostic Messages and Perform Validations via QScript

Later

How to Modify Variables and Value Attributes via QScript

How to Create Custom Variables via QScript

How to Add Pages, Folders, and Headings via QScript

How to Create Tables and Calculations via QScript

How to Create a Visualization via QScript

How to Modify Tables via QScript

See Also

How to Work with Variables via QScript

How to Create a Custom QScript

How to Use QScripts in Displayr

JavaScript Fundamentals