Dynamics Anywhere Framework

Developer's Guide

Version

2.0.0.0

Document title: Document type: Author Publish date File name Version

: : : : : :

Dynamics Anywhere Framework Developer's Guide

J. Holland 20-1-2010 DG-DAW-2010-01-20.Framework_Development_Guide.v2.0.0.0.docx 2.0.0.0

Dynamics Anywhere Nieuwe Bosweg 10 3341 LH Hendrik-Ido-Ambacht The Netherlands Telephone: +31 78 68 11 234 Mail address: [email protected] Internet: www.dynamicsanywhere.com

2010 Dynamics Anywhere. All rights reserved. The information in this document is confidential, constitutes the intellectual and proprietary property of Dynamics Anywhere, and is protected by intellectual property laws and international intellectual property treaties. The names of actual companies and products mentioned herein may be the trademarks of their respective owners. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Dynamics Anywhere. The information contained in this document is subject to change without notice. Dynamics Anywhere does not warrant that the information contained in this document is error free.

Table of contents
1. INTRODUCTION ........................................................................................................................................................ 1

1.1 1.2 1.3

2.

WHO SHOULD READ THIS GUIDE? .................................................................................................. 1 WHAT IS DISCUSSED IN THIS GUIDE? ............................................................................................... 1 NEW IN THIS VERSION ................................................................................................................... 1 INTRODUCTION ............................................................................................................................ 2 THE FRAMEWORK WITHIN AX ........................................................................................................ 3 ON SESSIONS ............................................................................................................................... 4

FRAMEWORK OVERVIEW ......................................................................................................................................... 2

2.1 2.2 2.3

3.

THE DESIGNER .......................................................................................................................................................... 5

3.1 THE APPLICATION CONFIGURATION TAB .......................................................................................... 5 3.1.1 Application object layer within framework data ............................................................. 6 3.1.2 Application properties ..................................................................................................... 6 3.1.3 Menu properties .............................................................................................................. 6 3.1.4 Label properties ............................................................................................................... 6 3.2 THE FORM CONFIGURATION TAB .................................................................................................... 7 3.2.1 Form properties ............................................................................................................... 8 3.2.2 User controls .................................................................................................................... 8 3.2.3 Properties overview ......................................................................................................... 8 3.2.4 Data grid column configuration..................................................................................... 10 3.2.5 Button actions................................................................................................................ 11 3.2.6 Variables ........................................................................................................................ 12 3.3 GENERAL TAB ............................................................................................................................ 13
4. A CASE: HELLO WORLD PART 1 ............................................................................................................................... 14

4.1 CREATING A NEW APPLICATION..................................................................................................... 14 4.2 ADDING FORMS TO YOUR APPLICATION .......................................................................................... 15 4.2.1 Configuring the hello world form................................................................................... 15 4.2.2 Configuring the logout form .......................................................................................... 17 4.3 TESTING THE APPLICATION ........................................................................................................... 19
5. CUSTOMIZING THE GENERATED APPLICATION AND FORM CLASSES ....................................................................... 22

5.1 INTRODUCTION .......................................................................................................................... 22 5.2 RESPONDING TO USER SUBMITS (BUTTON AND KEY PRESSES) ............................................................. 23 5.3 INITIALIZING OBJECTS WHEN THE FORM LOADS ................................................................................ 24 5.4 RESPONDING TO USER INPUT FROM A PREVIOUS FORM ..................................................................... 24 5.5 AN OVERVIEW OF OTHER FORM EVENT METHODS ............................................................................ 25 5.5.1 OnControlCheckedChanged ........................................................................................... 25 5.5.2 OnControlSelectedIndexChanged .................................................................................. 25 5.5.3 OnControlTextChanged ................................................................................................. 25 5.5.4 OnDeactivate ................................................................................................................. 25 5.5.5 OnInit ............................................................................................................................. 25 5.6 AN OVERVIEW OF APPLICATION EVENT METHODS............................................................................. 25 5.6.1 Onload ........................................................................................................................... 25 5.6.2 OnLogoff ........................................................................................................................ 25 5.6.3 OnMenuSelect................................................................................................................ 26 5.7 RESPONDING TO EVENTS IN GENERAL, CALLING EVENT METHODS EXPLICITLY FROM CODE ....................... 26
6. A CASE: GETTING SOME ITEM INFORMATION ......................................................................................................... 27

6.1

ADDING THE FORMS IN THE DESIGNER............................................................................................ 27

6.2 6.3 6.4

7.

CREATE A FORM THAT DISPLAYS THE RESULT ................................................................................... 29 ADDING SOME CUSTOM CODE TO YOUR APPLICATION ....................................................................... 31 TESTING YOUR MODIFICATIONS .................................................................................................... 32

THE TRANSACTION LOG .......................................................................................................................................... 33

7.1 INTRODUCTION .......................................................................................................................... 33 7.2 CLEANING UP THE TRANSACTION LOG ............................................................................................ 33 7.3 DEBUGGING THE APPLICATION...................................................................................................... 34 7.3.1 Notes on application state ............................................................................................. 34 7.3.2 Breaking your code with a throw so you can debug...................................................... 34 7.3.3 Debugging your code ..................................................................................................... 36
8. A CASE: SHOWING INFORMATION IN A DATA GRID ................................................................................................ 38

8.1 8.2 8.3 8.4 8.5

9.

ADDING A NEW FORM TO THE DESIGNER ........................................................................................ 38 ADDING CODE TO LOOK UP THE ITEM ............................................................................................. 40 SETTING UP THE DATA GRID ......................................................................................................... 41 NAVIGATE TO THE NEW FORM ...................................................................................................... 42 TEST THE MODIFICATION ............................................................................................................. 43

MANIPULATING THE FRAMEWORK THROUGH CODE .............................................................................................. 44

9.1 METHODS OF THE APPLICATION CLASS ........................................................................................... 44 9.1.1 About the application class............................................................................................ 44 9.1.2 Getters for form classes ................................................................................................. 44 9.1.3 Getters/setters for variables .......................................................................................... 44 9.1.4 FindLabel ........................................................................................................................ 44 9.1.5 GetDeviceTypeId ............................................................................................................ 44 9.1.6 GetHostname and GetUserId ......................................................................................... 44 9.1.7 GetLanguageId .............................................................................................................. 44 9.1.8 Get/SetMainParam and Get/SetMainParamContainer ................................................ 44 9.1.9 Logoff ............................................................................................................................. 44 9.1.10 ReturnFromForm ........................................................................................................... 45 9.1.11 ShowFormByInstanceId and ShowFormByConfigId ....................................................... 45 9.1.12 ShowMainMenu............................................................................................................. 45 9.2 METHODS OF THE FORM CLASS ..................................................................................................... 45 9.2.1 About the form class ...................................................................................................... 45 9.2.2 Getters for user control classes ..................................................................................... 45 9.2.3 Getters/setters for variables .......................................................................................... 45 9.2.4 Get/SetFormParam and Get/SetFormParamContainer................................................. 45 9.2.5 GetHostname and GetUserId ......................................................................................... 45 9.2.6 Get/SetMainParam and Get/SetMainParamContainer ................................................ 46 9.2.7 IsReturnedFromForm ..................................................................................................... 46 9.2.8 PerformButtonNavigation ............................................................................................. 46 9.2.9 ReturnFromForm ........................................................................................................... 46 9.2.10 ShowForm ...................................................................................................................... 46 9.3 METHODS OF USER CONTROL CLASSES ........................................................................................... 46 9.3.1 About the user control classes ....................................................................................... 46 9.3.2 BoundDataCount (data grids only) ................................................................................ 46 9.3.3 BoundDataContainsField (data grids only) .................................................................... 47 9.3.4 Checked (checkbox only) ................................................................................................ 47 9.3.5 ClearBoundData (data grids only) ................................................................................. 47 9.3.6 FillFromList (data grids only) ......................................................................................... 47 9.3.7 FillFromQuery (deprecated) ........................................................................................... 47 9.3.8 GetBoundData, GetBoundDataStruct (data grids only) ................................................ 47

9.3.9 9.3.10 9.3.11 9.3.12 9.3.13

10.

HasFocus and SetFocus .................................................................................................. 47 IsSubmitTarget (buttons only) ....................................................................................... 47 ListFields (data grids only) ............................................................................................. 47 SelectedIndex (data grids only)...................................................................................... 47 Text ................................................................................................................................ 47

A CASE: REACTING TO RETURN FROM FORM RESULT VALUES ......................................................................... 48

10.1 10.2
11.

AUTOMATICALLY CONTINUE AFTER SELECTING AN ITEM FROM THE LIST................................................ 48 ADDING CODE TO THE ONREACTIVATE METHOD .............................................................................. 48
SESSIONS AND SETUP......................................................................................................................................... 50

11.1 11.2 11.3

12.

ACTIVE SESSIONS FORM .............................................................................................................. 50 TRANSFERRING SESSIONS TO ANOTHER DEVICE ............................................................................... 50 FRAMEWORK PARAMETERS ......................................................................................................... 51
NOTES ................................................................................................................................................................ 52

1. Introduction
This guide explains how the Dynamics Anywhere Framework for Dynamics AX works, and how a developer can use it to create or modify a mobile application for the framework.

1.1 Who Should Read This Guide?

This guide is aimed at developers planning to create or modify a mobile application, or consultants planning to make minor modifications to existing mobile applications. A good general knowledge of dynamics AX, as well as the development environment and X++ syntax is required.

1.2 What is discussed in This Guide?

The following subjects are discussed in this document: An overview of the Framework The framework data model Creating or modifying a framework application Configuring behavior and navigation Events and the application and forms classes Adding validation and registration to submits Fine tuning navigation and mobile application behavior from code Creating pop-up style dialogs Filling grids and selecting data

1.3 New in this version

This document has been revised to reflect the changes made to the framework for R2. The hands-on assignments have also been updated, and a section on active sessions and parameters has been added.

Dynamics Anywhere Framework Developer's Guide

2. Framework overview
2.1 Introduction
Central to the Dynamics Anywhere Framework is the Dynamics Anywhere Portal. Utilizing Dynamics AX Business Connector technology to connect to Dynamics AX, the Dynamics Anywhere Portal carries Dynamics AX into the mobile world. Designed specifically to work flawless with any mobile device, the Dynamics Anywhere Portal presents the user with an attractive, fast and reliable user interface. In addition, the user interface is designed to make the most of the mobile device, providing a clutter free view of the application and making full use of additional resources like barcode scanners and RF tag readers to improve user productivity. The following figure shows the overall architecture and the components that constitute the Dynamics Anywhere Mobile Business Solution:

AOS

Microsoft Dynamics AX .NET Business Connector

DAWFW Mobile Portal

HTML

XML

DAWFW Webservice

DAW Application repository

DAW / Application User interface

DAW FrameWork

Microsoft Dynamics AX Functionality

PDA

Many mobile devices have a limited implementation of their web browser due to their design and configuration, making ordinary HTML based solutions unsuitable for use on a mobile device. The Dynamics Anywhere Framework will run on any device with a browser, and fully supports using multiple device types and form factors simultaneously. The system and hardware requirements for each component must be met before installing. When you have determined that your host environment meets the requirements that are provided in the following topics, proceed to the appropriate installation section. This guide deals mostly with configuring and modifying applications built within the Dynamics Anywhere Framework. For details on installation and configuration of the Portal, Web service and Framework in AX, please refer to the Installation Guide.

Dynamics Anywhere Framework Developer's Guide

2.2 The Framework within AX

The Framework in Dynamics AX consists of two parts. The first part is the user interface, which exists as data in Dynamics AX tables. The second part consists of additional extensions on the classes that are generated automatically by the framework when the user interface is designed. These extensions are used to interface with Dynamics AX business logic, allowing the developer to validate or query data, call Dynamics AX objects to perform registrations, etc.

Business Logic (X++) AX business logic AX business logic Custom extension Application Application to Extended Extended application Custom Form extension Form Extended to form Extended

AX Database

AX business logic AX data

Dynamics Anywhere FW

UI Config and default properties Application Application Application Form Form Form UI UI UI Element Element Element

Form and UI element properties

User action Event Handler New screen Session Session

Application and form vars

UI element bound data

Shown above is a diagram showing how the different parts work together, and how the framework interacts with the rest of AX. User actions are received from the Portal (using the Dynamics AX Business Connector). The event handler looks up the session that goes with the user/device (or instantiates a new one if the user is logging in), and passes the event on to the Application or Form objects (for instance, a user scanning a barcode in a textbox would result in a submit event being called on the form class object). Classes are generated automatically for forms and application by the framework whenever an application or form is added to the framework using the user interface designer, and are specific for that application or form. As these classes exist in the AOT of AX, custom extensions of those classes allow the developer to validate user input, register data, or call other AX business logic. Furthermore, since most user interface objects created when designing the user interface of the application will have a generated representation in the AOT, it is impossible to accidently reference an object that does not exist, and developer tools like code completion help to quickly add and customize the mobile application.

Dynamics Anywhere Framework Developer's Guide

2.3 On sessions
Whenever a user logs on to the framework, a session is created for this user/device. The framework creates this session using the configured application. The session represents the running instance of the application blueprint. The data stored in the user controls and associated variables are specific to this session, and separated from other sessions of other users that may be running simultaneously. Storing this data in tables in AX instead of as part of the web session makes sessions state persistent. If a device resets, or the web session is lost, or even the business connector session, the application state will be preserved, and upon logging in, the application will continue where it left off.

Dynamics Anywhere Framework Developer's Guide

3. The designer
Developers can use the designer to create or modify the user interface of a mobile application for the Dynamics Anywhere Framework, and to design some behavior and navigation for the application. You can find the designer by selecting DAW Framework from the main menu of Dynamics AX, and then selecting Application Configuration. Most tables shown in the designer display a column called Application Object Layer. Records are stored with this column set to the current AOL, and you can only modify records that are set to the current AOL. If the record is set in a different AOL, editing the record will create a copy of the record with the AOL set to the current layer. When rendering the user interface, the framework will use the topmost AOL version of the record, so multiple parties can work on the user interface in the same way they would on application objects in AX. The designer window has three tabs, called Application Configuration, Form Configuration and General.

3.1 The Application Configuration Tab

Applications Records in the Application Configuration mimic the AX layer system.

The menus configured for the selected application

Multi language labels in the selected application

This tab contains a list of the applications configured in the framework, and below that the menu configured for the selected application and the labels created. Labels can be used on many objects in the framework, and allow the developer to create a single reference to text that can be in several languages, and may be formatted for several

Dynamics Anywhere Framework Developer's Guide

devices (with abbreviations for devices with small screens, and verbose texts for devices with large screens). Whenever an application is created in the designer by adding a record to the Application Configuration grid, a project called D2MFW_<project name> is automatically created in the AOT, together with a class named <project name>Main. As forms are added to the mobile application, automatically generated classes for these forms are also added to this project.

3.1.1 Application object layer within framework data

Records in the Application Configuration mimic the AX layer system. If you make a modification within the designer, this modification will appear in the current application object layer. Keeping your modifications in a separate layer makes importing updates much easier, as the updates will not interfere with the modifications you made in the designer.

3.1.2 Application properties

Property Description ApplicationConfigId Uniquely identifies the application MenuId Main menu used by the application TitleLabel An optional label with the application title (shows up above the menu) Note: without a menu configured, the application will not display properly. Make sure youve defined a menu with at least one option, and reference this menu in the application properties.

3.1.3 Menu properties

Property Description MenuId Uniquely identifies a menu (which can contain multiple lines) Linenum Line number Jump go Form Reference to the form launched by selecting this menu option Jump to Menu Reference to a submenu Jump to Application Reference to another application LabelId Id of the label to be displayed for this menu item Process Id Checked against authorized processes for the user logging in Note: If a user is not authorized for the specified process id, the menu option is not displayed.

3.1.4 Label properties

Property Label id Devicetype Id Language Id Text Description Uniquely identifies a text label (for multiple languages/devices) Device type Language Text to display on the specified device in specified language.

Dynamics Anywhere Framework Developer's Guide

Note:

Note:

Each label should at least have an entry for en-us, as this is the language the framework uses when a label in the language of the user cannot be found. If the enus label is missing in this case, the framework could behave erratically or crash. A dropdown allows you to select an AX sys label for the Text property. If you use AX sys labels you only have to provide an entry for en-us, it will be translated to the user language automatically.

3.2 The Form Configuration Tab

Forms within the selected application Global variables available throughout the selected application

User interface elements on the selected form

Properties for this user control (varies depending on control type)

Variables can be linked to controls

Properties that may vary for different device types

Local variables on the selected form

This tab contains the forms in the selected application, as well as the global variables that are available throughout the application and local variables that are linked to a specific form. Whenever a form is created, a class named <application name><form name> will be created in the application project in the AOT. Forms contain user interface elements (user controls), as well as local variables that are available through the form class.

Dynamics Anywhere Framework Developer's Guide

3.2.1 Form properties

Property Sort order Form config id Title label id Default button Description Order in which forms are displayed on this screen Uniquely identifies the form in the application Reference to the label shown as the form title Button that is activated when the user presses the enter key

3.2.2 User controls

Currently, the user controls available are labels, textboxes, buttons, checkboxes, data grids and literal HTML texts, with several more planned to be implemented in the near future. Property Control Config Id Control Type Taborder Description Uniquely identifies a control on a form Control Type Order in which controls are shown on the form

User control properties for the selected user control are displayed below the control configuration grid, and can be modified. Only the properties appropriate for the control type are displayed.

3.2.3 Properties overview

Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description: Append colon Label Append a colon after the text Append newline Label, Textbox, Button, Grid, Literal HTML, Checkbox Append a line break after the control Button action Button Action to perform when button is selected Button action form id Button When the button action performs navigation to a form, this contains the id of that form Checked Checkbox Checked property Clear on load Label, Textbox, Grid, Checkbox Clears the control value upon loading the form (see 5.3)
Dynamics Anywhere Framework Developer's Guide

Property: Applies to: Description: Property: Applies to: Description:

Property: Applies to: Description: Property: Applies to: Description:

Clear on reactivate Label, Textbox, Grid, Checkbox Clears the control value upon reactivating the form (see 5.4) Data grid select Button When a grid is present on the form, this causes the data of the selected row on the grid to be copied to any variables linked to the columns Get caption from EDT Label, Textbox Gets and displays a caption for the label or textbox from the extended data type of the linked variable Hotkey Button Hotkey (function key) linked to control Include hotkey in caption Button Show hotkey in caption (e.g. F1: Back) Label id Label, Textbox, Button, Checkbox Reference to the label show as text with the control Linked variable Label, Textbox, Button, Grid, Checkbox Name of the variable linked to the value of the control Linked variable form id Label, Textbox, Button, Grid, Checkbox Either empty (for a global type variable), or the id of the current form (for a local type variable) Read-only Label, Textbox, Button, Grid, Checkbox Read-only controls show up greyed out Required Textbox When a button with the validate textbox property set is pressed, all textboxes with the required property set must have data, otherwise an error is displayed. Selected index Grid Selected index

Property: Applies to: Description:

Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description:

Property: Applies to: Description: Property: Applies to: Description:

Property: Applies to: Description:

Dynamics Anywhere Framework Developer's Guide

Property: Applies to: Description: Property: Applies to: Description: Property: Applies to: Description:

Text Label, Textbox, Button, Literal HTML, Checkbox Literal text to use instead of a label (you can use AX sys labels here) Validate textbox Button See Required Visible Label, Textbox, Button, Grid, Checkbox Visible property (invisible controls are not show)

3.2.4 Data grid column configuration

For data grids, an additional grid is shown allowing the developer to define the columns to be displayed in the data grid, as well as create a mapping to variables. Please refer to chapter 8 for an example of how to link data to a data grid.

Property: Description:

Grid column Order of the column within the grid. Make sure the numbers are consecutive (no numbers are skipped). Label id Reference to label shown in header of the column. Column width Width in pixels of the column. Use a width of 0 to hide the column. Query result list If a result list is used to populate the grid, this references the struct field used for this column. Linked variable Name of the variable linked to the value of this column. Linked variable form id Either empty for a global type variable, or the id of this form for a local type variable.

Property: Description: Property: Description: Property: Description:

Property: Description: Property: Description:

Creating a column definition for a data grid is not required. If the developer doesnt provide one, all of the columns in the data linked to the data grid are displayed.
Dynamics Anywhere Framework Developer's Guide

10

3.2.5 Button actions

Button actions are used to configure navigation through the forms, creating a workflow.

Button actions are performed by the framework when calling the onSubmit method of the form class. If you want to prevent the execution of the button action in certain cases (for instance if a validation fails), override the "onSubmit method of the form, and prevent the call to the super method (by either returning before it is called, or throwing an error). None/Custom This button action is used when some custom action is performed (for instance calling some AX business logic) without the need to navigate to another form. Main menu This button action causes the application to return to the main menu, regardless of whether there are other forms on the form stack or not. Logout This button action causes the application to return to the main menu, regardless of whether there are other forms on the form stack or not. Show form (create always) This causes the current form to be placed on the form stack, and a new form (specified in the button action form id) to be designated as the new current form. If no instance exists of the form, it is created. A single instance of a form can be added to the form stack multiple times, so take care when using this button action Show form (create or return) This button action does almost the same as Showform (create always), with one exception; if the new form (specified in the button action form id) is already available in the form stack, all forms above it on the stack are removed, and the new form is designated as the new current form. This is especially useful when the application has to loop a sequence of forms many times (for instance, when performing an item pick).
Dynamics Anywhere Framework Developer's Guide

11

Return from form This button action, which exists in several variants (OK, Cancel, Yes, No, etc.), pops the top most form from the form stack and makes it the new current form, in effect exiting the current form and returning to the previous one. When the previous form is reactivated in this way, the onReactivate method on the form class is called. The value shown in parenthesis corresponds to a parameter passed to this method, allowing the developer to evaluate it and take some appropriate action. Use this button action to create pop-up style forms, for instance when you need a pop-up where the operator answers yes or no in response to some situation. See 5.4 for an example.

3.2.6 Variables
Variables are used to store data in your session. Each session has its own personal set of variables, which other sessions have no access to.

Uniquely identifies this variable.

Associated AX extended data type.

Default value.

Variables can be either global or local. Global variables are available through the generated class for the application (named <application name>Main), and local variables are available through the generated class for the form (named <application name><form name>). User controls may be linked to variables (either of the global or local variety, with the restriction that they are on the same form for the latter). Variable linked to control

When displayed, the data of the variable is automatically used as the value for the user control. When the value of the user control is modified by the user, the modified value is automatically stored in the variable. The base type of the variable should be appropriate for the user control it is linked to (for instance, a date type variable may be linked to a textbox, but not to a checkbox.

12

Dynamics Anywhere Framework Developer's Guide

Control Type Checkbox Data grid Textbox or label Grid column

Allowed Base Type Enum (of type NoYesId) Interger, Int64 Date, Guid, Integer, Int64, Real, String, Time, Enum Type should be compatible with the data displayed

Linked property Checked SelectedIndex Text n.a.

Variables may also be linked to grid columns. When the user presses a button that has the data grid select property set, the data in the column of the selected row of the data grid is copied to the linked variable.

3.3 General tab

Definition of available devices along with their resolution

Definition of available fonts

On this tab, device types can be defined, as well as the fonts used in the mobile application. These settings are for all applications, not just the selected one. Whenever anything is configured for several device types, (such as labels, or the fonts configured for controls, or the number of lines for a data grid) the framework will consider the screen resolution of the used mobile device, and choose the setting for the device type that matches that of the used device, or is the next smallest, or failing that, the next largest. This ensures that the best possible configuration is selected for the used device.

Dynamics Anywhere Framework Developer's Guide

13

4. A case: Hello World part 1

This section details the creation of a small hello world application. Youll need to use the training VPC for this. Log in using DYNANYDMO\administrator, with password pass@word1.

4.1 Creating a new application

1. 2. 3. 4. Start with opening the designer and create a new application called Hello World. Then Select the new application, and create some labels1, as seen in the example below. After this, create the entries for the main menu, also shown below. Finally, set the main menu property and title label of the application.

The result should look something like this:

1. Create the application (leave menu id and title label empty).

4. Set the main menu and title label.

2. Create the labels.

3. Create the menu items.

Please note, we are using AX syslabels in this example out of convenience, were not indicating that as a rule, you should too, as arguments can be made for and against using the syslabels provided by AX.

Try to create the labels for all languages you wish to support from the start. However, always create at least an entry for en-us for each label you create.
Dynamics Anywhere Framework Developer's Guide

14

4.2 Adding forms to your application

Next, well be adding two new forms to our application, called HelloWorld and LogOff. Go to the tab Form Config and create both forms. Also set the Title Label Id properties to the appropriate values.

4.2.1 Configuring the hello world form

You can use this number to sort your forms in this grid.

Next, select the first form, and add a new user control called LblHelloWorld. Set the properties as in the example below.

Inserts a line break after the control

Dynamics Anywhere Framework Developer's Guide

15

Add a user control of type Literal HTML, called LitHorizontalLine. Set control type to Literal HTML and save (^S) to update the shown properties. Then, set the properties as in the sample below2. Please note, once you save a record you cant change name or type anymore. Dont forget to select the control type.

Literal HTML tags need to be XHTML (conform to XML). Finally, add a user control of the type button named BtnOk (dont forget to set the control type before saving), and set the properties as in the sample below. Use tab order to set the order in which controls show up in your form.

Causes the form to exit when pressed. We now have a form that displays a single fixed line of text, and has a button that exits the form.

Only properties appropriate to the control are show. If you dont see the properties change, save your record, reselect the record or refresh the screen.
Dynamics Anywhere Framework Developer's Guide

16

4.2.2 Configuring the logout form

Next, select the form configuration grid and press F5 to refresh it. Default button will show up after you press F5.

Then, select the form LogOut, and add a label control named AreYouSure to it, set the properties as shown below.

Add a literal HTML control named LitHorizontalLine, and set the properties like this.

Dynamics Anywhere Framework Developer's Guide

17

Add a button, named BtnNo.

And one named BtnYes.

Logs the user out when pressed. Now, well change the default button for the logoff form to BtnYes. Youll notice you get an error stating the values displayed in the form are not current. This is because the framework sets the default button value to the first button you add to the form in the background. Press F5 to refresh the screen, and then change the default button value for the logoff form to BtnYes.

Press F5 to refresh before you set this value.

18

Dynamics Anywhere Framework Developer's Guide

Finally, we need to set up the main menu to open the forms we just added. Go back to the tab Application Configuration, go to the main menu, and select the forms added in the form config id property of the menu items.

4.3 Testing the application

Now were ready to test our little hello world. Go to the users tab under the DAW Framework menu option in AX, and set the application for one of the users.

If youre creating a new user, dont forget to go to the Employee/Roles form and select a role for the user, and save the record, or the user may not be able to use the application correctly.

Dynamics Anywhere Framework Developer's Guide

19

Now, start the browser (use the PDA option on the desktop of the training VPC) and log in using the user name and password configured in the user form.

You can do this by printing the operator badge and scanning it into the login field (from the DAW Users form, select one or more users, and then select print operator badge).

As you probably dont have a barcode scanner available, you can also manually enter the user name, followed by the / character, and finally the password (for user 1000 in our example, use 1000/123). If you find you have trouble logging in, check if youre using the correct user name and password. Also, when using VPC with a non US keyboard, some characters show up under different keys so make sure youre not accidently entering a character other than the / character as the separator character (open up notepad to test this if you are not sure).

20

Dynamics Anywhere Framework Developer's Guide

You now see the main menu (it may look slightly different depending on the type of browser youre using).

Select the hello world option from the main menu.

Select OK to go back to the main menu, and from there select the menu option Log off.

Select Yes to log off.

Dynamics Anywhere Framework Developer's Guide

21

5. Customizing the generated application and form classes

5.1 Introduction
For each application and form added during the design of the user interface, a class is automatically generated in the AOT. These classes have two purposes. First of all, they are a means of customizing and fine tuning the application designed in the designer, by overriding methods and adding code that responds to user events. Secondly, they serve to create a presence in X++ of the varying user interface elements created in the designer. The classes for applications are generated with the name <application name>Main. The classes for forms are generated with the name <application name><form name>. Both can be found in a generated shared project named D2MFW_<application name>. Do not rename these classes or projects, as this might cause problems executing the mobile application.

Looking at the sample shown above, you can see that for each form in the application, a getter function (get<form name>) is added to the application class, and for each global type variable, a getter/setter (var<variable name>) is added. On the form classes, each user control gets a getter function (get<user control name>), and any local type variable also gets a getter/setter (var<variable name>). Finally, each form also gets a getMain function, which returns the application class for that form.

22

Dynamics Anywhere Framework Developer's Guide

5.2 Responding to user submits (button and key presses)

The most common event to override is the submit event, which is fired whenever the user submits data (presses a button, scans a barcode or enters a number). To override this event, find the class for the form on which you want to add some custom code in response to a user event, and override the method onSubmit. When adding custom code, make sure you first check if you are responding to the right submit, by checking the submit target. In the sample below, the submitted data (an item id) is checked to see if an item with this id exists, and its name is stored in a variable if it exists. Please note, submits may not always be the result of a button press (it may also be caused by a refresh or a wake up), so make sure you always check the pressed button before calling business logic.
public D2MFWEventHandleResult onFormSubmit(D2MFWControlInstanceID _submitTargetID) { D2MFWEventHandleResult ret; InventTable inventTable; ; // button OK pressed if(this.getBtnOk().isSubmitTarget(_submitTargetId)) { // nothing was entered if(this.getMain().varItemId() == "") return D2MFWEventHandleResult::OK; // find the item in the database inventTable = InventTable::find(this.getMain().varItemId()); if(!inventTable) // no data found throw error ("unknown item!"); // store name of found item in variable this.getMain().varItemName(inventTable.itemName); } ret = super(_submitTargetID); return ret; }

This example has a couple of interesting things to point out. First of all, the custom code is only executed when the OK button was submitted. This is very important, if you do not check the submit target the custom code will be executed on each submit, even simple screen refreshes. You can check if a submit event is caused by a certain user control (nearly always a button) by feeding the _submitTargetId parameter to the isSubmitTarget method of the control. Another interesting point to make is the use of throw error. The text provided with this throw will be shown to the user. In addition, the throw prevents the call to the super method, which might have caused the application to navigate to another form. Finally, the throw rolls back any updates in the current transaction, which means that when the user sees the form with the error message, the application session is in the same state is was in before the user submitted the faulty data. If you want to prevent the button press to navigate to another window, but you dont want to roll back the current transaction, you could also return the value D2MFWEventHandleResult::OK, without calling super(), so any navigating configured as a button action is bypassed.

Dynamics Anywhere Framework Developer's Guide

23

Make sure you perform the call to super() after you have finished processing the user submit, if you call it earlier it may navigate to another screen, and variables may have been set or cleared, and business logic may have been called, during navigation.

5.3 Initializing objects when the form loads

Another common use for custom code is to initialize some data of modify the properties of a control (for instance to hide a button for an option that is disabled in the configuration). To override this event, find the class for the form on which you want to add some custom code when it loads, and override the method onLoad. The onLoad event is called whenever the form is navigated to from the main menu, by a button which has a Show form button action configured, or from code by a call to the <formClass>.showForm method.
public D2MFWEventHandleResult onLoad() { D2MFWEventHandleResult ret; ret = super(); // initialize a user control and variable this.btnPrint().visible(NoYes::No); this.getMain().varSelectedItemId(""); return ret; }

Handle the call to super first, as this will clear all controls that have the clear on load property set.

5.4 Responding to user input from a previous form

Sometimes it is very useful to be able to ask the operator a question, and wait for a respond (for example, an are you sure pop-up where the user can respond with yes or no). If a form is closed by a return from form button action (or a call to this.returnFromForm in code), the form that is pulled from stack and is now the new active form will have its onReactivate method called. To respond to the user selection in a previous form, find the class for the form, and override the method onReactivate.
public D2MFWEventHandleResult onReactivate(D2MFWFormInstanceID _returnedFromFormID, D2MFWFormResult _formResult) { D2MFWEventHandleResult ret; ret = super(_returnedFromFormID, _formResult); if (this.getMain().getAreYouSure().isReturnedFromForm(_returnedFromFormID)) { if (_formResult == D2MFWFormResult::Yes) { // do something here } else // do nothing (just show the current form again) return D2MFWEventHandleResult::OK; } return ret; }

24

Dynamics Anywhere Framework Developer's Guide

In this example, code is added for when the form is reactivated after a form called AreYouSure exits (presumably, this form navigated to the AreYouSure form). You can see how to respond differently depending on the result the AreYouSure form exited with. You can find an example of this in chapter 10. Handle the call to super first, as this will clear all controls that have the clear on reactivate property set.

5.5 An overview of other form event methods

These methods can also be overriden, although they are far less commonly used than the previous ones.

5.5.1 OnControlCheckedChanged
This method is called when a control on the form has its checked property changed by the operator. Please note, this event will execute after the user submitted the changes by pressing a button or function key, so this is not real-time!

5.5.2 OnControlSelectedIndexChanged
This method is called when a control on the form has its selected index property changed by the operator. Please note, this event will execute after the user submitted the changes by pressing a button or function key, so this is not real-time!

5.5.3 OnControlTextChanged
This method is called when a control on the form has its text property changed by the operator. Please note, this event will execute after the user submitted the changes by pressing a button or function key, so this is not real-time!

5.5.4 OnDeactivate
This method is called when a form navigates away to another form by a showform button action or by calling <formClass>.ShowForm.

5.5.5 OnInit
This method is called when a form is instantiated, and is usually only called once during the lifetime of an application session.

5.6 An overview of application event methods

The application class also has some methods that can be overridden, although they are seldom used.

5.6.1 Onload
This method is called when the application is loaded. It is not called when the user logs in again on an already instantiated application.

5.6.2 OnLogoff
This method is called when the user logs off from the application. It is not called if the web session expires, only when the framework performs a log off.

Dynamics Anywhere Framework Developer's Guide

25

5.6.3 OnMenuSelect
This method is called when a menu option is selected. When overriding this method, pass over the call to super if you dont want to perform the action associated with the menu item (opening a form, submenu or other application).

5.7 Responding to events in general, calling event methods explicitly from code
When responding to events in general, make sure you return a D2MFWEventHandleResult value if required (some event methods are void methods and dont require the return of a result value). Use either the return value of super, or return D2MFWEventHandleResult::OK if you didnt call super. This is important because the framework will take a cue from the returned value for further navigation, and returning a value other than D2MFWEventHandleResult::OK may result in unexpected behavior. You can also explicitly call an event method when reacting to another event method. In the example below, we have a form where the user inputs an item id. Upon returning from a list form where the user selected an item from a list, we accept this item and call the onSubmit method to simulate the user pressing the OK button.

public D2MFWEventHandleResult onReactivate( D2MFWFormInstanceID _returnedFromFormID, D2MFWFormResult _formResult) { D2MFWEventHandleResult rv = super(_returnedFromFormID, _formResult); if((_formResult == D2MFWFormResult::OK) && (this.getMain().getListItems().isReturnedFromForm(_returnedFromFormId))) { // set ItemId in textbox and simulate press OK this.getTxtScannedData().text(this.getMain().varItemId()); return this.onFormSubmit(this.getBtnOk().getControlInstanceID()); } return rv; }

Please note that the return value from onSubmit is returned instead of the return value from the call to super. This is especially important when explicitly calling onFormSubmit, failing to do so for this method may result in buttons with the main menu or logout button action not working anymore.

26

Dynamics Anywhere Framework Developer's Guide

6. A case: getting some item information

Inevitably, there comes a point when business logic needs to be called to look up some information, register some data, validate some user input etc. This is done by adding business logic to the classes the framework generated when forms were added to the application. For this case, well add a form to our Hello World application where the user scans or enters a unit id, and well look up the item in the AX table InventTable. This involves modifying the form class to add some validation and querying.

6.1 Adding the forms in the designer

First, we add some labels.

Next well add two forms called ScanItemId and ShowItemName (dont forget to set the Title label id), and two global type variables called ItemId and ItemName (with matching extended data type, although it is not a requirement that they have the same name).

Select the form ScanItemId, add a user control called TxtItemId. Set up a linked variable to this control here.

Clears the control when the form is opened.

Checks if something is filled in (see also button)

Gets a caption from the EDT (e.g. Item Id:___)

Dynamics Anywhere Framework Developer's Guide

27

Add a horizontal line.

Then add a button called BtnBack.

And add a button called BtnOk.

Show form button action navigates to another form when pressed.

Checks all required textboxes when this button is pressed.

28

Dynamics Anywhere Framework Developer's Guide

Finally, refresh the screen by pressing F5, and set the default button property of the form ScanItemId to BtnOk.

6.2 Create a form that displays the result

Next, select form ShowItemName and add a label called LblItemId. Linked variable set to captured item id.

And add a label called LblItemName.

Linked variable set to queried item name.

Dynamics Anywhere Framework Developer's Guide

29

Again, add a horizontal line.

And finally, add a button called BtnOk. Using show form (create or return) instead of return from form, so the load of ScanItemId is triggered, and the textbox is cleared.

Finally, go back to the Application Configuration tab, and add a main menu line for the new form.

30

Dynamics Anywhere Framework Developer's Guide

6.3 Adding some custom code to your application

Now we need to add code to the class that goes with the ScanItemId form. Open the projects tab in AX, and find the public project named D2MFW_HelloWorld.

Select the class HelloWorldScanItemId, right click and select Override method, and then select OnFormSubmit. Add the following code in the overridden method.
public D2MFWEventHandleResult onFormSubmit(D2MFWControlInstanceID _submitTargetID) { D2MFWEventHandleResult ret; InventTable inventTable; ; // Button OK Pressen? if(this.getBtnOk().isSubmitTarget(_submitTargetId)) { // find the item in the database inventTable = InventTable::find(this.getMain().varItemId()); if(!inventTable) // no data found throw error ("unknown item!"); // store name of found item in variable this.getMain().varItemName(inventTable.itemName); } ret = super(_submitTargetID); return ret; }

Next, save and compile your code.

Dynamics Anywhere Framework Developer's Guide

31

6.4 Testing your modifications

First, log out of the application if you havent already (if you dont, your changes might not show up). If your web session has expired, youll need to log in first to be able to log out! If youre still having trouble, you can try to delete your session from the Active Sessions form (see chapter 11). Now, log back in.

Your new menu item shows up on the bottom. Change the line number to move it up or down.

Scan or enter an item id here (try AX106).

The name of the item should show up (or an error message if the item id you entered wasnt valid).

32

Dynamics Anywhere Framework Developer's Guide

7. The transaction log

7.1 Introduction
Now is a good time to look at the transaction log. From the AX main menu, select DAW Framework, and select Transaction Log. Events received from the portal (newest on top).

Event sent by the portal (logon, key press, etc.). Response from the framework.

Contents of the AX info log after handling the event. Here, youll find all transactions send to the framework by the Portal, and the response from the framework. Also displayed here are the contents of the info log at the end of event handling. Often, when your application is behaving erratic, youll find an answer here. For instance:

You may find error messages in the response.

7.2 Cleaning up the transaction log

Theres a Cleanup transaction log button on the transaction log form to clean up the transaction log. You can specify the age of transactions to clean from the log. This action can also be batched.

Dynamics Anywhere Framework Developer's Guide

33

7.3 Debugging the application

The transaction log offers an option to feed a logged transaction back to the framework for testing purposes, breaking to the debugger as processing starts. In order to make this work, youll need to have AX configured so it will allow debugging, refer to the AX documentation for more information on how to do this.

7.3.1 Notes on application state

An important fact to keep in mind when trying to debug a transaction is that the application should be in the same state as it was when the transaction was received or it will not work as intended. Consider the case where a transaction contains a submit of a button on form A, but the application has already moved on to form B. Execution will now fail as form B will not contain the button that caused the submit action. As a rule of thumb, you can debug a transaction if your application is at the same form instance it was when the transaction was originally received (so no logging out in-between).

7.3.2 Breaking your code with a throw so you can debug

If the transaction you want to debug results in navigating away from the current form, or if it is performing some registration that invalidates a second pass through, there is a trick you can perform. Consider the example with the item information screens we created earlier. Suppose we want to debug the query in InventTable we created in chapter 6. To do this, first modify the code to include a throw error, and save and compile it:

Throw an error here.

34

Dynamics Anywhere Framework Developer's Guide

Next, perform the action in the application, so itll execute the bit of code with the throw error in it.

The thrown error shows up here.

Go back to your code, remove the throw, set a breakpoint, save and compile

Remove the throw, set a breakpoint.

Next, well look up the transaction in the transaction log.

Dynamics Anywhere Framework Developer's Guide

35

7.3.3 Debugging your code

Go to the Transaction Log, and select the last transaction (if youre in an environment with multiple active sessions, you can look in the response field for your throw error text).

This button starts debugging the transaction.

The text from the error throw shows up here.

Next, press the button Debug Transaction. If AX is set up correctly for debugging code, the debugger will pop up. The run button will take you to your breakpoint.

36

Dynamics Anywhere Framework Developer's Guide

Press the Run button to jump to your breakpoint.

Were now in our own code, and can debug it.

You can now debug your code.

Dynamics Anywhere Framework Developer's Guide

37

8. A case: showing information in a data grid

Populating a data grid can be done manually, but the easiest way is to use the fillFromList method available on the data grid class, which accepts a packed list object for a list of struct classes, where each struct class contains a row of data. In the grid configuration, you can map the name of the field in the struct class to a column in the data grid. Note: in previous versions, we did use a method called FillFromQuery to populate data grids. This method will still work, but it is much less efficient, and is now deprecated. Try to use FillFromList instead. With FillFromQuery, you had to pass a list iterator for a list, with fillFromList you pass the list as a packed list (use <list>.pack() to create one), so changing to FillFromList requires only a minor modification any existing code you may have.

8.1 Adding a new form to the designer

For this case, well add an additional form to the item information forms, which will show a list of items. First, we need to add some labels.

Add a new form called ListItems.

On this form, well display a grid with all the items, where the user can select an item.

38

Dynamics Anywhere Framework Developer's Guide

Select the ListItems form and add a data grid control named GridItems (leave it as it is for now) and a horizontal line (refer to the previous hands-on sections if youre unsure how to do this). Then, add a button control called BtnBack.

Next, add a button control called BtnOK.

Set this so the OK button selects data from the grid. Finally, select the form ListItems, and set the default button to BtnOK.

Dynamics Anywhere Framework Developer's Guide

39

8.2 Adding code to look up the item

Now, find the newly created class HelloWorldListItems in the project D2MFW_HelloWorld (you may need to close and then reopen the project to refresh the contents), and add a new method named qryItems. To do this, right-click the class and select new method.
private container qryItems () { str structBuild = "str ItemId; str ItemName; str ItemGroupId"; struct s; List resultList = new List(Types::Class); InventTable inventTable; ; while select * from inventTable { s = new struct (structBuild); s.value("ItemId", inventTable.ItemId); s.value("ItemName", inventTable.itemName); s.value("ItemGroupId", inventTable.ItemGroupId); resultList.addEnd(s); } return resultList.pack(); }

This method is used to populate the grid with data. It fills a list with structs, where each struct represents a line of data to be displayed in the grid. Finally, the list is packed and returned. Next, well add a call to the method we just created, so override the onLoad method of the class HelloWorldListItems, and add a call to the fillFromList method of the grid, passing the packed list object created by the qryItems method, to populate the grid.
public D2MFWEventHandleResult onLoad() { D2MFWEventHandleResult ret; ret = super(); this.getGridItems().fillFromList(this.qryItems()); return ret; }

Here, the packed list from our first method is passed to the .fillFromList method that is unique to data grids. Upon entering the form, the data grid will now be populated by data from the invent table. Next, well set up the data to display.

40

Dynamics Anywhere Framework Developer's Guide

8.3 Setting up the data grid

Then, go back to the designer, select the form ListItems, then select the GridItems control.

On the Grid configuration (which only appears when you select a grid control), create the column mappings as shown here.

Set to 0 to hide this column.

This links data from the method to the column.

When a button with Data Grid Select is pressed, this variable is filled.

Please make sure the texts in the Query result list mapping column matches the names of the fields in the structs we created in the qryItems method. Also, if you decided to skip creating a horizontal line a couple of steps back, make sure you check the Append newline property on the data grid as shown below, otherwise the buttons will show up to the right of it instead of under it.

Dynamics Anywhere Framework Developer's Guide

41

8.4 Navigate to the new form

Finishing up, select the form ScanItemId, and add a button to navigate to the new form. Set tab order to 1.5 so it shows up behind the textbox. Navigate to form ShowItemName.

Also, remove the append newline on the TxtItemId textbox so the button sits directly to the right of it.

Clear this so the button ends up right next to the textbox.

42

Dynamics Anywhere Framework Developer's Guide

8.5 Test the modification

Now, test the result (dont forget to log out first or delete your session or the changes may not show up correctly). It should be something like this:

Select this button

Select an item and press OK

Select the item info option .

Press F3: Items to display the list

The item shows up here

After pressing OK, the item is selected. If you are up for an extra challenge, you may want to try to display the ItemGroupId field in the data grid, and if youre feeling up to it, maybe add the current stock level of the item to the grid, too.

Dynamics Anywhere Framework Developer's Guide

43

9. Manipulating the framework through code

Much of the configurable effect of the framework can also be performed by calling code in X++. This section provides an overview of the various objects that can be called from code.

9.1 Methods of the application class

9.1.1 About the application class
The application class is called <application name>Main, and can be found in the automatically generated project with the name D2MFW_<application name>. To get the application class when executing a method in a form class, just call this.getMain(), which will return a reference to the main class.

9.1.2 Getters for form classes

The application class contains a getter method for every form in the application. The getter method is named get<form name>. This makes it very easy to access the properties and methods of any form from code.

9.1.3 Getters/setters for variables

The application class contains a getter/setter method for every global type variable. The name of this method is var<variable name>. This makes it very easy to access variables from code.

9.1.4 FindLabel
Use this method to quickly find a (DAW) label (without having to provide the device type id and language id).

9.1.5 GetDeviceTypeId
Gets the device type id for this session.

9.1.6 GetHostname and GetUserId

These getter methods return the logged in user id and hostname (IP address) of the current session.

9.1.7 GetLanguageId
Returns the language id of the current language for this session.

9.1.8 Get/SetMainParam and Get/SetMainParamContainer

These methods allow you to get or set a global type variable without creating it in the designer, using a text string instead to reference it. Using these methods is not recommended as it might seriously compromise the proper functioning of variables created during design.

9.1.9 Logoff
Logs off the current application. When calling from an event method, return the return value of this method to properly log off.

44

Dynamics Anywhere Framework Developer's Guide

9.1.10 ReturnFromForm
Deactivates the current active form, and set the top form on the form stack as the new current form. This is the same as the return from form button actions. It takes a parameter that is passed to a call to the previous forms onReactivate event method as _returnResult.

9.1.11 ShowFormByInstanceId and ShowFormByConfigId

Shows a form taking either the form instance id or the form configuration id as a reference. It is preferable to show a form in code by using the form getter method to get the form class and call its ShowForm method, which doesnt require parameters. This is the same as setting the showform button action. Leaving the _returnToExisting parameter false, the current active form is placed on the form stack, and the new form is instantiated if needed, and set to the new current form. If the _returnToExisting parameter is set to true, and the new form is already somewhere in the form stack, the forms above it on the stack are removed and the form is set active. If the form is not already in the stack, the system behaves just as if the parameter was left false.

9.1.12 ShowMainMenu
Returns the application to the main menu. When calling from an event method, return the return value of this method to properly return to the main menu.

9.2 Methods of the form class

9.2.1 About the form class
The application class is called <application name><form name>, and can be found in the automatically generated project with the name D2MFW_<application name>.

9.2.2 Getters for user control classes

The application class contains a getter method for every user control on the form. The getter method is named get<control name>. This makes it very easy to access the properties and methods of user control from code. Available methods will vary with the type of control returned (e.g., a class for a text box will not have the checked property).

9.2.3 Getters/setters for variables

The application class contains a getter/setter method for every global type variable. The name of this method is var<variable name>. This makes it very easy to access variables from code.

9.2.4 Get/SetFormParam and Get/SetFormParamContainer

These methods allow you to get or set a local type variable without creating it in the designer, using a text string instead to reference it. Using these methods is not recommended as it might seriously compromise with proper functioning of variables created during design.

9.2.5 GetHostname and GetUserId

These getter methods return the logged in user id and hostname (IP address) of the current session.

Dynamics Anywhere Framework Developer's Guide

45

9.2.6 Get/SetMainParam and Get/SetMainParamContainer

These methods allow you to get or set a global type variable without creating it in the designer, using a text string instead to reference it. Using these methods is not recommended as it might seriously compromise with proper functioning of variables created during design.

9.2.7 IsReturnedFromForm
This method takes the _returnedFromFormId parameter passed to the onReactivate event method, and returns true if it matches the forms instance id.

9.2.8 PerformButtonNavigation
Performs the navigation action associated with a button on the form. Use this when you want to perform the navigation action associated with another button, but not the business logic in onSubmit. Important: when calling this from another event method, make sure you return the value returned by this function when you exit the event method. If you call the onSubmit of the form like this, dont call super as this might interfere with the navigation performed by the PerformButtonNavigation method.

9.2.9 ReturnFromForm
Deactivates the current active form, and set the top form on the form stack as the new current form. This is the same as the return from form button actions. It takes a parameter that is passed to a call to the previous forms onReactivate event method as _returnResult. Please note this method closes the current active form, which might not be the form that the calling class is linked to.

9.2.10 ShowForm
Shows the form, making it the new current form. This is the same as setting the showform button action. Leaving the _returnToExisting parameter false, the current active form is placed on the form stack, and the new form is instantiated if needed, and set to the new current form. If the _returnToExisting parameter is set to true, and the new form is already somewhere in the form stack, the forms above it on the stack are removed and the form is set active. If the form is not already in the stack, the system behaves just as if the parameter was left false.

9.3 Methods of user control classes

9.3.1 About the user control classes
The user control classes are returned by the getter functions that are automatically generated in the form class when a user control is added to the form. Depending on the type of user control, some of the methods described below may not be available. The user control classes are D2MFWTextControlClass, D2MFWCheckboxControlClass, D2MFWListControlClass, D2MFWComboboxControlClass and D2MFWDatagridControlClass.

9.3.2 BoundDataCount (data grids only)

Returns the number of rows of data for a data grid.

46

Dynamics Anywhere Framework Developer's Guide

9.3.3 BoundDataContainsField (data grids only)

Returns true if the struct containing the data for a row in the data grid contains the specified field.

9.3.4 Checked (checkbox only)

This getter/setter allows the developer to evaluate or set the checked value of a checkbox control, setting this property also sets the linked variable if any.

9.3.5 ClearBoundData (data grids only)

Clears the list of data associated with a data grid.

9.3.6 FillFromList (data grids only)

This method populates a data grid. It accepts a packed list (container) for a list of struct classes, where each struct class represents one row of data. The name of the struct fields should correspond with the query result mapping property of the data grid in the designer (see also 3.2.2). This method replaces FillFromQuery.

9.3.7 FillFromQuery (deprecated)

This method is deprecated. Use FillFromList instead.

9.3.8 GetBoundData, GetBoundDataStruct (data grids only)

Use these methods to get data from a data grid. Use GetBoundData to get a specific column in a row, or GetBoundDataStruct to get the entire row. Row index is optional (leave empty for the current row).

9.3.9 HasFocus and SetFocus

Use this method to check if a control has the focus or set the focus to the control. Please note, this just notifies the portal to set a specific control to be focused, and does not prevent the user from selecting another, nor does it reflect the focus the user set (so this method cant be used to check if the cursor is currently in a specific textbox for instance).

9.3.10 IsSubmitTarget (buttons only)

This method takes the _submitTargetId passed to the onSubmit event method on a form class, and returns true if the target of the user submit is this control. Available on all controls, although most often used for buttons.

9.3.11 ListFields (data grids only)

Returns a list of the field names in the structure containing the data for a data grid row.

9.3.12 SelectedIndex (data grids only)

This getter/setter allows the developer to manipulate the current selected row on list type controls, setting this property also sets the linked variable if any.

9.3.13 Text
This getter/setter allows the developer to evaluate or set the text value of a control. For text controls, setting this property also sets the linked variable if any.

Dynamics Anywhere Framework Developer's Guide

47

10. A Case: reacting to return from form result values

If is often very useful to have pop-up style dialog windows, where the operator has to respond to a question by choosing one of several options (Are you sure? (Yes/No), Continue? (OK/Cancel). To create pop-up style dialog boxes, create a dialog form with two or more buttons and set the button actions of these forms to different versions of the return from form actions. You can show this form from another form, and react to the choice of the operator by evaluating the _formResult parameter that is passed to the onReactivate method of the calling form when the dialog form exits.

10.1 Automatically continue after selecting an item from the list

For this case, we will use the list we created in chapter 8, and add functionality to it so that after we select an item, we dont go back to the scanItemId form where we have to press OK, but instead continue straight into the DisplayItemName form. Of course, we could do this by letting the OK button on the ListItems form navigate straight to the DisplayItemName form, but wed be skipping the business logic we added to the onSubmit method in chapter 6, so the item name would not be filled in. Instead, well leave it as it is, and in the form ScanItemId, well add code to the OnReactivate method, where well first determine if the user pressed OK on the ListItems form, and if the user did, well execute the business logic that goes with the OK press on the ScanItemId form.

10.2 Adding code to the OnReactivate method

To have the ScanItemId form automatically continue after the ListItems form closes, open the shared project HelloWorld, locate the class HelloWorldScanItemId, and override the OnReactivate method (if you dont remember how to do this, please refer to chapter 6). Change it so it looks like this.
public D2MFWEventHandleResult onReactivate(D2MFWFormInstanceID _returnedFromFormID, D2MFWFormResult _formResult) { D2MFWEventHandleResult ret; ret = super(_returnedFromFormID, _formResult); // when the form ListItems was closed if(this.getMain().getListItems().isReturnedFromForm(_returnedFromFormID)) // and the user pressed OK if(_formResult == D2MFWFormResult::OK) // call the logic that goes with pressing the OK button on this form (ScanItemId) return this.onFormSubmit(this.getBtnOk().getControlInstanceID()); return ret; }

Save and compile the code.

48

Dynamics Anywhere Framework Developer's Guide

Now, after the user selects an item from the list of items and presses the OK button, the business logic that goes with submitting a press of the OK button on the ScanItemId form is executed. Remember, we set the button action property of the OK button to return from form (OK), and that is what we are checking in this bit of code by comparing it with D2MFWFormResult::OK. You can now check your changes. Note that after you select an item from the list and press the OK button, the application goes straight to the form displaying the item name. Also note, if you exit the list form by pressing cancel, you simply return to the item id input form. This same method could also be used to react to a user response to a form that offers a yes/no, or ok/cancel kind of dialog window.

Dynamics Anywhere Framework Developer's Guide

49

11. Sessions and setup

11.1 Active Sessions Form
The Active Sessions form displays the currently connected devices. It also allows you to transfer a session from one device to another.

Logged Employee.

Log-on date/time .

Resolution of client device.

Detected browser.

Last active date/time .

Delete sessions that have expired (can be batched).

Device IP addresses.

Events sent to AX.

Web session ID.

Current active process.

Check to allow user to transfer session.

To access the framework parameters, go to the option DAW Framework from the main menu, and select Active Sessions.

11.2 Transferring Sessions to another Device

In order to transfer a session from one device to another, locate the session for this user in the active sessions form, and check the Session takeover allowed column for that session. When the user logs on to another device, the session is transferred to that device. You can set the framework up so this setting is always checked (e.g. sessions are always transferred to another device when the user logs in, see chapter 11.3). If the Session takeover allowed column is unavailable, it may have been disabled in setup (see chapter 11.3).

50

Dynamics Anywhere Framework Developer's Guide

11.3 Framework Parameters

To access the framework parameters, go to the option DAW Framework from the main menu, and select Parameters. Prevents users from logging in on multiple devices. Toggles between just the last line and full infolog on an error.

Enables the option to transfer a session from one device to another. Checks to transfer a session to another device automatically (otherwise, an operator sets this manually on the Active Sessions form). Sessions will timeout when inactive. Inactivity timeout period. Number sequences used by the framework. Refer to the Installation guide for a description on how to set them up.

Specifies whether to log all, slow or no transactions.

Threshold value (in seconds) for what counts as slow transactions.

Dynamics Anywhere Framework Developer's Guide

51

12. Notes

52

Dynamics Anywhere Framework Developer's Guide