You edit the metadata in Microsoft Dynamics AX by using the AOT. The base definitions for forms contained within the AOTForms node consists 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 AOTData DictionaryTables node, menu items that are declared in the AOTMenu Items node, queries that are declared in the AOTQueries node, and classes that are declared in the AOTClasses node.

You need to be aware of the inheritance within the metadata used by forms. For example, tables use base enums, extended data types (EDTs), and configuration keys. 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.

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 Labels, HelpText, Configuration Key, Enabled, and the various Font properties.

Table 6-2 shows examples of pieces of metadata that are inherited from associated metadata.

The term dynalink refers to two data sources that are dynamically linked. A dynalink always has a parent data source and a child data source.

For example, the SalesTable (Sales orders) form where the SalesTable (Sales order) data source is the parent and the SalesLine (Sales order line) data source is the child. If two data sources have a dynalink, when a record changes in the parent data source, the child data source is notified about that change. The query for the child data source is reexecuted to retrieve the appropriate related data.

The following types of dynalinks are available:

Table inheritance in Microsoft Dynamics AX functions much like class inheritance in any object-orientated language. However, it has the added benefit of allowing polymorphic queries of the data in tables. (For more information about table inheritance, see Chapter 17)

If you model a form data source on a table that is a base type, the derived types are automatically expanded into a subnode called Derived Data Sources. This node is not editable and is generated by the forms engine. The derived data sources have no properties or methods of their own because all of those characteristics are inherited from the base form data source. However, you can still override and add methods to the fields for derived data sources. For example, the DirPartyTable data source, shown in Figure 6-2, is part of a table inheritance hierarchy.

Figure 6-2 shows all of the automatically-generated data sources, one for each derived type. The Fields node for each derived type lists the fields for that type. When there is only a single chain of base types, all of the base fields are collapsed into a single Fields node underneath the form data source. For example, if you model a form data source based on the DirPerson type, the Fields node contains all of the fields in the chain.

Instance methods on the form data source also follow the table inheritance hierarchy. For example, if the user triggers the validateWrite event when the current active record is of type DirPerson, the FormDataSource.validateWrite method is called, which will call DirPerson.validateWrite, which will call DirPartyTable.validateWrite, which will call the kernel level Common.validateWrite. However non-instance-specific methods such as executeQuery work on the general form data source, so there are no calls to any base methods.

Figure 6-2. The DirPartyTable data source in the AOT.

Because polymorphic queries are allowed, polymorphic creation of records is also supported. When a user clicks New on a form with a form data source that has no derived types, the concrete type to create is known. However, when the form data source has derived types, the user must be prompted to select a type to create.

Traditionally, to create a record in X++ code you only had to call the FormDataSource.create method. However, that method does not let you specify the type. To support the polymorphic creation scenario, use the following method:

FormRun.createRecord(str _formDataSourceName [, boolean _append = false])

All create actions performed by the kernel are routed through this method. You should use this method as well instead of the create method. The first parameter specifies the name of the form data source in which to create the record, and the second parameter contains the same append value that is passed to the create method. You can override this to put in conditional code that depends on the type being created. The call to the super of the method executes the correct logic depending on the type.

If the type (or any of the types in the join hierarchy) is a polymorphic type, the user is prompted to select the type of record to create, as shown in Figure 6-3.

Figure 6-3. Dialog box that prompts a user to specify a record type.

The createRecord method lets you override the behavior of the super to either specify the types of records that the user can create, or to display your own dialog box to the user. To inform the kernel of which types you want the user to choose from, you use the following method:

FormDataSource.createTypes(Map _concreteTypesToCreate [, boolean _append = false])

The first parameter contains a map of string key/value pairs where the key is the name of the form data source and the value is the name of the table type to create. For example, if your objective is to always create a type of CompanyInfo, you could use the following code. Note that the name of the form data source is the name of the data source that is modeled on the form, not the derived data source.

public void createRecord(str _formDataSourceName, boolean _append = false)
{
    Map typestoCreate = new Map(Types::String, Types::String);

    if(_formDataSourceName == "DirPartyTable")
    {
        typestoCreate.insert("DirPartyTable", "CompanyInfo");
        DirPartyTable_ds.createTypes(typestoCreate, _append);
    }
    else
    {
        super(_formDataSourceName, _append);
    }
}

Saving records in form data sources can occur in two ways. The traditional approach is that all of the inner-joined and outer-joined data sources are saved together in one process, but each record is saved to the server in individual remote procedure calls (RPCs) and transactions. This can be troublesome, because sometimes you need all of the records to be saved in a single transaction. To achieve this, you can set the ChangeGroupMode property on the Data Sources node to ImplicitInnerOuter. (The default setting is None, which results in the behavior described earlier.) With the ImplicitInnerOuter setting, all of the inner-joined and outer-joined records are grouped into a single RPC to the server and occur in a single transaction. If anything causes the transaction to be cancelled, the changes are rolled back. This feature is called Unit of Work. For more information about Unit of Work, see Chapter 17.

With this new approach, the write and delete methods no longer apply, because the actions occurred in the call to the super for those methods. With the change group mode behavior, the writing, written, deleting, and deleted methods are used. For each type of operation, when the validate method for each data source is called on the client, the methods ending in ing, such as writing, are called. The transaction then occurs on the server, where the table insert, update, or delete methods are called. Finally, the methods ending in ed or en, such as deleted or written, are called.

Unit of Work has an additional feature called OptionalRecord that saves database space by inserting outer-joined records only if the values have been changed from the default. For OptionalRecord, the two possible options are ImplicitCreate and ExplicitCreate. In the ImplicitCreate scenario, the forms engine automatically creates the outer-joined record if the record does not exist in the database. The record is saved only if values are changed from the default value. In the ExplicitCreate scenario, you can model a check box on the form that explicitly controls the behavior of record creation and deletion for the outer-joined record.

Date effectivity allows tracking of how data changes over time. The date effectivity functionality lets users with appropriate security privileges see the entire change history for a record. It also provides support for creating records that become effective on specific dates. Interest and currency conversion rates are good examples of date effective records as they make use of specific effective dates and times. For more information, see Chapter 17 or download the white paper, “Using date effective data patterns” from http://download.microsoft.com/download/4/E/3/4E36B655-568E-4D4A-B161-152B28BAAF30/Using_Date_Effective_Patterns_AX2012.pdf.

Traditional foreign keys in Microsoft Dynamics AX used the natural key or a type of intelligent key for the target object. This has many drawbacks, such as breaking referential integrity if the value of a natural key was changed. To solve those problems and improve performance through the use of integer keys, surrogate foreign key support was added to Microsoft Dynamics AX 2012. Surrogate foreign key support uses reference data sources and Reference Group controls to provide surrogate key support in the Microsoft Dynamics AX client. For more information, see the Chapter 17.

Table 6-3 describes some of the most important form data source properties.

An important change in Microsoft Dynamics AX 2012 is the addition of the FormDataSource.queryBuildDataSource method and the FormDataSource.queryRunQueryBuildDataSource methods. These methods expose the respective Query and QueryBuildDataSource objects that the forms engine uses. These methods let X++ developers quickly access the correct QueryBuildDataSource object for the form data source. This is especially helpful when a form has multiple form data sources of the same type, such as the CustTable form.

An important part of query interaction with the form is accessing the proper query to work with. For every data source on a form, there are two queries: the FormDataSource.query and the FormDataSource.queryRun.query. When a form initially loads, the Query is created in the call to the super of the FormDataSource.init method. Any modifications that you want to remain regardless of the filters that a user defines or clears should be applied to this query. In the call to the super of the executeQuery method, the QueryRun object is created, which contains a copy of the original Query object. When a user applies a filter, the filter is applied to QueryRun.query and the research method is called. An internal flag is set that specifies not to recreate the QueryRun object, and then the executeQuery method is called. When the user clears the filters, executeQuery is called, which by default, re-creates the QueryRun object from the base Query object.

CopyCallerQuery is a property for the MenuItemButton and MenuItem resources that specifies whether to copy the query from the source form to the target form. When using CopyCallerQuery, the same rules apply as when you manually assign a query through code:

In Microsoft Dynamics AX 2012, the kernel automatically adds any missing QueryBuildDataSource objects for required form data sources. This makes the queries as compatible as possible.

Forms in Microsoft Dynamics AX 2012 apply filtering through the use of QueryFilter objects instead of QueryBuildRange objects. QueryBuildRanges are applied to the ON clause in a Transact-SQL statement, which works correctly for inner joins because the ON clause and the WHERE clause provide equivalent behavior. However, this does not work as expected for outer joins. The expected behavior for data sources with outer joins is to apply the WHERE clause to restrict the entire query, instead of the ON clause, which restricts only the join. To solve this problem, the QueryFilter class was created. All of the internal kernel logic in the forms engine that modifies queries uses QueryFilter objects. It is recommended that all new X++ logic on forms use QueryFilter objects instead of QueryBuildRange objects for consistency.

For more information about query filters, see Chapter 17.

Users click buttons to perform actions. Several types of button controls are available:

You should populate the Text property for a Button or a MenuButton. However, the text for a CommandButton or a MenuItemButton should come implicitly from the referenced command or MenuItem, respectively.

You can place buttons directly on a form or within a ButtonGroup that is on a form. More commonly, buttons are placed inside an Action pane or an Action pane strip.

An Action pane (see Figure 6-5) organizes and displays buttons that represent the actions the form supports. An action is a task or operation that occurs when the user clicks a button on the Action pane. With actions, you can use data that is displayed in the current form to let users perform commands, open related forms, or execute custom X++ code.

Use an Action pane at the top of large forms when you need multiple tabs to display the actions that are available for the entire form.

Figure 6-5. An Action pane.

Use an Action pane strip at the top of smaller forms when there are a small number of actions for the form. You can define an Action pane strip by setting the ActionPane.Style property to Strip.

You can also use an Action pane strip to display actions that have a specific context. Common locations for an Action pane strip are at the top of a TabPage, FastTab, or Group control. The context might be fields of a particular category within a record or a collection of associated child records. The most common usage of a contextual Action pane strip is when displaying the Add and Remove actions above a grid that contains associated child records, as shown in Figure 6-6. When you are using an Action pane strip in a particular data context, you should set the DataSource property of the Action pane control.

Figure 6-6. An Action pane strip.

For more information about how to design Action panes, see Chapter 5.

Use the Group control to organized related fields and other controls into logical groups within a form. You can create and label a Group control manually (using the Caption property). You can also create a Group control by using the DataGroup property to point to a field group that has been predefined on a table (the data source).

Try to use table field groups whenever possible. Table field groups allow for easier maintenance of the application because a change to a table field group affects every form or report that uses that field group.

If you are manually adding controls and a caption to a Group control, be sure to provide a descriptive and understandable caption that accurately describes the group.

Use TabPage controls to reduce the complexity of a form by hiding fields until the user needs them. TabPage controls are listed within a parent Tab control. The Tab control is commonly called a tab group to differentiate it from the TabPage controls it contains.

The following styles are available for TabPage controls:

Use a Grid control to display a collection of records that are associated with the primary record on the form. For example, you could use a Grid control to display contacts or addresses for a customer.

If you do not want the Grid control to take up the entire form, you can control the size by using the VisibleRows property. For example, when displaying the addresses of a customer, many customers will only have one or two addresses. Setting VisibleRows to 3 is one way to display the relevant information while taking up minimal space.

Input controls represent the fields on a form. To create input controls that are bound to fields, you can manually add controls to the form and then bind them to fields in the data source. Another alternative is to drag fields from the data source and drop them onto the form, as in the following procedure:

If you bind an input control to a display method, you can present data that is processed or created through code. You should place display methods that relate to a particular table on that table instead of on a form data source.

When binding a control to a display method, use the Datasource and Datamethod properties to point at the appropriate display method.

Display methods use the display keyword in the method declaration. The best examples of display methods are those that already exist in Microsoft Dynamics AX. Use the search capability in the AOT to find example display methods on tables by looking for the display keyword followed by a space (display).

The standard display method format is as follows:

display SomeEDT myDisplayMethod()
{
    //Code here...
    return "returnValue";
}

You can add input controls such as StringEdit and IntEdit to a form and manipulate them through X++ code to provide the user experience you want. An example of this is seen in the AxdWizard form. Unbound controls can also be used to provide a custom filtering experience. An example of this is seen in the SalesLineBackOrder form.

To make a service available:

To make a query available: