How To Override An Existing Lookup Method: Event Handler

In this article you will learn how to override an existing lookup method that exists on a form that is in a different model than your own. In a previous article we looked at how to override the lookup method in D365. However, there are some extra steps needed to learn how to override an existing lookup method in D365.

What Are Lookup Methods?

If you are new to lookup methods, please start with this article: How To Create a Lookup Method In D365 Forms.

It explains that lookup methods allow users to view multiple columns from a related record to help with selecting a value for the current record. This forms the basis for any relational database. First, it really speeds up data entry for the user. And secondly it helps ensure data integrity is maintained.

When designing a table in D365, a developer can specify the default fields to be shown in a lookup. However, a developer can also override the columns shown in the lookup for use on a particular form. On top of that, developers can also filter the rows returned in a lookup to be a subset of all the records in the table. This is really powerful and again makes the form even easier for a user to use.

In a previous article, I showed you how to override the lookup method. However, this was on a form that you created as part of your model. There are times when you will want to override the lookup method on an existing form that is not part of your model. This requires some additional steps.

Two Ways To Override An Existing Lookup Method

There are actually two ways to override an existing lookup method.

• Using a Form Control Event Handler
• Using Chain Of Command

I will explain both methods. No pun intended. Ultimately, I do not know that one way is preferred over the other. I am more partial to using Chain Of Command, because I find the attribute syntax easier to write. And I tend to put all of my other extension code in a Chain Of Command class. But please use whatever you are most comfortable with.

If you are new to Chain Of Command, I recommend you read this previous article on Chain Of Command Fundamentals.

The Example Scenario

In this section, consider the example that you want to override an existing lookup method on the customer details form. Go to customer form by searching for ‘all customers’ in the search bar. Then select a customer to open the customer details form.

The CustTable form, contains a field that lets a user select the customer group. By default this lookup method shows two columns. The customer group ID and the Description.

Let’s pretend we wish to show a third column. The related Customer Group form contains a field named ‘Terms of payment’. In this example, I will show you how to display additional columns in the lookup.

Override An Existing Lookup Using An Event Handler

First, we will look at how to override an existing lookup using an event handler. Open Visual Studio. Using the Application Explorer, search for the ‘CustTable’ form. Right click the form, and select ‘open designer’.

Next, we need to locate the customer group control. The easiest way to do this is to use the Preview pane. In the preview pane, locate the field labeled ‘Customer group’. Visual studio will then also highlight the control in the right designer pane.

You could have expanded the form design nodes yourselves until you located the control. However, that way takes a little bit more time.

Next, expand the control. Then expand the Events node.

After that, right click the ‘OnLookup’ node and select ‘Copy event handler method’ from the dialog’.

Create a new D365 project. In Visual Studio, go to File>New>Project. Select the Dynamics 365>Finance Operations. Finally, enter a name and then click ‘Ok’.

Next, create a new class, by right clicking on the project and select Add>Class. Name the class TutorialCustTable_Form_Handler.

Now that the class is created, paste the text in your clipboard into the class. Press ctrl-v to do this. Ultimately, you should now see this code in a code editor window.

class TutorialCustTable_Form_Handler
{
    /// <summary>
    ///
    /// </summary>
    /// <param name="sender"></param>
    /// <param name="e"></param>
    [FormControlEventHandler(formControlStr(CustTable, Posting_CustGroup), FormControlEventType::Lookup)]
    public static void Posting_CustGroup_OnLookup(FormControl sender, FormControlEventArgs e)
    {
    }
}

Populating the Event Handler Code

Currently, the code tells the system to override an existing lookup method on the customer form. However, we need to set what the new lookup will do.

In our example, we need to display a lookup form that shows three columns: Customer group ID, Description, and Payment Term ID.

However, since we are overriding a lookup on a form that is not part of our model, we also need to cancel the original base lookup method. To do this, call the method ‘CancelSuperCall()’ in the lookup code. See the complete code below.

class TutorialCustTable_Form_Handler
{
    /// <summary>
    ///
    /// </summary>
    /// <param name="sender"></param>
    /// <param name="e"></param>
    [FormControlEventHandler(formControlStr(CustTable, Posting_CustGroup), FormControlEventType::Lookup)]
    public static void Posting_CustGroup_OnLookup(FormControl sender, FormControlEventArgs e)
    {
        SysTableLookup      sysTableLookup  = SysTableLookup::newParameters(tableNum(CustGroup), sender);
        
        // Add the lookup columns
        sysTableLookup.addLookupfield(fieldNum(CustGroup, CustGroup));
        sysTableLookup.addLookupfield(fieldNum(CustGroup, Name));
        sysTableLookup.addLookupfield(fieldNum(CustGroup, PaymTermId));

        // Run the lookup
        sysTableLookup.performFormLookup();

        //cancel the call to super() to prevent the system from trying to show 
        //the lookup form twice and cause an error.
        FormControlCancelableSuperEventArgs cancelableSuperEventArgs = e as FormControlCancelableSuperEventArgs;
        cancelableSuperEventArgs.CancelSuperCall();
    }
}

If you forget to add the CancelSuperCall, you will receive an error when you try your lookup. The error will say ‘More than one form was opened at once for the lookup control’.

After adding all the code, save and compile your project.

In order to see your latest changes, reload the customer details form in your browser.

Finally, test out the overridden lookup method. You show now see all three columns showing in the lookup.

Override An Existing Lookup Using Chain Of Command

In this next article, I will explain how to override an existing lookup method using chain of command.

Conclusion

In this article you learned how to override an existing lookup method on an existing form. This is very useful for when you need to change the functionality on a form that is not part of your model. You learned how to override the lookup using form handlers. The lookup method is not the only form control method you can override on an existing form. Using these same techniques you can apply them to other situations.

Peter Ramer

Peter Ramer is a part of the Managed Application Services team at RSM working on Microsoft Dynamics 365. He focuses on the Retail and Commerce industries. When he is not solving problems and finding ways to accelerate his clients' business, he enjoys time with his three kids and amazing wife.