List Values (Data Field/Data Column Property) - Revision history

Dgreenwood at 18:56, 24 June 2025

2025-06-24T18:56:44Z

← Older revision		Revision as of 13:56, 24 June 2025
Line 1:		Line 1:
	{{AutoVersion}}		{{AutoVersion}}

			{\|class="download-box"
			\|
			[[File:Asset 22@4x.png]]
			\|
			You may download the ZIP(s) below and upload it into your own Grooper environment (version 2025). The first contains one or more '''Batches''' of sample documents. The second contains one or more '''Projects''' with resources used in examples throughout this article.
			* [[Media:2025 Wiki - List Values Batches.zip]]
			* [[Media:2025 Wiki - List Values Projects.zip]]
			\|}

			== About ==

	"List Values" is a set of configurable properties for {DataFieldIcon}} [[Data Field]] and {DataColumnIcon}} [[Data Column]]s. 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.		"List Values" is a set of configurable properties for {DataFieldIcon}} [[Data Field]] and {DataColumnIcon}} [[Data Column]]s. 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.

Dgreenwood at 16:54, 24 June 2025

2025-06-24T16:54:45Z

← Older revision		Revision as of 11:54, 24 June 2025
Line 1:		Line 1:
	~~{\|class="attn-box"~~
	\|
	~~⚠~~
	\|
	~~ARTICLE UNDER CONSTRUCTION~~
	\|}

	{{AutoVersion}}		{{AutoVersion}}

Dgreenwood: /* Value Interpretation */

2025-06-24T16:53:35Z

Value Interpretation

← Older revision		Revision as of 11:53, 24 June 2025
Line 141:		Line 141:

	=== Value Interpretation ===		=== Value Interpretation ===

			The "Value Interpretation" property determines how lookup style Lexicons behave in the Data Viewer.
			* Lookup Lexicons list entries as key-value pairs separated by an equals sign (i.e. <code>key=value</code>)
			* The Value Interpretation mode will determine how the Data Viewer interface renders the list.
			** '''None''' - Users will be shown the "key" entries in the selection list.
			** '''DisplayValue''' - Users will be shown the "value" entries in the selection list.
			***<li class="attn-bullet"> Be aware this will affect the Data Field's value too. The Data Field will record the "value" component of the key-value entry.
			** '''Remarks''' - Users are shown the "key" entries in the selection list, and a "Search List Value" button will appear next to the Data Field.
			*** The "Search List Value" button will open a window to search for items in the selection list.
			*** Furthermore, the "value" component of the key-value entries show up as description remarks. This is helpful to give your users more information about the values they are selecting from the list.


			<big>Example</big>

			In this example, the following is added to the "Local Entries":
			<pre>
			S=Single
			M=Married
			D=Divorced
			W=Widowed
			</pre>

			Depending on the "Value Interpretation" mode, the user's experience will differ.

			'''Value Interpretation: None'''

			[[File:2025Wiki-ListValues-03-02-None-01.png\|left\|class=simpleborder simpleshadow]]

			The "key" component of the key-value list entries is selectable.
			<br clear=all>

			'''Value Interpretation: DisplayValue'''

			[[File:2025Wiki-ListValues-03-02-DisplayValues-01.png\|left\|class=simpleborder simpleshadow]]

			The "value" component of the key-value list entries is selectable.
			<br clear=all>

			'''Value Interpretation: Remarks'''

			[[File:2025Wiki-ListValues-03-02-Remarks01.png\|left\|class=simpleborder simpleshadow]]

			A "Search List Values" button appears.
			<br clear=all>
			[[File:2025Wiki-ListValues-03-02-Remarks-02.png\|left\|class=simpleborder simpleshadow]]

			Pressing this button brings up a search interface.

			Notice the "value" component of the key-value list entries are in the "Remarks" column. This acts as a description for the value the user selects (which is the "key" component of the key-value entry in the list).

			<br clear=all>

	== Other features ==		== Other features ==

Dgreenwood: /* Restrict to List */

2025-06-24T14:23:58Z

Restrict to List

← Older revision		Revision as of 09:23, 24 June 2025
Line 147:		Line 147:

	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).		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).
			* This can help prevent data entry errors.
			* If a user only has a limited set of values they can choose from, they cannot enter an invalid value not present in the List Values.
			*<li class="attn-bullet"> The Restrict to List feature is ''not'' appropriate for selection fields that have an "Other" option. This will prevent users from free typing a value.


			To enable the "Restrict to List" property:
			# Select the Data Field or Data Column in the node tree.
			# Configure "List Values" if not already done.
			#*<li class="attn-bullet"> The "Restrict to List" property will not appear until List Values has been configured and is either populating a list from Local Entries, Included Lexicons or Include Lookup Results.
			# Enable "Restrict to List" by turning it to "True".

Dgreenwood: /* Include Lookup Results: Using a lookup to populate the list */

2025-06-24T14:14:24Z

Include Lookup Results: Using a lookup to populate the list

← Older revision		Revision as of 09:14, 24 June 2025
Line 122:		Line 122:
	#* Use field variables (<code>%FieldName</code>) to insert "lookup fields".		#* Use field variables (<code>%FieldName</code>) to insert "lookup fields".
	#* The lookup field(s) value will be inserted into the XPath when XML Lookup runs.		#* The lookup field(s) value will be inserted into the XPath when XML Lookup runs.
	#* Example: <code><nowiki>//state[@name='%State']/counties/county</nowiki></code> would select <county> nodes in a hierarchy of //state/counties/~~county~~ nodes where the state ~~nodes "~~name" attribute is the Grooper extracted value for a "State" Data Field.		#* Example: <code><nowiki>//state[@name='%State']/counties/county</nowiki></code> would select <code><county></code> XML nodes in a hierarchy of <code><state><counties><county></code> nodes where the <code><state></code> node's <code>name</code> attribute is the Grooper extracted value for a "State" Data Field.
	# Open the "Value Selectors" editor (Press the "..." button).		# Open the "Value Selectors" editor (Press the "..." button).
	# Press the "Add" button to add a new Value Selector.		# Press the "Add" button to add a new Value Selector.

Dgreenwood: /* Include Lookup Results: Using a lookup to populate the list */

2025-06-24T14:10:01Z

Include Lookup Results: Using a lookup to populate the list

← Older revision		Revision as of 09:10, 24 June 2025
Line 122:		Line 122:
	#* Use field variables (<code>%FieldName</code>) to insert "lookup fields".		#* Use field variables (<code>%FieldName</code>) to insert "lookup fields".
	#* The lookup field(s) value will be inserted into the XPath when XML Lookup runs.		#* The lookup field(s) value will be inserted into the XPath when XML Lookup runs.
	#* Example: <code><nowiki>//state[@name='%State']/counties/county</nowiki></code>		#* Example: <code><nowiki>//state[@name='%State']/counties/county</nowiki></code> would select <county> nodes in a hierarchy of //state/counties/county nodes where the state nodes "name" attribute is the Grooper extracted value for a "State" Data Field.
	# Open the "Value Selectors" editor (Press the "..." button).		# Open the "Value Selectors" editor (Press the "..." button).
	# Press the "Add" button to add a new Value Selector.		# Press the "Add" button to add a new Value Selector.
	# 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.		# 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: <code><nowiki>@name</nowiki></code>		#* Example: <code><nowiki>@name</nowiki></code> would select an XML attribute named "name".
			#*<li class="attn-bullet"> In cases where the Record Selector selects XML elements whose inner text you want to use for List Values, enter the dot expression (<code>.</code>) to select the element's text.
	# 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.		# 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		#* Example: "County" Data Field

Dgreenwood at 13:58, 24 June 2025

2025-06-24T13:58:24Z

@@ Line 25: / Line 25: @@
 ** 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.
 == Basic functionality ==
@@ Line 57: / Line 69: @@
 * Example: A Lexicon that contains entries for US states could be used for a "State" Data Field.
 *:*<li class="fyi-bullet"> Furthermore, because it is its own node in the node tree, the Lexicon could also be referenced by a Data Type extractor that needs to match state names on a document.
 == Advanced functionality ==

Dgreenwood: /* Referenced Lexicons */

2025-06-24T13:47:02Z

Referenced Lexicons

← Older revision		Revision as of 08:47, 24 June 2025
Line 51:		Line 51:

	=== Referenced Lexicons ===		=== Referenced Lexicons ===

			If you have a larger list of selection values, or a list that is used by other nodes in Project, you should consider referencing a {{LexiconIcon}} [[Lexicon]] when configuring List Values.
			* Lexicons are a type of node that can be added to the Grooper node tree. They store list entries and can be referenced throughout Grooper for a variety of purposes.
			* Lexicons are referenced by List Values using the "Included Lexicons" editor.
			* Example: A Lexicon that contains entries for US states could be used for a "State" Data Field.
			:<li class="fyi-bullet"> Furthermore, because it is its own node in the node tree, the Lexicon could also be referenced by a Data Type extractor that needs to match state names on a document.

	== Advanced functionality ==		== Advanced functionality ==

Dgreenwood: /* Local lists */

2025-06-24T13:40:52Z

Local lists

@@ Line 28: / Line 28: @@
 == Basic functionality ==
-=== Local lists ===
+=== Local Entries lists ===
 === Referenced Lexicons ===

Dgreenwood: /* Include Lookup Results: Using a lookup to populate the list */

2025-06-23T20:22:19Z

Include Lookup Results: Using a lookup to populate the list

← Older revision		Revision as of 15:22, 23 June 2025
Line 35:		Line 35:

	=== Include Lookup Results: Using a lookup to populate the list ===		=== Include Lookup Results: Using a lookup to populate the list ===

			[[File:2025Wiki-XMLLookup-03-03-ListValues-01.png\|Example "County" list when "State" is "Delaware".\|frame]]

			[[File:2025Wiki-XMLLookup-03-03-ListValues-02.png\|Example "County" list when "State" is "Hawaii".\|frame]]

			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.

			{\|class="attn-box"
			\|
			⚠
			\|
			'''''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.
			\|}


			<big>Example "Include Lookup Results" setup using an XML Lookup</big>

			To use XML Lookup to generate a field's list values:
			# Drag the XML file to the Project (or a folder in the Project).
			# Select the Data Element you want to add XML Lookup to.
			#:*<li class="fyi-bullet"> 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.
			# Open the "Lookups" editor (Press the "..." button).
			# Press the "Add" button and select "XML Lookup".
			# Using the "Source" button, select the XML file you added to the Project in Step 1.
			# Open the "Record Selector" editor (Press the "..." button).
			# Enter an XPath expression to select an XML node from the source XML file.
			#*<li class="attn-bullet"> The Record Selector is crucial to XML Lookup. The lookup will fail if no record is selected.
			#* Use field variables (<code>%FieldName</code>) to insert "lookup fields".
			#* The lookup field(s) value will be inserted into the XPath when XML Lookup runs.
			#* Example: <code><nowiki>//state[@name='%State']/counties/county</nowiki></code>
			# Open the "Value Selectors" editor (Press the "..." button).
			# Press the "Add" button to add a new Value Selector.
			# 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: <code><nowiki>@name</nowiki></code>
			# 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
			#:*<li class="fyi-bullet"> 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).
			# Press "OK" when finished to exit the Value Selectors editor.
			# Set the "Conflict Disposition" to "Ignore".
			#*<li class="attn-bullet"> 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.
			# When finished configuring the XML Lookup, press "OK" to exit the Lookups editor.
			# Save changes to the Data Element.
			# Navigate to the target Data Field/Data Column selected in step 11.
			# At the bottom of the property grid, expand the "List Values" settings.
			# Enable "Include Lookup Results" by changing it to "True".

	=== Value Interpretation ===		=== Value Interpretation ===