The standard “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, a LUA script can be created either by using the “Adopt Fields > Custom…” menu option or by placing a ‘.lua’ script inside of a folder called “Adopt Fields” within the data source’s “Scripts” folder.
The LUA script is called once for each link in the document, and on entry four string variables are defined. It is the responsibility of the LUA script to change the values of these variables before exiting. EasyCatalog will then use the contents of these variables to modify the link in the document.
| Variable | Contents |
|---|---|
| key | The key field value that identifies the record that the field is linked to |
| datasource | The name of the data source that the field is linked to |
| fieldname | The name of the field that the field is linked to |
| fieldcontent | The content of the field in the document. For image fields, this will be empty |
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | -- get the record passed in: my_link_record = RECORD.get(key, datasource) if my_link_record == nil then error ("Record not found"); end; -- find the 'Position field for it my_field = my_link_record:field('Position'); if my_field == nil then error ("Field not found"); end; 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"); end; -- 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:
1 2 3 | -- original key like this - 'key_locale' -- Replace the locale part of the key with "es-ES" key = key:match(".*_") .. "es-ES"; |
The Custom Link Adoption Dialog
The Custom Link Adoption dialog can be used to develop the LUA script, as it shows both the existing document links and what they will become after running the script on the document.
The dialog displays the active documents links on the left, and the links after processing by the script. Pressing the Test button will execute the code for each link and present the results in the right hand column. Each element of the link is color coded to show validity, with green valid (the field links to a valid data source, record and field) and red invalid.
Saving Scripts To the Adopt Fields Menu
Custom adoption can be used as a regular part of a workflow, and as such scripts can be added to the “Adopt Fields” menu. Selecting “Save..” on the popup at the bottom of a dialog will prompt for a name. This is then permanently added to the menu for the current data source. These are stored inside the Scripts folder inside the Data source folder and can be removed manually.
