Lookup form returning more than one value

I have been posted with the question of creating a lookup that would return more than 1 value into the calling record, filling in a number of fields and populating the selected control with the corresponding value at the same time.

I will try to answer that question by an example from the standard application, particularly using one of the forms owned by my (Inventory) team.

Example

If we take a look at the lookup form for one of the item inventory dimensions (Configuration, Size or Color), we'll see the following tab page on it:
(assuming more than 1 item dimension is enabled for this item)

Basically, the user is able to select the configuration that belongs to a specific dimension combination. Note the check-box "" under the grid. If the user sets that check-box and then selects the configuration from a combination, the values for all item dimensions will be copied to the record from the parent form.
So, basically, the lookup returns more than just the configuration dimension value, but also size and color.

How is that implemented?

The lookup is implemented using a custom form, present in AOT, with name ConfigIdLookup.

The methods important for a working lookup are:

• init() method.

In particular, the way the calling control is determined based on the args passed into the form:

callerControl = SysTableLookup::getCallerStringControl(element.args());

• selectMode() method.

(called from setSelectMode() on this form). This method accepts an AX form control as parameter, and informs the kernel about which control should be used as the returning control.

• closeSelect() method.

This method is executed on lookup forms wheneven a selection of a particular value is made. So, obviously, in this method you still have access you all the fields of the datasource with the selected record, as well as to the calling form through element.args(). Here is the code that handles the update of multiple fields:

    if (ctrlTabPageCombination.visible() &&
        selectAllCombi &&
        ctrlTabPageCombination.isActivePage())
    {
        // Genericly determine the InventDim datasource on the calling form
        callerInventDimDS = inventDimFormSetup.callerInventDimFormDatasource();
        if (callerInventDimDS)
        {
        //...
            // Get the current record of that datasource
            callerInventDim = callerInventDimDS.cursor();
            // Set the needed fields on the record based on the selection in the lookup form
            // Basically, this is how you can achieve returning more than one value from a lookup
            // Get the record where the values need to be put in, and put them in from the currently selected record
            if (inventDimCombination_ConfigId.visible() && inventDimCombination.ConfigId)
                callerInventDim.ConfigId = inventDimCombination.ConfigId;
            if (inventDimCombination_InventSizeId.visible() && inventDimCombination.InventSizeId)
                callerInventDim.InventSizeId = inventDimCombination.InventSizeId;
            if (inventDimCombination_InventColorId.visible() && inventDimCombination.InventColorId)
                callerInventDim.InventColorId = inventDimCombination.InventColorId;
            // Refresh the datasource so that values are displayed on the calling form
            callerInventDimDS.refresh();
        }   
    }