Microsoft Dynamics AX 2009 : Browsing for folders

Folder browsing lookups are used when the user is required to specify a local or network folder for storing or retrieving Dynamics AX data. In this recipe, we will see how such lookups could be built using various techniques.

As an example, we will create a new control called Documents in the Ledger parameters form, which will store a folder path.

How to do it...

1. 1. Open the LedgerParameters table in AOT, and create a new field:

   Property	Value
   Type	String
   Name	DocumentPath
   ExtendedDataType	FilePath
   Label	Documents

   
   

2. 2. Add the newly created field to the bottom of the General field group.

3. 3. Open LedgerParameters form in AOT, and create the following method:

   str filePathLookupTitle()
   
   {
   return "Select document folder";
   }
   

4. 4. To check the results, open General ledger | Setup | Parameters, and notice that now it has a new control Documents, which allows you to select a folder:

How it works...

The folder browsing lookup is bound to the FilePath extended data type, and it appears automatically near every control that is based on that type. In this recipe, we add a new DocumentPath field, which extends FilePath and consequently inherits the lookup.

We also add the DocumentPath field to the General field group in order for it to appear on the form automatically.

Browsing for folder lookup requires the filePathLookupTitle() method on a caller form. This method returns a lookup description text. Dynamics AX will show an error, if this method is not present on a caller.

There's more...

In this section, we will explore other enhancements to the previous example. Firstly, we will build exactly the same lookup but using different approach and secondly, we will enable Make New Folder button on the lookup.

Manual folder browsing lookup

The described technique works fine in most cases. But personally, I prefer the other way of creating such lookups for two main reasons.

First is that standard folder browsing lookup requires the filePathLookupTitle() method to be present on a caller form. The name of this method has to be exactly like this and cannot be prefixed with a three letter code, as per best practice recommendations, and it might lead to confusions when performing system changes in the future.

Another reason is that a single form cannot have two or more folder browsing lookups unless they share the same description. Every lookup calls the same filePathLookupTitle() and will obviously have the same descriptions.

The standard browse-for-folder lookup form internally uses WinAPI::browseForPath() to invoke the standard Windows folder browsing dialog. We can reuse this method to create a folder browsing lookup manually.

We have to modify our previous example by deleting filePathLookupTitle() from the LedgerParameters form and overriding the lookup() method of the DocumentPath field in the LedgerParameters form data source:

public void lookup(FormControl _formControl, str _filterStr)

{
FilePath path;
;
path = WinAPI::browseForPath(
element.hWnd(),
"Select document folder extended");
LedgerParameters.DocumentPath = path;
LedgerParameters_ds.refresh();
}

Now, if you open the lookup, you may notice that it looks exactly the same as before apart from its description. Using this technique, we can create more than one folder browsing lookup on the same form without adding additional methods to the form itself.

Adding a Make New Folder button

Standard Dynamics AX contains one more WinAPI method called browseForFolderDialog(). Besides selecting a folder, it allows us to create a new one. It accepts three optional arguments:

1. 1. The lookup description.

2. 2. The preselected folder path.

3. 3. true to show and false to hide the Make New Folder button. This button is shown by default, if this argument is omitted.

Let's override the lookup() method of the DocumentPath field in the LedgerParameters form data source with:

public void lookup(FormControl _formControl, str _filterStr)

{
FilePath path;
;
path = WinAPI::browseForFolderDialog(
"Select document folder extended",
LedgerParameters.DocumentPath,
true);
LedgerParameters.DocumentPath = path;
LedgerParameters_ds.refresh();
}

Note that now, the folder browsing lookup has a Make New Folder button, which allows the user to create a new folder straight away: