Skip to content

Check List

The CheckList widget in Emakin allows multiple selections from a list of checkboxes. List options can be sourced from various data sources, including static lists or query results.

XML Fields

Stored Values

  • XPath selects the collection or value that receives the selection. ItemXPath selects individual stored items.
  • ValueXPath selects the source field written for each selected item; CaptionXPath selects the display text stored with it. In Single Mode, the selected values are represented in one data element as described below.

Choice Source and Presentation

  • DataSources supplies the selectable items. MonitoredXPaths lists values that reload those items when changed.
  • Layout selects Vertical or Horizontal checkbox arrangement. RequiredForGroup requires a selection when the matching validation group is evaluated. Hints gives user help and Rules controls conditional behavior.

Single Mode

CheckList supports two different storage models. The default model stores each selection as a separate XML item. Single Mode stores all selected values in the text value of the node selected by XPath.

Enable Single Mode by setting ItemXPath to !. Here, ! is a mode marker, not an XPath expression. Consequently, ValueXPath, CaptionXPath, data-source mappings, and the State attribute are not used to write the data model.

Default mode Single Mode
XPath target A container for the selected-item sequence One scalar XML element or attribute
ItemXPath XPath for each item in the sequence, for example Item or * !
Stored value One XML item per checked option A comma-separated string such as 1,3
Caption and mappings May be stored on each XML item Not stored or executed by CheckList
Selection lifecycle New, existing, and unchecked items can carry State The complete string is replaced; no per-item state exists
Suitable when Each selection needs metadata, mappings, or change tracking Only the selected identifiers need to be saved compactly

Data Model Comparison

For the examples below, assume that the user checks Item 1 (1) and Item 3 (3). Data is only the enclosing form data root; the actual root element can have a different name.

Default mode: sequence of selected items

The regular example uses XPath="List" and ItemXPath="*". In a schema, * resolves to the allowed child element of the List sequence. If that child element is named Item, the resulting data is structurally equivalent to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<Data>
    <List>
        <Item State="Temp">
            <Value>1</Value>
            <Caption>Item 1</Caption>
        </Item>
        <Item State="Temp">
            <Value>3</Value>
            <Caption>Item 3</Caption>
        </Item>
    </List>
</Data>

ValueXPath and CaptionXPath are evaluated relative to every selected Item. They may point to child elements, as above, or to attributes. For example, ValueXPath="@Value" and CaptionXPath="@Caption" would produce <Item Value="1" Caption="Item 1" State="Temp" />.

On a later edit, an item that is unchecked is retained in the data model with State="Deleted"; a previously stored item that remains checked has no State attribute. This preserves the per-item lifecycle until $Xml.CommitDeletes() clears it. The widget also executes data-source mappings for newly created items, so this mode can persist additional fields beyond value and caption.

Single Mode: one scalar value

The Single Mode example uses XPath="SingleMode" and ItemXPath="!". With the same two checked options, it creates or updates only this one value:

1
2
3
<Data>
    <SingleMode>1,3</SingleMode>
</Data>

There are no child Item nodes, captions, mappings, or State attributes. When the selection changes, CheckList rewrites the complete text value; for example, changing the selection to Item 2 produces <SingleMode>2</SingleMode>. An empty selection produces an empty value.

Single Mode Value Rules

  • Values must be unique, non-empty identifiers. A duplicate value would address the same checkbox row.
  • Do not use commas in data-source values: commas are the storage delimiter. On load, surrounding whitespace is ignored.
  • Single Mode is appropriate when labels can always be obtained from the current data source. Use the default mode if historical captions, additional mapped fields, or an item-level deletion audit are required.

Remarks

Default Behavior

  • The CheckList widget uses a sequence-type data model to store selected items.
  • Checked Items: Each selected item creates a new element in the data model with the corresponding 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 CheckList 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.

Example

An example checklist widget that uses data sources can be defined as follows:

 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
26
27
<CheckList RequiredForGroup="" Layout="Vertical" XPath="List">
    <ItemXPath><![CDATA[*]]></ItemXPath>
    <ValueXPath><![CDATA[Value]]></ValueXPath>
    <CaptionXPath><![CDATA[Caption]]></CaptionXPath>
    <DataSources>
        <ListItemDataSource TextFormat="{{Text}}" ValueFormat="{{Value}}" Enabled="True">
            <Mappings/>
            <Items>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 1]]></Text>
                    <Value Type="System.String"><![CDATA[1]]></Value>
                </Item>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 2]]></Text>
                    <Value Type="System.String"><![CDATA[2]]></Value>
                </Item>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 3]]></Text>
                    <Value Type="System.String"><![CDATA[3]]></Value>
                </Item>
            </Items>
        </ListItemDataSource>
    </DataSources>
    <MonitoredXPaths />
    <Hints><![CDATA[]]></Hints>
    <Rules />
</CheckList>

Single Mode Example

 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
26
27
<CheckList RequiredForGroup="" Layout="Horizontal" XPath="SingleMode">
    <Rules/>
    <ItemXPath><![CDATA[!]]></ItemXPath>
    <ValueXPath><![CDATA[]]></ValueXPath>
    <CaptionXPath><![CDATA[]]></CaptionXPath>
    <DataSources>
        <ListItemDataSource TextFormat="{{Text}}" ValueFormat="{{Value}}" Enabled="True">
            <Mappings/>
            <Items>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 1]]></Text>
                    <Value Type="System.String"><![CDATA[1]]></Value>
                </Item>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 2]]></Text>
                    <Value Type="System.String"><![CDATA[2]]></Value>
                </Item>
                <Item>
                    <Text Type="System.String"><![CDATA[Item 3]]></Text>
                    <Value Type="System.String"><![CDATA[3]]></Value>
                </Item>
            </Items>
        </ListItemDataSource>
    </DataSources>
    <MonitoredXPaths />
    <Hints><![CDATA[]]></Hints>
</CheckList>