Inconsistent treatment between "displayField" and "labelField"

[patricknelson]

The code documents each field as:

• displayField: The field or method used to identify the results.
  • To me this is the field on the foreign object who's value is used to present what was selected and populates inside of AutoCompleteField on the local object.
• labelField: The field or method used for the display of the result in the listing.
  • To me this means the field on the foreign object who's value is used to present an option in the suggested list prior to selection.

However, the treatment appears to be:

• ✅ On initial form load, the displayField is used as the value inside of AutoCompleteField.
• ✅ Suggestions listed during typing are pulled from labelField.
• ❌ Selected value (from suggestion list) inserted into AutoCompleteField value is pulled from labelField instead of displayField as expected.

To me this is unexpected behavior, as ultimately the value used to populate the contents of AutoCompleteField should be consistent not only on field initialization, but also after interaction as well. Once you save, it initializes again with displayField's value.

Example 1: Stored field is "City", displayField is "FullTitle" (City + Country).

Example 2: Stored field is "City", labelField is "FullTitle" (City + Country).

Workaround:

Currently, the workaround required for consistency is to define both ->setDisplayField() and ->setLabelField() to the same field, which may not be obvious to a developer using this module until they've noticed that problem, takes the step to investigate and then takes action.

Possible fixes for consistency:

1. Ensure that your selection from the suggestions (who are labeled via labelField) populates AutoCompleteField with the value from displayField.
2. Eliminate these two fields and just use one (e.g. settle either on displayField or labelField).

Personally I would prefer option 2, because I would expect the suggestion I select to always populate into the field and should consistently remain in the field on save and etc. I'm not sure what the use case is for keeping them separate. But if we do keep them separate, their function should be clearly defined and they should function consistently.