Dropdown¶

The Dropdown widget allows users to select a single option from a predefined list. This list can be populated statically or dynamically using data sources (see Data Sources for details). The widget includes a built-in search mechanism to facilitate selection from large lists. Selection is automatically mapped to the data model using the Selection Mapping feature.

Manual Entry¶

If the AllowNew property is set to true, users can enter values not present in the predefined list. Otherwise, only existing options can be selected.

XML Fields¶

Binding and Selection¶

• XPath selects the form-data context. ValueXPath selects the field from the chosen item that is written to the form data. CaptionXPath optionally stores the text shown to the user alongside that value.
• MappingXPath selects additional item fields to copy when MapSelection is True. Use it when choosing one item must also populate related form fields.

Choice Source¶

• DataSources defines the available options. A static ListItemDataSource uses TextFormat for visible text and ValueFormat for the stored value; other sources may obtain the same shape from a query or service.
• MonitoredXPaths lists data paths that refresh the choices after they change. Use it for dependent dropdowns. CacheDataSources controls whether the current source result is reused between refreshes.

Input Behavior¶

• AutoSelectValue selects the first valid option when the current value is empty. AllowNew permits a value that is not returned by the source. MapSelection enables MappingXPath processing.
• Size controls width. RequiredForGroup applies required validation when a button validates the same group. Hints supplies help text and Rules contains formatting or validation rules.

Automatic Value Selection¶

By default, the first available item is selected when the widget loads if the corresponding data model element is empty. This behavior can be disabled by setting the AutoSelectValue property to false. With AutoSelectValue set to false, no item is pre-selected; user selection is required if a value is mandatory.

Selection Mapping¶

The selected item's value is mapped to the ValueXPath element, and its display text is mapped to the CaptionXPath element by default.

To map additional item properties to other data model elements, set the MapSelection property to true. The mapping root path defaults to the widget's XPath but can be customized using the MappingXPath property.

See the Selection Mapping Example for an illustration.

Data Source Caching¶

For improved performance, the widget caches data sources by default. This caching can be disabled by setting the CacheDataSources property to false. Disabling caching causes data sources to be reloaded each time the widget is rendered.

Simple Example¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<DropDown XPath="ManualEntry" RequiredForGroup="" CacheDataSources="True" Size="Medium" AutoSelectValue="False" AllowNew="False" MapSelection="False">
    <ValueXPath><![CDATA[Id]]></ValueXPath>
    <CaptionXPath><![CDATA[Name]]></CaptionXPath>
    <MappingXPath><![CDATA[]]></MappingXPath>
    <DataSources>
        <ListItemDataSource TextFormat="{{Text}}" ValueFormat="{{Value}}" Enabled="true">
            <Mappings/>
            <Items>
                <Item>
                    <Text><![CDATA[Option 1]]></Text>
                    <Value><![CDATA[Option1]]></Value>
                </Item>
                <Item>
                    <Text><![CDATA[Option 2]]></Text>
                    <Value><![CDATA[Option2]]></Value>
                </Item>
            </Items>
        </ListItemDataSource>
    </DataSources>
    <MonitoredXPaths/>
    <Hints><![CDATA[]]></Hints>
    <Rules />
</DropDown>

Related Pages¶

• Forms
• Form Widgets
• Data Sources

Selection Mapping Example¶

Consider the following data model:

1
2
3
4
5

<ManualEntry>
    <Id></Id>
    <Name></Name>
    <MappedField></MappedField>
</ManualEntry>

The following example demonstrates how the selected item's MappedField value is automatically copied to the MappedField element in the data model upon selection:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<DropDown XPath="ManualEntry" RequiredForGroup="" CacheDataSources="True" Size="Medium" AutoSelectValue="False" AllowNew="False" MapSelection="True">
    <ValueXPath><![CDATA[Id]]></ValueXPath>
    <CaptionXPath><![CDATA[Name]]></CaptionXPath>
    <MappingXPath><![CDATA[]]></MappingXPath>
    <DataSources>
        <ListItemDataSource TextFormat="{{Text}}" ValueFormat="{{Value}}" Enabled="true">
            <Mappings/>
            <Items>
                <Item>
                    <Text><![CDATA[Option 1]]></Text>
                    <Value><![CDATA[Option1]]></Value>
                    <MappedField>X</MappedField>
                </Item>
                <Item>
                    <Text><![CDATA[Option 2]]></Text>
                    <Value><![CDATA[Option2]]></Value>
                    <MappedField>Y</MappedField>
                </Item>
            </Items>
        </ListItemDataSource>
    </DataSources>
    <MonitoredXPaths/>
    <Hints><![CDATA[]]></Hints>
    <Rules />
</DropDown>