Microsoft dynamics ax2012 : forms and tables methods call sequences, How To?

Microsoft Dynamics® AX 2012

Forms/tables methods call sequences

Objectifs

• Describe the methods call sequencing

• Describe the forms and tables methods and

when they should be override

• Describe how to access form objects

• Describe how to do some common tasks on

forms

Methods call sequencing

Cases

• Case 1: Form opening

• Case 2: Record creation

• Case 3: Field modification

• Case 4: Record saving

• Case 5: Record deletion

• Case 6: Form closing

• Case 7: RunBase

Form opening

Form Opening

Form.init• Used to retrieve and validate the calling parameters• Initialize Controls : Visibility, Enable, Editable…• Do not put code that affects DS in this method use DS.init instead

DS.init• Set Data Source properties : AllowEdit, AllowCreate, AllowDelete…• Create ranges, sorting and filters• Cache methods to improve performance• Not apply ranges values only if the ranges/links… are permanent

Form Opening

DS.linkActive• This methods is called every time we activate a new record on the

calling form• Applying links, ranges and updating design depending on the caller

record!

DS.executeQuery• Applying ranges and filters values• Avoid changing the query structure (create ranges, links…) at this

level as this method is frequently called

DS.active• Updating design depending on the selected record• Updating other Data Sources queries

Record creation

Record creation

DS.Create• Add supplementary rules to validate the creation• Modify creation process : example open a specific form for creation

DS.initValue• Only to initialize fields with values that can not exists outside of the

form, example :• Filter on the top of the form• Values coming from a calling form/class

Table.initValue• Assign a default value to fields• Always call this method when creating records by X++ code even if

the method is empty : It may be overridden in a future version!

Field modification

Field modification

Control.validate - Control.Modified• never!

DSField.validate• Validate the value typed / chosen by the user against business rules

and data consistency

DSField.modified• Modify value on other fields• Implement field modification rules

When : code we want to implement is specific to the form, or depends on some data that are only available on the form

Table.validateField, table.modifiedFieldSame as DS methods. These methods are called what ever the form.

Field modification

In modifiedField methods, you should always make sure that the code you have implemented will be cancelable if the user choose not save the changes he made. Else you have to force the saving of the record!

Incorrect :

Correct :

Field modification

Modifying a field value by X++

You should be sure the value you are assigning to the field respect

business rules, as the system will not trigger a validateField method

call automatically!

Lookup consideration

When you override the default lookup of a field to filter values that can

be chosen by the user. You should always override validateField or

validate to consider the case when the user type directly a value in the

field without using the lookup.

Record saving

Record saving

DS.validateWrite• Validate business rules and data consistency (mandatory fields filled…) that

are form specific

Table.validateWrite• Same as the DS equivalent but will be applied on all forms

DS.Write• Updating other DS in the same form• Override the normal saving process with some specific rules

Table.insert / Tables.update• Implement specific rules : CUD other record, recalculate a value…

Record saving

•When inserting/updating records by X++ code you should always call Table.validateWrite in order o validate business rules/ mandatory fields… Even if the method is empty!

•Avoid direct call to doInsert/doUpdate, as all business rules that are written in insert/update are not executed. Only use direct call if :

1. Performance issues

2. You are sure that business rules implemented in insert/update are not applicable in your use case.

Creation/update by X++ Code should be done using AxBC classes because they implement a Framework to correctly validate fields values and business rules. This will be discussed in an other session.

Record deletion

Record deletion

Delete Actions

You should always remember to implement Delete Actions when your table is

linked to other tables! Forgetting this can lead to data inconsistency.

In X++ code you should always call Table.validateDelete before calling delete

Form closing

Form closing

How to catch closing method of a form

• ClosedOk : form has been closed using OK command button

• ClosedCancel : form has been closed using a cancel command button or

Esc

• Closed : form has been closed “Normally”

Runbase

RunBase

Main• Keep the code as minimum as possible• Used to retrieve and validate calling parameters, instantiate a class objects

and initialize class object parameters

Construct • Always create a construct method to encapsulate the new Method

InitParmDefault• Use this method to default class variables/query with default values for the

first class run by the user.

HOW TO ?

How to acces form objects

• FormRun : element, this

• DataSource : DataSourceName_ds, this

• Active Record : DataSourceName

• DataSource Query : DataSourceName_q

• DataSource Query Run : DataSourceName_qr

• Field value : DataSourceName.Field

• Control

element.control(element.controlId(formControlStr(FormName, ControlName)))

Or

AutoDeclaration

General rules

• Do not place code in a form unless you cannot place it in a class or in a table method.• Code written on forms cannot be reused and is difficult to

customize.• Forms are entirely client-based. There should be no code in

them that manipulates the database.

• Always Use Field Groups in Tables

• To modify text that appears in the user interface you should modify property values on the extended data types or base enums in the application.

General rules

• If a control is linked to a field data source, You should never AutoDeclare this control. All behavior changes (visibility, mandatory, enable, …) can be done throw the data Source. Next slides shows you how you can do common tasks!

How To ?

How to enable/disable a controlIncorrect :

ControlName.enabled(true/false);

Correct :DataSourceName_ds.object(fieldnum(Table, Field)).enabled(true/false);

How to set visibility of a controlIncorrect :

ControlName.visible(true/false);

Correct :DataSourceName_ds.object(fieldnum(Table, Field)).visible(true/false);

How To ?

How to make a control editable

Incorrect :ControlName.allowEdit(true/false);

Correct :DataSourceName_ds.object(fieldnum(Table, Field)).allowEdit(true/false);

How to make a control mandatory

Incorrect :ControlName.mandatory(true/false);

Correct :DataSourceName_ds.object(fieldnum(Table, Field)).mandatory(true/false);

How to?

Assign a value to a control

IncorrectContol.text(value), control.realvalue(value), control. Checked(Value)…

CorrectDataSourceName.Field = Value;

How to?

Allow/prevent record creation/modification/deletion

Creation• Propriety : AllowCreate• X++ : DataSourceName_ds.allowCreate()

Modification• Propriety : AllowEdit• X++ : DataSourceName_ds.allowEdit()

Deletion• Propriety : AllowDelete• X++ : DataSourceName_ds.allowDelete()

NOT CORRECT

Making Buttons that allow creation/modification/deletion disabled doesn’t prevent doing

theses action. As there are shortcuts (Ctrl+N, Alt+F9…) that trigger the same events!

How to?

Cache methods (1)

Method caching mechanism helps improve performances.

DataSource_ds.cacheAddMethod(tableMethodStr(TableName, MethodName));

(1) Caching mechanism will be discussed in details in an other session.

How to?

Create/Apply range on a form DS1. Declare a variable QueryBuildRange on classDeclaration

2. Create and assign the range in DS.init() after super()

3. Apply the range value in DS.executeQuery or DS.linkActive

Add a filter control to a form (not listPage)4. Declare a Range as previous

5. Declare a variable in class Declaration with desired type

6. Create an edit method on form methods on the declared variable

7. Call the DS.executeQuery() and use the variable as a value for the range

8. Create a control on the form using the edit method

9. Optional : Save the filter value by user by overriding methods

In some cases you may have to use QueryFilter and not QueryBuildRange. See : - http://msdn.microsoft.com/en-us/library/hh745335.aspx- http://msdn.microsoft.com/en-us/library/gg881181.aspx

How to?

Add a filter control to a listPage1. Turn the “Filter” group visible = Yes

2. Add a control to the group and specify properties : Label, helpText, CK…

3. Specify properties :1. FilterDataSource : data source you want to filter

2. FilterField : field to filter based on it

3. FilterExpression : %1, !=%1, ..%1, %1..

A standard framework behind listPage will apply filter once a value is specified!

Contact me

Mohamed Amine HAMDAOUI

Email

Website

Phone+212 (0) 6 36 12 50 02

Please don’t hesitate to contact me if you find any error on the document or if you have any questions.

Thanks for your time, and see you in the next Lab!