Lets the user select a value from a list of predefined, mutually exclusive options.
Remarks
The query expression in the choices property returns a
number of records, each of which will serve as an available option in the control.
The keyMap property is a data-binding expression that
gets evaluated for each of the rows returned in choices, and must return a
unique key for each of the selectable options. You can set keyMap to any
value as long as it defines a unique key-option mapping, but practically, it will evaluate to
one or more of the data fields of the current row returned in the choices
query.
...
<numberbox id="nboxNoo" numberFormat='{decimalSeparator: "."}' label="The single-integer dropdown key (1-4)"/>
<radiogroup id="rgroupDoo"
label="Pick an ice cream flavor"
choices='{TABLE keyDoo, valueDoo
(1, "vanilla";
2, "chocolate";
3, "strawberry";
4, "rocky road")}'
keyMap='{SELECT keyDoo myalias}'
textMap='{valueDoo}'
selectedKey='{SELECT nboxNoo.number myalias}'
...
Figure 249. Numbers 1 through 4 identify the options in the rgroupDoo
radiogroup, and its selected option is data-bound to the user input in
nboxNoo
If the choices recordset does not have a column with
unique values, more than one column can be bound into the keyMap property. In
such cases, the result of the keyMap query will have a record type value.
Since the selectedKey property matches keyMap in every
respect, in these cases, selectedKey will also have a record type value with
data fields whose name, number, type, and order matches those of the keyMap
query result.
...
<textbox id="boxMoo"
label="Key part 1 of 2 (manxome or uffish)"
text=""/>
<textbox id="boxTroo"
label="Key part 2 of 2 (tove or mimsy)"
text=""/>
<radiogroup id="rgVroo"
label="The composite key determines the selected option:"
choices='{TABLE keyBar1, keyBar2, valueBaz
("manxome", "mimsy", "wabe";
"uffish", "tove", "frumious")}'
keyMap='{SELECT keyBar1, keyBar2}'
textMap='{valueBaz}'
selectedKey='{SELECT boxMoo.text keyBar1,
boxTroo.text keyBar2}'/>
Figure 250. The keyMap property of rgVroo specifies 2 keys to
identify the selectable options, which come from the boxMoo and
boxTroo
textboxes
Note that if keyMap has a
record-type value, the name, type, and order of its fields must match those
in the selectedKey that references it.
The textMap property is also evaluated for each of the
returned rows in turn, and maps each returned record to a string displayed in the control as
its corresponding text. Because keyMap and textMap are
evaluated in turn for each of the records that the choices query returns, you
can reference columns in the choices query inside these properties: this way,
you can set up one or more of the data fields of the current returned record as the key, and
another data field as the displayed text.
Using the selectedKey, selectedText
and selectedValue properties, you can reference the option that the user
selected (or the option set as selected by a data binding expression).
You can set a selected option in the control by binding a value into
the selectedKey property.
Unlike the dropdown control, which works practically the same as a
radiogroup, there is no <None> option rendered
over the list of rows returned in choices. This also means that if the user
makes a selection in a radiogroup control, there is no going back to a 'No
options selected' state in the user interface.
selectedText is the string value that the user
selected as an option: the result of evaluating the textMap expression for
the row that the user selected from the list of rows returned in choices. It
is a read-only property: use it outside the drop-down control to bind your user's selection
into other controls.
<radiogroup id="rgroupDoo"
label="Pick an ice cream flavor"
choices='{TABLE keyDoo, valueDoo
(1, "vanilla";
2, "chocolate";
3, "strawberry";
4, "rocky road")}'
keyMap='{keyDoo}'
textMap='{valueDoo}'
<textview label="Here's what you picked.
Are you sure it's chocolate?"
text='{rgroupDoo.selectedText}'/>
selectedValue is the record that the user selected
from the recordset returned in choices. You can target its data fields using
the
dropdown-id.selectedValue.column-name-of-recordset-in-choices
syntax.
Sample
<radiogroup id="key1"
label="Who was Calvin's ideological rival?"
choices='{TABLE keyZ, valueZ
(1, "The Pope";
2, "Hobbes")}'
keyMap='{keyZ}'
textMap='{valueZ}'/>
<radiogroup id="key2"
label="Beer or wine?"
choices='{TABLE keyX, valueY
(1, "beer";
2, "wine")}'
keyMap='{keyX}'
textMap='{valueY}'/>
<radiogroup id="answer"
label="Which side of the potato chip is saltier?"
choices='{TABLE superKey1, superKey2, superValue
("The Pope","beer","the top side";
"Hobbes","wine","the bottom side")}'
keyMap='{SELECT superKey1, superKey2}'
textMap='{superValue}'
selectedKey='{SELECT key1.selectedText superKey1,
key2.selectedText superKey2}'/>
The
selectedText properties of the top dropdowns serve as
composite key for the bottom dropdown.
A workflow script running in the Mobilengine Cloud would access the submission of the webform above in the format below:
{...
answer:
{
selectedKey: {superKey1: "Hobbes", superKey2: "wine"},
selectedText: "the bottom side",
selectedValue:
{
superKey1: "Hobbes",
superKey2: "wine",
superValue: "the bottom side"
}
}
...}See the workflow script reference guide for more details on data type mapping.