While often the data you want to show on a form is stored in a field on a table, this is not always the case. There are times when the data you need to show must run code to come up with the final output. In this article, I will show you how to write a D365 Display method. Display methods run code based on the data in the current record. And show a value that is not stored directly in a table field.
Explaining Display Methods
On a form, you can show a grid. And on that grid you can show multiple columns such as strings, and numbers, and enum values.
Almost always, the controls in this grid, have the DataSource property set. This means that the grid is showing you records retrieved from the DataSource on the form.
And most of the time, the DataField property is set on the controls in the grid of a form. This means that the control will show you the value stored in the DataSource field specified.
However, there are times when the value that you wish to show is not stored explicitly in a field on the table. In these cases, you can use what is called a Display method. Display methods are very similar to regular x++ methods. However, there are a couple of differences.
- They use the keyword ‘display’ in the method definition.
- They should return a value that can be displayed in a form control. In almost all cases, this means they should return a basic data type, such as a string, an integer, a real, or an enum. They should not return a class object, as these cannot be display directly on a form. And while it is possible to have display methods return an array, this is not very common.
A Basic Example
To help teach you how to write a D365 display method, I will start with a basic example. Let’s pretend that I have a table and form. On this form, I have a field where I show someone’s First Name. And I show another field where I show someone’s Last Name. What happens if I wish to show a single field that displays the combined First Name and Last Name?
I could create a new field named ‘Full Name’ and override the ‘insert’ method on the table. Then add code to the ‘write’ method, so that every time the record is written to the database, the First Name and the Last Name field values are combined and then stored in the ‘Full Name’ field.
This would work, but I would essentially be stored the same data twice. And while this helpful to do in many cases for the sake of SQL performance, this same thing can be accomplished using a D365 Display method.
Example Display Method Code
The D365 Display method for the above example would look like this.
public display Name FullName(){ Name fullName = this.FirstName + this.LastName; return fullName;}Notice that the keyword ‘display’ is used in the method definition. Without this keyword, you cannot use this method on a form control or report.
The method returns an EDT of type ‘Name’. As a Best Practice, an ‘EDT’ should always be used as the return type on a display method. You should not use a base data type, such as int, or str, or real.
There are a few benefits of using an EDT.
- The EDT has a Label property on it. And so when a display method is used on a form control, that control can inherit the label of the EDT returned on the method. While you can override the label on a form control, having a default label is still very helpful.
- Some of the properties on the EDT ultimately affect how the data is shown. For example, if the EDT is of type string, the EDT will have a string length associated with it. The EDT’s string length will help control how many characters of text are shown on the form control.
- A display method can actually be added to a table ‘field group’. And that field group can be set on a grid control in a form. The base data type of the EDT on the display method tells the system what type of control to create on the grid. such as String control, or Combo Box, or Checkbox, ect.
A display method must always return a value. This is the value that will be displayed on the form.
You can read Microsoft’s documentation here.
Where To Add A Display Method
D365 Display methods can actually be added to multiple objects. They can be added as Table methods, form methods, form data source methods, report methods, and report design methods.
When a display method is created on a form object, only that form can use that display method. And the same thing when a display method is created on a report.
Therefore, it is recommended that you add the display method to a table whenever possible. Adding the method to a table, allows the display method to be used by any form that has a Data Source that uses that table. This allows for your code to be reused in a lot more places.
Add A Display Method To A Form
The next step to learning how to write a D365 display method is to connect your display method to a form control.
First, create a new control on the grid of your form.
Right click on the control and select ‘Properties‘.
Se the ‘Data Source‘ property to be the name of the Data Source on the form, whose underlying table contains the display method.
Finally, instead of setting the ‘Data Field‘ property, set the ‘Data Method‘ property to be the name of your display method.
That is it. Now, for each record in the grid, the display method will be run. The display method ‘this’ variable will contain the current record being displayed. It will use values on the record, and the code you have written in the method to produce a result that is shown in the form control.
Product Name Examples
There are many examples where using Display methods is very help.
Imagine you are storing a field which is the primary key on a related record. Typically, in order to show any data on that related record you would need to add the related table as a Data Source. Then add fields from that Data Source to your form. Using a D365 Display Method you can write x++ code to select the related record. Then display a value on the related record.
For example, the ItemId is a field that is stored on many tables. SalesLine is one of those tables. The name of the item is stored on the related table InventTable. Instead of joining to the InventTable, the display method ‘itemName’ on the SalesLine table can be used. This method calls other methods to find the related InventTable record. Then it runs additional logic to determine what text should display as the item name.
public display SalesLineShowItemName itemName() { return this.inventTable().itemName(this.inventDim()); }Customer Address example
Let’s look at another example. Most of the customer information is stored on the ‘CustTable’ table. Customers can have many addresses related to them. But they are are only allowed to have one address marked as the ‘primary’ address. In order to retrieve all of the primary address information, several related tables need to be selected.
Instead of doing the work of adding many Data Sources to a form, the display method ‘primaryAddress’ on the CustTable can be used. This method retrieves the related postal address record. Then displays the ‘Address’ field from that table.
display LogisticsAddressing address() { return this.postalAddress().Address; }Cautions When Using Display Methods
There are some things that you should be aware of when using a D365 Display method.
Whenever a display method is used on a form, the display method needs to be run once for every record shown on the form. This can have a performance impact. If the display method you have written is time-consuming to run, the form will not be able to show the data quickly. And this will cause the user experience to suffer.
To mitigate this, instead of putting the display method on a control that is on a grid. You can put the display method on another tab, which is not always shown to the user. The display method will only be run for controls that are being shown to the user.
In addition, the filter functionality on a grid control cannot be used on a column that uses a display method. This is an important limitation to pay attention to. Therefore, if it is a requirement that the user be able to filter the control, then you need to not use a Display Method. And instead join in Data Sources, or store the value off into a field that can be used.
The reason for this is because in order for the system to filter the results of a display method, the display method would need to be run against every record in the table. And this would be a huge performance impact. Whereas, one of the things that makes Display Methods practical, is that they are only run on records the users is viewing.
Caching Display Methods
One way that the performance of a display method can be improved is to cache the display method. Microsoft Dynamics 365 for Finance and Operations uses a lot of caching to improve the performance of the forms. However, all display methods are not cached automatically.
Old Way Of Caching A Method
In order to cache the display method, first override the ‘init’ method on the form.
Next, add the a line of code in this format:
<Data Source Name>_ds.cacheAddMethod(tableMethodStr(<TableName>, <Display Method Name>));
For example, there is code on the CustTable form, to cache the edit method named ‘phone’. It is found in the ‘init’ method. It looks like this.
custTable_ds.cacheAddMethod(tableMethodStr(CustTable, phone));The code uses the method cacheAddMethod on the form Data Source. The name of display method is passed into the method. The code uses the global function ‘tableMethodStr’ to get the name of the method. This global function takes the name of the table, and the name of the method as parameters. This is useful, because if the name of the method ever changes, a compile error will be thrown until this code is changed. Whereas a hard-coded string would only fail at runtime.
Please see additional Microsoft documentation here.
New Way Of Caching A Method.
There is a new way of Caching a method. Instead of overriding the ‘init’ method on a form, and adding a call to ‘cacheAddMethod’, the new way is much simpler. Simply add this attribute just above your method definition in code.
[SysClientCacheDataMethodAttribute(true)]Summary
In this article I showed you how to write a D365 display method. I explained that a display method is just like a normal method, except that it uses the ‘display’ keyword. Most of the time, Display methods should be added to Table objects in the Application Explorer. And then they are tied to a form control by setting the Data Source and Data Method properties on the control.
Display methods are incredibly useful. They make it much easier to show values on related records. And they allow code to be run and values to be shown that are not stored in any table.
There is a performance impact to using display methods. And you cannot filter on display methods. So developers should keep these limitations in mind before using them.
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.
