Microsoft Dynamics AX 2009 : Form Customization (part 1) - Learning Form Fundamentals

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 1 shows important examples of pieces of metadata that are inherited from associated metadata.

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 2 describes the most important form design properties, and Table 3 describes the most important form data source 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 4 describes the metadata properties used for the three common image locations.

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:

• 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.
  
  
• 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)).
  
  
• 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.

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 6. The two most overridden form methods are Init and Run.

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 7. The five most overridden form data source methods are Init, Active, ExecuteQuery, Write, and LinkActive.

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