AX 2012 Forms/tables methods call sequences

AX 2012 Forms/tables methods call sequences

========================================================================
2. 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
3. Methods call sequencing
4. 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
5. Form opening
6. 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
7. 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
8. Record creation
9. 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!
10. Field modification
11. 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.
12. 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 :
13. 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.
14. Record saving
15. 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…
16. 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. 2. Performance issues 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.
17. Record deletion
18. 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
19. Form closing
20. 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”
21. Runbase
22. 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.
23. HOW TO ?
24. 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
25. 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.
26. 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!
27. 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);
28. 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);
29. How to? Assign a value to a control Incorrect Contol.text(value), control.realvalue(value), control. Checked(Value)… Correct DataSourceName.Field = Value;
30. How to? Allow/prevent record creation/modification/deletion Creation • • Propriety X++ : AllowCreate : DataSourceName_ds.allowCreate() Modification • • Propriety X++ : AllowEdit : DataSourceName_ds.allowEdit() Deletion • • Propriety X++ : AllowDelete : 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!
31. 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.
32. How to? Create/Apply range on a form DS 1. 2. 3. Declare a variable QueryBuildRange on classDeclaration Create and assign the range in DS.init() after super() Apply the range value in DS.executeQuery or DS.linkActive Add a filter control to a form (not listPage) 1. 2. 3. 4. 5. 6. Declare a Range as previous Declare a variable in class Declaration with desired type Create an edit method on form methods on the declared variable Call the DS.executeQuery() and use the variable as a value for the range Create a control on the form using the edit method 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
33. How to? Add a filter control to a listPage 1. 2. 3. Turn the “Filter” group visible = Yes Add a control to the group and specify properties : Label, helpText, CK… Specify properties : 1. 2. 3. FilterDataSource : data source you want to filter FilterField : field to filter based on it FilterExpression : %1, !=%1, ..%1, %1.. A standard framework behind listPage will apply filter once a value is specified!