Skip to content

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.

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
<DropDown AutoSelectValue="false" AllowNew="false" MapSelection="false" CacheDataSources="true" XPath="ManualEntry">
    <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/>
</DropDown>

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
<DropDown AutoSelectValue="false" AllowNew="false" MapSelection="true" CacheDataSources="true" XPath="ManualEntry">
    <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/>
</DropDown>