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.modifiedField
Same 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 control

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

How to set visibility of a control

Incorrect :
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

Incorrect
Contol.text(value), control.realvalue(value), control. Checked(Value)…
Correct
DataSourceName.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 DS

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

1. Declare a Range as previous
2. Declare a variable in class Declaration with desired type
3. Create an edit method on form methods on the declared variable
4. Call the DS.executeQuery() and use the variable as a value for the range
5. Create a control on the form using the edit method
6. 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 listPage

1. 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

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

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