Customizing Microsoft Dynamics AX 2009

Form Customization

Like most of the elements in the AOT, forms can be customized to include additional information and actions, such as fields and buttons, and to fulfill user requirements. The design and behavior of a form are provided by a combination of the form and the tables that are bound to the form.

Best Practices

Even though you can implement all necessary customizations by modifying just the form, we don’t recommend this approach. As a best practice, you should implement application customizations at the lowest level possible, preferably through changes to a table or a class rather than through changing specific forms.

The best way to implement forms is to keep most of the business logic and design decisions in tables and classes, focusing only on the positioning of fields and menu items when designing the form. This approach has several advantages:

• X++ code in forms is executed on the client tier only; X++ code in table methods can be executed on the server tier to optimize performance.

• Customizations made to a form are restricted to that form; customizations made to a table or a class apply to all forms that use that table or class as a source of data. This results in a consistent user experience wherever the table is used.

• When a form is customized, the entire form is copied to the current layer; customizations to tables and classes are more granular. When fields, field groups, and methods are customized, a copy of the specific element is in the current layer only. This makes upgrading to service packs and new versions easier.

• X++ customizations to the validate, default, and database trigger methods on forms, such as create, validateWrite, and write, affect only the records that are modified through the user interface. If records are modified somewhere other than that form, then that customized form’s X++ code doesn’t execute.

The following actions be customized only on the form, not by customizing a table:

• Enable and disable fields and other user interface elements (Enabled = Yes/No)

• Show and hide fields and other user interface elements (Visible = Yes/No)

However, you should consider having a table or a class method determine the business logic on the form. An example of this is shown in the following lines of X++ code from the InventTable form, in which a method on the table determines whether a field can be edited.

void setItemDimEnabled()
{
    boolean     configActive    = inventTable.configActive();
    ...
    inventTable_ds.object(
             fieldnum(InventTable,StandardConfigId)).allowEdit(configActive);
    inventTable_ds.object(
             fieldnum(InventTable, StandardConfigId)).skip(!configActive);
    ...
}

By moving these decision-making methods to a table or class, you make them available to other forms.

Learning Form Fundamentals

The rich client user interface in Dynamics AX is made up of forms that are declared in metadata and often contain associated code. Ideally, you should customize these forms as changes to metadata and make any changes at the lowest level (i.e., table level rather than form level) possible to ensure the greatest amount of metadata and code reuse.

The most visible change from Dynamics AX 4.0 to Dynamics AX 2009 is the change from a predominantly multiple-document interface (MDI) to a predominantly single-document interface (SDI). Forms with a WindowType property value of Standard (the default) are now SDI forms, and the WindowType values of ListPage and ContentPage have been added to fill the Workspace content area to provide a navigation experience similar to that in Microsoft Office Outlook. The different WindowType values share the same object model, metadata, and method overrides, so form customization skills are applicable across all forms.

Customizing with Metadata

Metadata customization is preferred over code customization because metadata changes (also called deltas) are easier to merge than code changes.

When customizing forms, you should be aware of the important properties, the metadata associations, and the metadata inheritance that is being used to fully define the form and its contents.

Metadata associations

You edit the metadata in Dynamics AX by using the AOT. The base definitions for forms contained within the AOT\Forms node is composed of a hierarchy of metadata that is located in other nodes in the AOT. To fully understand a form, you should investigate the metadata associations it makes. For example, a form uses tables that are declared in the AOT\Data Dictionary\Tables node, security keys that are declared in the AOT\ Data Dictionary\Security Keys node, menu items that are declared in the AOT\Menu Items node, queries that are declared in the AOT\Queries node, and classes that are declared in the AOT\Classes node.

Metadata inheritance

You need to be aware of the inheritance within the metadata used by forms. For example, tables use Base Enums, Extended Data Types, and Configuration Key. A simple example of inheritance is that the Image properties on a MenuItemButton are inherited from the associated MenuItem if they aren’t explicitly specified on that MenuItemButton. Table 5-4 shows important examples of pieces of metadata that are inherited from associated metadata.

Table 5-4. Examples of Metadata Inheritance

Inheritance also occurs within forms. Controls that are contained within other controls receive certain metadata property behaviors from their parents unless different property values are specified, including HTMLHelpFile, HTMLHelpTopic, Security Key, Configuration Key, Enabled, and the various Font properties.

Menu definitions

Dynamics AX 2009 has a number of new navigation capabilities in the form of area pages and the address bar to complement the existing navigation pane (sometimes referred to as the “WunderBar”). In terms of metadata, the area pages and address bar are mostly just additional methods of exposing the existing menu metadata defined in the AOT\Menus and AOT\Menu Items nodes. The modules are defined in AOT\ Menus\MainMenu, and you can follow the menu structure from that starting point. For example, the Accounts Receivable module is represented by the AOT\Menus\MainMenu\Cust MenuReference and is defined as AOT\Menus\Cust.

The menu metadata for list pages and content pages has some small changes. A primary list page is implemented as a submenu with IsDisplayedInContentArea=Yes, MenuItemType=Display, and MenuItemName populated. A secondary list page, a list page that adds ranges to a primary list page, is implemented as a menu item under the submenu of its primary list page. The list pages and content pages are navigation places, so all their menu item and submenu references are set to IsDisplayedInContentArea=Yes so that they appear in the Places group in the area pages and the Places section in the navigation pane. The other menu items in the root of each module’s menu definition are displayed in the Common Forms group in the area pages and in the root of the Forms section in the navigation pane.

Important metadata properties

Many properties are available to developers, but some are more important than others. Table 5-5 describes the most important form design properties, and Table 5-6 describes the most important form data source properties.

Table 5-5. Important Form Design Metadata Properties

Table 5-6. Important Form DataSource Metadata Properties

Image metadata

Dynamics AX 2009 makes greater use of images and icons throughout the application to provide the user with additional visual cues. Icons are used extensively in list pages to help users identify specific actions. The metadata properties used to associate images and icons with buttons, menus (menu items), and other controls depends on their location. Table 5-7 describes the metadata properties used for the three common image locations.

Table 5-7. Image Metadata

SomeButton.normalImage(SysResource::getImagePath("<AOT
Resource Name>"));

Customizing with Code

You should customize forms with code only as a last resort. Customizing with metadata is much more upgrade friendly since metadata change conflicts are straight forward to resolve whereas code change conflicts need deeper investigation that sometimes involves creating a new merged method that attempts to replicate the behavior from the two original methods.

When you start to customize Dynamics AX, the following ideas may provide good starting points for investigation:

• Leverage examples in the base Dynamics AX 2009 codebase by using the Find command on the Forms node in the AOT (Ctrl+F).

• Refer to the system documentation entries (AOT\System Documentation) for information about system classes, tables, functions, enumerations, and other system elements that have been implemented in the AX kernel.

• When investigating the form method call hierarchy for a suitable location to place customization code, add a debug breakpoint in the Form Init method and step through the execution of method overrides. Note that control events (e.g., clicked) do not trigger debugging breakpoints. An explicit breakpoint (i.e., "breakpoint;“) keyword is needed in the X++ code.

To enable simpler code maintenance, the following rules should be followed:

1. Utilize the table and field functions of FieldNum (e.g., fieldnum(SalesTable, SalesId)) and TableNum (e.g., tablenum(SalesTable)) when working with form data sources.

2. Avoid hard coding strings by using sys labels (e.g., throw error(“@SYS88659”);) and functions like FieldStr (e.g., fieldstr(SalesTable, SalesId)) and TableStr (e.g., tablestr(SalesTable)).

3. Use as few method overrides as possible. Each additional method override has a chance of causing merge issues during future upgrades, patch applications, or code integrations.

When X++ code is executed in the scope of a form, there are some form-specific global variables created in X++ to help developers access important objects related to the form. These global variables are described in Table 5-8.

Table 5-8. Form-Specific Global X++ Variables

element.args().record().TableId == tablenum(SalesTable)

name = element.design().addControl(FormControlType::String,
"X");

if (SalesTable.type().canHaveCreditCard())

SalesTable_DS.research();

rangeSalesLineProjId    = salesLine1_q.dataSourceTable-
(tablenum(SalesLine)).addRange(fieldnum(SalesLine, ProjId));

rangeSalesLineProjId.value(ProjTable.ProjId);

SalesTableQueryBuildDataSource =
SalesTable_QR.query().dataSourceTable(tablenum(SalesTable));

backorderDate.dateValue(systemdateget());

Form method overrides allow developers to influence the form life cycle and how the form responds to some user-initiated events. The most important form method overrides are described in Table 5-9. The two most overridden form methods are Init and Run.

Table 5-9. Form Method Override Explanations

Form data source and form data source field method overrides allow developers to influence how the form reads and writes its data and allows developers to respond to user-initiated data-related events. The most important form data source method overrides are described in Table 5-10. The five most overridden form data source methods are Init, Active, ExecuteQuery, Write, and LinkActive.

Table 5-10. Form Data Source Method Override Explanations

Three commonly used form data source field method overrides are described in Table 5-11. The most overridden form data source field method is the Modified method.

Table 5-11. Form Data Source Field Method Override Explanations

Displaying an Image

The following example illustrates how to customize the sales order form to allow a user to upload and display an image of a custom order. In this example, a customer must be able to place an order for a bike through Enterprise Portal and upload a sketch of the bike at the same time. An example of a customer-supplied bike image is shown in Figure 5-8.

Figure 5-8. Uploaded bike image

This image must be stored in the database and attached to the sales order line. Sales order lines are stored in the SalesLine table. You could add a new field to the SalesLine table of the type container and store the image in this field, but this example uses the document management functionality in Dynamics AX. The image is therefore stored in the DocuValue table with a reference to a record in the DocuRef table from the image record in DocuValue to the SalesLine record. The relationship and multiplicity among the three tables is shown in Figure 5-9.

Figure 5-9. Relationship among the SalesLine, DocuRef, and DocuValue tables

In this example, a document type named Image stores the attached file in the disk folder. The Image document type is shown in Figure 5-10. The Document Type form is located in the navigation pane, Basic\Setup\Document Management\Document Types.

Figure 5-10. Image document type

Any uploaded image is therefore stored in the document management system; a user can view the image by either clicking the Document Handling icon on the status bar or choosing Document Handling on the Command menu. The user sees the dialog box shown in Figure 5-11, in which the image can be viewed, modified, or deleted, and additional notes or documents can be attached.

Figure 5-11. Storage of the uploaded bike image in the document management system

Displaying an Image on a Form

You can display the image directly by placing it on a separate Image tab on the sales order form. Figure 5-12 shows an order for a bike with a frame size of 21 inches and a wheel size of 28 inches. The user can click the Image tab to view the uploaded bike image and confirm that it matches the ordered item before confirming the sales order. The Sales Order form (AOT\Forms\SalesTable) is located in the navigation pane, Accounts Receivable\Sales Order.

Figure 5-12. Uploaded bike image displayed on the Sales Order form Image tab

The following two example implementations describe how to use the document management tables as data sources in the form and how to create a separate method on the SalesLine table. These examples demonstrate customization of the SalesTable sales order form and the SalesLine table.

Displaying an Image by Using Joined Data Sources

One way to display the image is to apply the DocuRef and DocuValue tables as data sources for the SalesTable form. The following example creates a DocuRef data source based on the relationship among the SalesLine, DocuRef, and DocuValue tables shown in Figure 5-9. The DocuRef data source relates to the DocuRef table and is joined to the SalesLine data source. Additionally, a DocuValue data source is created to connect to the DocuRef data source. Table 5-12 shows additional properties of the data sources.

Table 5-12. DocuRef and DocuValue Property Settings

The properties JoinSource and LinkType allow the DocuRef and DocuValue records to be fetched when the user moves from one line to another. The remaining properties disable editing of the records.

You can attach multiple files, documents, and notes to a SalesLine record by using the document management feature, but the goal of this example is to display an image from a linked document named Image. You can limit the retrieved records from the DocuRef table by adding a range to the query used by the DocuRef data source. You do this by customizing the Init method on the DocuRef data source, as shown here.

public void init()
{
    super();

    docuRef_ds.query().dataSourceTable(
                       tableNum(DocuRef)).addRange(
                       fieldNum(DocuRef,TypeId)).value(queryValue('Image'));
}

This X++ code limits the query so that it retrieves only records from the DocuRef table in which the TypeId field is equal to the value ‘Image’.

NOTE

The use of a constant such as the word Image is not a best practice. The value must be retrieved from a configuration table so that the user can decide the naming. ‘Image’ is hard coded in the preceding example only to improve the readability and limit the scope of the example.

The image is displayed by using a window control, which is placed in a tab control, as shown in Figure 5-13.

Figure 5-13. Tab and window controls in the SalesTable form

Although the image is stored in the File field on the DocuValue table, to display the image you can’t simply link the field as a DataField value on the window control property sheet. The image must be parsed to the control by using a method on the control in X++ that uses the FormWindowControl object. The AutoDeclaration property on the FormWindowControl object is therefore set to Yes so that the forms designer automatically declares an object handle with the same name. This handle can be used in X++ and manipulated at run time because the form application runtime automatically ensures that it is a handle to the FormWindowControl object. The Width and Height properties are set to Column width and Column height so that the image takes up all the space on the tab.

The last step is to parse the retrieved image from the DocuValue table to the BikeImage FormWindowControl object. You can do this when a DocuValue record buffer is present. This record must contain an image that is stored in the database, and the X++ code should be placed in the active method on the DocuValue data source and look like the following.

public int active()
{
    Image   image;
    int    ret;
    ret = super();
    if (docuValue.File)
    {
        image = new Image();
        image.setData(docuValue.File);
        bikeImage.image(image);
    }
    else
    {
        bikeImage.imageResource(0);
    }
    return ret;
}

This code determines whether a value exists in the File field and, if so, instantiates an image object and parses the File field value to the image object. This object is then parsed by using the Image method to the FormWindowControl object that displays the image. If the File field doesn’t contain a value, the imageResource method on the FormWindowControl object is called with a value of 0 to clear the control of any previous content. The active method is executed only if a DocuValue record has been retrieved. However, if a user moves from an order line with an image to an order line without an image, the image isn’t cleared because the active method isn’t executed. If you add the following line to the active method on the SalesLine data source, the image is cleared when a new order line becomes active and before the DocuRef and DocuValue records are retrieved.

docuBikeImage.imageResource(0);

The customizations described in this section make it possible to display the image on the Image tab. This solution has one downside, however. Whenever a user moves from one order line to another or a line is created or saved, calls are made from the client to the server, and lookups are made in the database for the DocuRef and DocuValue data sources. You can see this by turning on the client/server or SQL trace option in the Options dialog box, which you access from the Tools menu. The next section addresses this issue and offers a solution—decreasing the number of client/server calls and lookups in the database.

Displaying an Image When Activating the Image Tab

The following example implements a solution similar to the previous example, but it results in calls to the server and the database only when the image is actually displayed.

The TabPage control must be added to the SalesTable form and contain a FormWindowControl with property settings similar to those in the preceding example. The DocuRef and DocuValue tables are not, however, added as data sources for the form. Instead, this example retrieves the image—the only element shown on the Image tab—from the database only when the user chooses to display the content of the Image tab. You configure this by adding the following X++ code to the pageActivated method on the TabPage control.

public void pageActivated()
{
    Image           image;
    DocuValueFile   docuValueFile;
    ;
    docuValueFile = salesLine.bikeImage();
    if (docuValueFile)
    {
        image = new Image();
        image.setData(docuValueFile);
        bikeImage.image(image);
    }
    else
    {
        bikeImage.imageResource(0);
    }

    super();
}

This code is very similar to the code added to the DocuValue active method, but in this case the value is retrieved from a bikeImage method on the SalesLine table. The bikeImage method is a new method created on the SalesLine table with the following content.

server public DocuValueFile bikeImage()
{
    DocuRef     docuref;
    DocuValue   docuValue;
    ;
    select firstonly tableid from docuRef
        where docuRef.RefCompanyId == this.DataAreaId &&
              docuRef.RefTableId   == this.TableId    &&
              docuRef.RefRecId     == this.RecId      &&
              docuRef.TypeId       == 'Image'
    join file from docuValue
        where docuValue.RecId  == docuRef.ValueRecId;

    return docuValue.File;
}

The select statement in the bikeImage method is a combination of the two lookups in the database produced by the runtime shown in the first sample implementation, which used data sources. However, the statements in this method are joined. The bikeImage method could simply be implemented in the SalesTable form, but implementing it on the SalesLine table allows it to be reused in other forms or reports and executed on the server tier, if required.

The advantage of this implementation method is that both database lookups and calls from the client to the server are reduced by half. And because calls are made only when the Image tab is activated, they aren’t made when a user simply moves through the order lines without viewing the content of the Image tab. The disadvantage, however, is that the user can’t personalize the form or move the display of the image to another tab because retrieval of the image is dependent on activation of the Image tab.