Tag List¶

The TagList widget allows users to select multiple options (tags) from a predefined list. This list can be populated statically or dynamically using data sources (see Data Sources for details). The user can remove tags from the list by clicking on the close icon on the tag.

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.

Data Model¶

The TagList widget uses a sequence-type data model to store selected items. Each selected item results in a new element within the data model, containing the selected item's value.

Data Mapping¶

• Value Assignment:

  • Defined by the data source item's Value property using the ValueXPath property.
  • Default: Empty string, assigning the data source item value to the new element.

• Label Assignment:

  • Defined by the data source item's Text property using the CaptionXPath property.
  • Default: Empty string, assigning the data source item's Text property to the new element's Caption attribute.

State Attribute¶

The TagList widget supports monitoring list item changes using the State attribute:

• Temp: Marks newly checked items.
• Existing Items: Preserved as is.
• Deleted: Marks items that were unchecked.

Clearing the State Attribute:
Use the scripting method $Xml.CommitDeletes() to reset the State attribute.

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.

Example¶

Considering the following data model:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

<xs:element name="TagList">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="Item" minOccurs="0">
                <xs:complexType>
                    <xs:sequence>
                        <xs:element name="Value" type="xs:string"/>
                        <xs:element name="Text" type="xs:string"/>
                    </xs:sequence>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:element>

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

<TagList AllowNew="True" CacheDataSources="True" XPath="TagList">
    <ItemXPath><![CDATA[*]]></ItemXPath>
    <ValueXPath><![CDATA[Value]]></ValueXPath>
    <CaptionXPath><![CDATA[Text]]></CaptionXPath>
    <DataSources>
        <ListItemDataSource TextFormat="{{Text}}" ValueFormat="{{Value}}" Enabled="True">
            <Items>
                <Item>
                    <Text><![CDATA[A]]></Text>
                    <Value><![CDATA[A]]></Value>
                </Item>
                <Item>
                    <Text><![CDATA[B]]></Text>
                    <Value><![CDATA[B]]></Value>
                </Item>
                <Item>
                    <Text><![CDATA[C]]></Text>
                    <Value><![CDATA[C]]></Value>
                </Item>
            </Items>
        </ListItemDataSource>
    </DataSources>
</TagList>