How to send Reference Column Data using the Plugin API?

I’m encountering an issue with handling reference columns in my custom Grist widget. In my widget, reference column values are returned in a format like “TableName[VALUE]” (for example, “Table2[15.23]”) instead of simply returning the numeric reference ID. When I enter edit mode, I need to display a dropdown populated with data from the referenced table so that the user can select the proper option. However, if I save the record without changing anything, the widget sends back the full string (e.g., “Table2[15.23]”) rather than the expected numeric ID.

My ideal behavior is as follows:

  1. For a reference column, the widget should fetch data from the referenced table, build a dropdown that displays the proper values (using a display field such as “gristHelper_Display” or another designated field), and when saving, return the underlying numeric ID for the selected reference.
  2. Although reference columns sometimes appear as formulas in the metadata (e.g., with a formula like “$ref.Coluna3”), they should remain editable. That is, they must not be blocked like other formula fields; instead, they should allow a proper selection from the dropdown.

I’m looking for advice on how to implement this behavior:

  • How can I fetch and map the referenced table’s data so that the dropdown displays the correct values?
  • How can I ensure that, when saving, the widget returns the numeric reference ID rather than a formatted string like “TableName[VALUE]”?

Any guidance or examples from the Grist Forum or documentation would be greatly appreciated.