The “Adopt Fields” method of relinking assumes field names and key field values are consistent between the existing links and the new data. It was designed to link fields from one data source to another, and as such is limited to changing the key element of a link.
In some circumstances it may be necessary to implement custom re-linking logic. Possibilities with this method include:
- Changing a key.
- Relinking a field from one record to another.
- Altering the field name.
To implement this logic, create a .lua script and place it inside a folder called “Adopt Fields” in the “Scripts” folder of a data source. When correctly installed, the script name shows up on the “Adopt Fields->” sub menu. When actioned, the script is called for each link in the document selection, or for all the links when nothing is selected:
The script is passed 3 string variables representing each element of a link:
- key – Key field value
- datasource – Data source name.
- field – Name of a field.
The value of these variables when the script exits determines the link.
In addition a “records” parameter is passed, which is a RECORDSET object of the data panel selection. The example shown below combines these to relink records placed from one group to another group based on the “Position” field, which is numbered 1..n in each group:
-- get the record passed in:
my_link_record = RECORD.get(key, datasource)
if my_link_record == nil then
error ("Record not found");
-- find the 'Position field for it
my_field = my_link_record:field('Position');
if my_field == nil then
error ("Field not found");
item_position = my_field:content();
-- lookup the record in the selection with the same "Position"
selected_record_matches = records:filter('Position', item_position);
if selected_record_matches:size() == 0 then
error ("No corresponding record in selection");
-- Give the link a new key
key = selected_record_matches:getrecord(1):field('Key'):content();
Another example, that changes the ‘language’ part of a key:
-- original key like this - 'key_locale'
-- Replace the locale part of the key with "es-ES"
key = key:match(".*_") .. "es-ES";