Tutorial: Brief description of ways to close a form in AX

We had this question asked on one of the internal AX forums, and Michael Fruergaard wrote a short description of each method you can use.

Re-posting it here with some extra comments, so that new developers can read and understand, when to use what method.

There are “only” 5 ways to close a form:

• Close - close the form. Similar to the 'X' button.
• CloseOK – close the form, and set the OK flag – called by the Commandbutton::Ok
• CloseCancel – close the form, and set the Cancel flag – called by the Commandbutton::Cancel
• CloseSelectRecord – close the lookup form, and set return record
• CloseSelect – close the lookup form, and set return value

The below methods (note their names are in past-tense) are used to determine if or how a form was closed:

• Closed – Returns true, if the form is no longer open
• ClosedOK – Return true, if the form was closed by the user clicking ‘OK’
• ClosedCancel – Returns true, if the form was closed by the user clicking ‘Cancel’

Finally, CanClose() is called inside super() of any of the close methods. If CanClose() returns false, the form is not allowed to close.

Tool: DEV_SysTableBrowser and DEV_CreateNewProject tools now on AX 2009

3 or so years ago I created a couple of tools that provide extra capabilities for AX developers, specifically, ease up the creation of a new project with a predefined structure and name pattern, and add functionality to the way we browse tables with the standard SysTableBrowser, allowing to specify the exact fields you want to see, browsing temporary tables. Both tools were also available as Tabax plugins

You can read more about the tools, as well as Tabax, on the following pages on Axaptapedia:
DEV_SysTableBrowser home page on Axaptapedia
DEV_CreateNewProject home page on Axaptapedia

You can download the new versions of these tools through the pages on Axaptapedia, or directly from my SkyDrive: DEV_SysTableBrowser, DEV_CreateNewProject
If you are unfamiliar with these tools, I suggest you go through Axaptapedia, as it also contains a detailed description of the features provided.

A couple of things I would like to note:

• There is a kernel bug in AX 2009 that heavily impacts the SysTableBrowser user experience. It takes around 10 seconds each time you want to browse the contents of a specific table. This bug was fixed with a hotfix rollup 3, so users of AX 2009 without the hotfix might have problems enjoying the DEV_SysTableBrowser tool.
• In AX 2009 the behavior of SysTableBrowser changed a bit. Instead of re-opening the browser window each time the user changes from All fields to AutoGroup only, now 2 grids with these fields are added from the beginning, and hidden/shown based on user selection. DEV_SysTableBrowser provides much more flexibility when selecting the fields to display, so I was not able to follow the same approach. Thus, see bullet 1
• I have not added any new AOT nodes to the template in DEV_CreateNewProject tool (Data sets, Report Libraries, etc). I don't think AX developers will invest that much time into SSRS reports and EP, and in these cases they will be able to manually create the remaining group nodes in the project.

Let me know if you have comments, suggestions or ideas for these tools.
Thanks

Tool: User preferred startup menu for Dynamics AX 2009

In AX 2009, the user has no control over which menu is opened in the navigation pane and address bar when AX client is started. Most of the time you simply get the Home page, which is frustrating for a number of users. Another thing that is frustrating for them is the company account the application opens with. The latter can actually be setup using standard application functionality in the User options form. Just set the 'Start company accounts' to the account you want for the user by default. I wrote a small tool, that allows the user to select a preferred startup menu, ensuring that this menu is the one open every time AX client is started. Something similar existed in Axapta 3.0 application. You can download the xpo for this tool from my SkyDrive. Note, that it contains minor changes to a number of existing application objects. I suggest that you compare the xpo from the import dialog and ensure that you don't override any of your changes during import - the best thing would be to re-implement these minor changes manually. Below is a list of changes that I am referring to above:

• SysUserInfo table - 1 new field was added
• SysUserSetup form - 1 new control was added. Lookup method on datasource field overridden
• Info class - startupPost method changed

In order to enable the functionality, simply select one of the menus in the User options, as shown in the below screenshot. Next time you start AX, the selected menu will be open by default. Below is a short listing of "code patterns" used in the project, that can serve as examples for your future projects:

• SysTableLookup - for displaying a lookup form with a list of menus
• infolog.globalCache() - for storing a global reference to the navigator class
• TreeNode iteration - for finding all menu references in MainMenu
• QueryBuild classes - for constructing and filtering a list of menu references in MainMenu, used in the lookup form
• infolog.addTimeOut() method - for scheduling execution of another method in a set period of time

Tutorial: refresh, reread, research, executeQuery - which one to use?

X++ developers seem to be having a lot of trouble with these 4 datasource methods, no matter how senior they are in AX.
So I decided to make a small hands-on tutorial, demonstrating the common usage scenario for each of the methods. I have ordered the methods based on the impact on the rows being displayed in the grid.
You can download the xpo with the tutorial on my SkyDrive.

1. Common mistakes

Often, developers call 2 of the mentioned methods in the following order:
formDataSource.refresh()
formDataSource.research()
or
formDataSource.reread()
formDataSource.research()
or
formDataSource.research()
formDataSource.executeQuery()
or
formDataSource.research()
formDataSource.refresh() / formDataSource.reread()
All of these are wrong, or at least partially redundant.
Hopefully, after reading the full post, there will be no questions as to why they are wrong. Leave a comment to this post if one of them is still unclear, and I will try to explain in more detail.

2. Refresh

This method basically refreshes the data displayed in the form controls with whatever is stored in the form cache for that particular datasource record. Calling refresh() method will NOT reread the record from the database. So if changes happened to the record in another process, these will not be shown after executing refresh().

refreshEx

Does a redraw of the grid rows, depending on the optional argment for specifying the number of the record to refresh (and this means the actual row number in the grid, which is less useful for AX devs). Special argument values include -1, which means that all records will be redrawn, and -2, which redraws all marked records and records with displayOptions. Default argument value is -2.
This method should be used sparingly, in cases where multiple rows from the grid are updated, resulting in changes in their displayOptions, as an example. So you should avoid using it as a replacement for refresh(), since they actually have completely different implementations in the kernel.
Also, note, that refreshEx() only redraws the grid, so the controls not in the grid might still contain outdated values. Refresh() updates everything, since this is its intention.

3. Reread

Calling reread() will query the database and re-read the current record contents into the datasource form cache. This will not display the changes on the form until a redraw of the grid contents happens (for example, when you navigate away from the row or re-open the form).
You should not use it to refresh the form data if you have through code added or removed records. For this, you would use a different method described below.

How are these 2 methods commonly used?

Usually, when you change some values in the current record through some code (for example, when the user clicks on a button), and update the database by calling update method on the table buffer, you would want to show the user the changes that happened.
In this case, you would call reread() method to update the datasource form cache with the values from the database (this will not update the screen), and then call refresh() to actually redraw the grid and show the changes to the user.

Clicking buttons with SaveRecord == Yes

Each button has a property SaveRecord, which is by default set to Yes. Whenever you click a button, the changes you have done in the current record are saved to the database. So calling reread will not restore the original record values, as some expect. If that is the user expectation, you as a developer should set the property to No.

4. Research

Calling research() will rerun the existing form query against the database, therefore updating the list with new/removed records as well as updating all existing rows. This will honor any existing filters and sorting on the form, that were set by the user.

Research(true)

The research method starting with AX 2009 accepts an optional boolean argument _retainPosition. If you call research(true), the cursor position in the grid will be preserved after the data has been refreshed. This is an extremely useful addition, which solves most of the problems with cursor positioning (findRecord method is the alternative, but this method is very slow).

5. ExecuteQuery

Calling executeQuery() will also rerun the query and update/add/delete the rows in the grid. The difference in behavior from research is described below.
ExecuteQuery should be used if you have modified the query in your code and need to refresh the form to display the data based on the updated query.

formDataSource.queryRun().query() vs formDataSource.query()

An important thing to mention here is that the form has 2 instances of the query object - one is the original datasource query (stored in formDataSource.query()), and the other is the currently used query with any user filters applied (stored in formDataSource.queryRun().query()).
When the research method is called, a new instance of the queryRun is created, using the formDataSource.queryRun().query() as the basis. Therefore, if the user has set up some filters on the displayed data, those will be preserved.
This is useful, for example, when multiple users work with a certain form, each user has his own filters set up for displaying only relevant data, and rows get inserted into the underlying table externally (for example, through AIF).
Calling executeQuery, on the other hand, will use the original query as the basis, therefore removing any user filters.
This is a distinction that everyone should understand when using research/executeQuery methods in order to prevent possible collisions with the user filters when updating the query.

Highlighting your code on Blogger

A couple of people have now asked me for the tool that I use for pasting the source code on my blog.
In order to use the same, you will have to change the template of your blog and include the following scrips:

<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shCore.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushCpp.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushCSharp.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushSql.js' type='text/javascript'/>
<script src='http://amalafe.googlecode.com/svn/trunk/Scripts/shBrushXml.js' type='text/javascript'/>
<link href='http://amalafe.googlecode.com/svn/trunk/Styles/shCore.css' rel='stylesheet' type='text/css'/>
<link href='http://amalafe.googlecode.com/svn/trunk/Styles/shThemeDefault.css' rel='stylesheet' type='text/css'/>
<script type='text/javascript'>
SyntaxHighlighter.config.bloggerMode = true;
SyntaxHighlighter.config.clipboardSwf = 'http://amalafe.googlecode.com/svn/trunk/Scripts/clipboard.swf';
SyntaxHighlighter.all();
</script>

After that, you will be able to create code by specifying the following:

<pre class="brush: c-sharp;">
Your code goes here...
</pre>