List Values (Data Field/Data Column Property)

⚠	ARTICLE UNDER CONSTRUCTION

This article is about the current version of Grooper. Note that some content may still need to be updated.

2025

"List Values" is a set of configurable properties for {DataFieldIcon}} Data Field and {DataColumnIcon}} Data Columns. When enabled and configured, List Values alters how users interact with Data Field input boxes and Data Column cell input boxes in a Data Viewer. It allows Grooper designers to set a list of values users can pick from a dropdown selection. Instead of a "free type" input, it users can pick from the list when reviewing the field.

Example List Values selection list

The items in the selection list can be generated in one of three ways (or a combination of the three):

• A local list
• A referenced Lexicon
• A list generated by a lookup (such as a Database Lookup or an XML Lookup)

The selection list can be "permissive" or "restrictive".

• Permissive lists are the default behavior.
  • Permissive lists lets users type in values that are not present in the selection list.
  • Permissive lists will accept values collected by the Data Field's Value Extractor that are not present in the selection list.
• Restrictive lists are enabled by enabling the "Restrict to List" property.
  • Restrictive lists prevent users from typing anything in the input box. They can only select an item from the selection list.
  • Restrictive lists will ignore values returned by the Data Field's Value Extractor if it is not present in the selection list.

Advanced functionality

Include Lookup Results: Using a lookup to populate the list

Example "County" list when "State" is "Delaware".

Example "County" list when "State" is "Hawaii".

When the "Include Lookup Results" option is enabled, the field will use the results of a lookup (such as XML Lookup) to generate the selection list.

• This is helpful for use cases where the possible entry values for Field B change based on Field A's value.
• Example: A "State" lookup field could be used to generate list values for a "County" field using this mechanism.

⚠

BE AWARE: Set the Lookup Specification's "Conflict Disposition" to "Ignore" The "Conflict Disposition" determines what happens when the Lookup Specification returns multiple hits (multiple rows for Database Lookup, multiple records for XML Lookup or Web Service Lookup, or multiple lines for Lexicon Lookup). You must set the Lookup Specification's "Conflict Disposition" to "Ignore" in order to use a lookup to generate a selection list for a Data Field/Data Column. In normal lookups (for field population/validation), Grooper is designed to alert you if the lookup produces multiple hits. However, in this case, we want to ignore that warning to include all results in the selection list.

Example "Include Lookup Results" setup using an XML Lookup

To use XML Lookup to generate a field's list values:

1. Drag the XML file to the Project (or a folder in the Project).
2. Select the Data Element you want to add XML Lookup to.

   • Commonly lookups are added the Data Model. However, lookups may be added to Data Sections and Data Tables as well.
     • If added to the Data Model, XML Lookup will execute once for the document instance.
     • If added to a Data Section, XML Lookup will execute for each section instance.
     • If added to a Data Table, XML Lookup will execute for each row instance.

3. Open the "Lookups" editor (Press the "..." button).
4. Press the "Add" button and select "XML Lookup".
5. Using the "Source" button, select the XML file you added to the Project in Step 1.
6. Open the "Record Selector" editor (Press the "..." button).
7. Enter an XPath expression to select an XML node from the source XML file.
   • The Record Selector is crucial to XML Lookup. The lookup will fail if no record is selected.
   • Use field variables (%FieldName) to insert "lookup fields".
   • The lookup field(s) value will be inserted into the XPath when XML Lookup runs.
   • Example: //state[@name='%State']/counties/county
8. Open the "Value Selectors" editor (Press the "..." button).
9. Press the "Add" button to add a new Value Selector.
10. In the "Path" editor, enter an XML selector that selects an attribute or child XML element whose value you want to collect. When XML Lookup runs, the Value Selector's "target field" will be populated with the selected attribute or element's text.
    • Example: @name
11. Open the "Target Field" dropdown and select the corresponding Data Field in the Data Model. When XML Lookup runs, the Data Field you select will be populated with the attribute or element's text selected by the Value Selector's Path.
    • Example: "County" Data Field

    • Most typically, one XML Lookup will be used to generate one Data Field's list. This means you'll only need a single Value Selector. However, you could add multiple Value Selectors if multiple fields selection lists change depended on the lookup field's (or fields') value(s).

12. Press "OK" when finished to exit the Value Selectors editor.
13. Set the "Conflict Disposition" to "Ignore".
    • The selection list will not be generated if not set to "Ignore". Multiple lookup hits are what we want in this case. Telling Grooper to "ignore" the conflict will allow all lookup hits to be used to populate the list values.
14. When finished configuring the XML Lookup, press "OK" to exit the Lookups editor.
15. Save changes to the Data Element.
16. Navigate to the target Data Field/Data Column selected in step 11.
17. At the bottom of the property grid, expand the "List Values" settings.
18. Enable "Include Lookup Results" by changing it to "True".

Other features

Restrict to List

While technically not a "List Values" setting, the "Restrict to List" property is only used in conjunction with List Values. Enabling "Restrict to List" will only allow values from the selection list to be selected (whether a local list, referenced Lexicon or list populated by a lookup).