Choice Action

Declaration

<AMSELECTITEM MESSAGETEXT="test" WINDOWTITLE="text" LISTTYPE="option" RESULTVARIABLE="text" ITEMS="text" VALUES="text" SELECTED="1" VALUEONCANCEL="text" FORCESELECT="yes/no" MULTIPLE="yes/no">

See Also

Choice-Setting Properties, Message Box, Input Box, Create Variable

Description

Displays an auto-generated multiple choice dialog box based the options you specify. Choice is useful when a multiple-choice selection is needed or the user must make a decision that will affect the action taken by a task. The value associated with the item that the user selects is placed into a variable where it can be evaluated and acted on.

Practical Usage

Similar to the Input Box <AMINPUTBOX> action except allows the user to enter a text value in response to a question. The text value is populated into a variable which can be used later in the task.

Parameters

General Tab

Message to display

Text, Required
MARKUP: MESSAGETEXT="The contents of the variable is %VARNAME%"

Specifies the text to be displayed in the choice dialog box. Usually this is the question that the user should select the answer to.

 

List Type

Text [options], Required
MARKUP: LISTTYPE="combobox"

Specifies the manner by which the list will be displayed on the auto-generated form at runtime. This selection is relevant not only for aesthetics but will also affect the ability of the user to make a multiple choice selection (see below).

The available options are:

 

Populate variable with result

text, Required
MARKUP: RESULTVARIABLE="varname"

Specifies the name of an already created variable that should be populated with the value parameter of the item selected. If the user has selected multiple items the values are returned as a comma-delimited list.

 

Use items from

list, Required
MARKUP: ITEMS="item1, item2"

Specifies where the list items should derive from. Different parameters appear depending on which option is selected.  

The available options are:

 

Values

list, Required
MARKUP: VALUES="value1, value2"

Specifies a comma-delimited list of values in the list. The values represent value(s) will be returned by the item if selected at runtime by the user. There must be an equivalent number of values to items. Each value must have a corresponding item in the ITEMS= parameter. This parameter is valid only when List is selected from the Use items from parameter.

 

Selected

list, Required
MARKUP: SELECTED="2"

Specifies the index (base 1) numbers of the items that should be checked or selected by default. Depending on the list type, the requirements for this parameter differ. In the case of a dropdown and options, one item must be selected. In the case of a listbox or checkboxes, none or multiple items may be specified. To specify multiple options the numbers should be comma-delimited. This parameter is valid only when List is selected from the Use items from parameter.

 

Dataset

text, Required
MARKUP: DATASET="theDataset"

Specifies the dataset that the list items should be gathered from.

 

Use column as caption

text, Required
MARKUP: COLUMN="theDataset.A"

Specifies the dataset column that should be used as a caption.

 

Advanced Tab

Title

text, Optional
MARKUP: WINDOWTITLE="The choice dialog"

Specifies the Window title of the choice dialog.

 

On Cancel

text, Optional - Default (blank)
MARKUP: VALUEONCANCEL="cancelled"

Specifies the value that should be returned into the variable if the user presses the "Cancel" button.

The available options are:

 

Force selection

yes/no, Optional - Default YES
MARKUP: FORCESELECT="NO"

Specifies that the user must make a valid selection before continuing. This option is only valid if the List Type parameter is set to Checkbox or List. Other list types automatically force selection.

 

Allow multiple selection

text, Optional - Default NO
MARKUP: MULTIPLE="yes"

Specifies that multiple selections are allowed. This option is only valid if the List Type parameter is set to Checkbox or List as only those controls support multiple-selection.

 

Notes

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

This task shows how to use the Choice action and make decisions based on the answer.

<AMVARIABLE NAME="foodchoice"></AMVARIABLE>

<AMSELECTITEM MESSAGETEXT="&quot;What would you like to eat?&quot;" WINDOWTITLE="&quot;What's for dinner?&quot;" LISTTYPE="option" RESULTVARIABLE="foodchoice" ITEMS="Hamburger,Pasta,Chicken" VALUES="1,2,3" SELECTED="1" />

<AMIF EXPRESSION="%foodchoice% = 1">

     <AMMESSAGEBOX>You chose Hamburger</AMMESSAGEBOX>

</AMIF>

<AMIF EXPRESSION="%foodchoice% = 2">

     <AMMESSAGEBOX>You chose pasta</AMMESSAGEBOX>

</AMIF>

<AMIF EXPRESSION="%foodchoice% = 3">

     <AMMESSAGEBOX>You chose chicken</AMMESSAGEBOX>

</AMIF>