DG DAW 2010-01-20.Framework Development Guide.v2.0.0.0

Dynamics Anywhere Framework Developer's Guide

Version : 2.0.0.0

Document title: : Dynamics Anywhere Framework

Document type: : Developer's Guide Author : J. Holland Publish date : 20-1-2010 File name : DG-DAW-2010-01-20.Framework_Development_Guide.v2.0.0.0.docx Version : 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.

http://www.dynamicsanywhere.com/

Table of contents

1. INTRODUCTION ........................................................................................................................................................ 1

1.1 WHO SHOULD READ THIS GUIDE? .................................................................................................. 1 1.2 WHAT IS DISCUSSED IN THIS GUIDE? ............................................................................................... 1 1.3 NEW IN THIS VERSION ................................................................................................................... 1

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

2.1 INTRODUCTION ............................................................................................................................ 2 2.2 THE FRAMEWORK WITHIN AX ........................................................................................................ 3 2.3 ON SESSIONS ............................................................................................................................... 4

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 CREATE A FORM THAT DISPLAYS THE RESULT ................................................................................... 29 6.3 ADDING SOME CUSTOM CODE TO YOUR APPLICATION ....................................................................... 31 6.4 TESTING YOUR MODIFICATIONS .................................................................................................... 32

7. 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 ADDING A NEW FORM TO THE DESIGNER ........................................................................................ 38 8.2 ADDING CODE TO LOOK UP THE ITEM ............................................................................................. 40 8.3 SETTING UP THE DATA GRID ......................................................................................................... 41 8.4 NAVIGATE TO THE NEW FORM ...................................................................................................... 42 8.5 TEST THE MODIFICATION ............................................................................................................. 43

9. 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 HasFocus and SetFocus .................................................................................................. 47 9.3.10 IsSubmitTarget (buttons only) ....................................................................................... 47 9.3.11 ListFields (data grids only) ............................................................................................. 47 9.3.12 SelectedIndex (data grids only) ...................................................................................... 47 9.3.13 Text ................................................................................................................................ 47

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

10.1 AUTOMATICALLY CONTINUE AFTER SELECTING AN ITEM FROM THE LIST ................................................ 48 10.2 ADDING CODE TO THE ONREACTIVATE METHOD .............................................................................. 48

11. SESSIONS AND SETUP......................................................................................................................................... 50

11.1 ACTIVE SESSIONS FORM .............................................................................................................. 50 11.2 TRANSFERRING SESSIONS TO ANOTHER DEVICE ............................................................................... 50 11.3 FRAMEWORK PARAMETERS ......................................................................................................... 51

12. NOTES ................................................................................................................................................................ 52

Dynamics Anywhere Framework Developer's Guide 1

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

DAW FrameWork

XML

DAW Application repository

DAW / Application User interface

Microsoft Dynamics AX Functionality

AOS

Mic

roso

ft D

ynam

ics

AX

.NET

Bu

sin

ess

Co

nn

ecto

r

DA

WFW

Web

serv

ice

DA

WFW

Mo

bile

Po

rtal

HTML

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.


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

AX

business

logic

Dynamics Anywhere FW

Event

Handler SessionSession UI

Element

UI

Element

UI

Element

AX Database

UI Config

and default

properties

Application

and form

vars

Form and

UI element

properties

UI element

bound data

AX data

Application

Extended

Application

Application

Extended

Application

Custom

extension

to

application

Application

Form

Extended

Form

Form

Extended

Form

Custom

extension

to form

FormUser action

New screen

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.


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.


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

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

Applications

The menus configured for the selected application

Multi language labels in the selected application

Records in the Application Configuration mimic the AX layer system.


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 you’ve defined a menu with at least one option, and reference this menu in the application properties.

3.1.3 Menu properties


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


Label id Uniquely identifies a text label (for multiple languages/devices)

Devicetype Id Device type

Language Id Language

Text Text to display on the specified device in specified language.


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 en-us label is missing in this case, the framework could behave erratically or crash.

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

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.

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)

Properties that may vary for different device types

“Local” variables on the selected form

Variables can be linked to controls


3.2.1 Form properties


Sort order Order in which forms are displayed on this screen

Form config id Uniquely identifies the form in the application

Title label id Reference to the label shown as the form title

Default button 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.


Control Config Id Uniquely identifies a control on a form

Control Type Control Type

Taborder 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: Append colon Applies to: Label Description: Append a colon after the text Property: Append newline Applies to: Label, Textbox, Button, Grid, Literal HTML, Checkbox Description: Append a line break after the control Property: Button action Applies to: Button Description: Action to perform when button is selected Property: Button action form id Applies to: Button Description: When the button action performs navigation to a form, this contains the id of

that form Property: Checked Applies to: Checkbox Description: Checked property Property: Clear on load Applies to: Label, Textbox, Grid, Checkbox Description: Clears the control value upon loading the form (see 5.3)


Property: Clear on reactivate Applies to: Label, Textbox, Grid, Checkbox Description: Clears the control value upon reactivating the form (see 5.4) Property: Data grid select Applies to: Button Description: 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 Property: Get caption from EDT Applies to: Label, Textbox Description: Gets and displays a caption for the label or textbox from the extended data

type of the linked variable Property: Hotkey Applies to: Button Description: Hotkey (function key) linked to control Property: Include hotkey in caption Applies to: Button Description: Show hotkey in caption (e.g. “F1: Back”) Property: Label id Applies to: Label, Textbox, Button, Checkbox Description: Reference to the label show as text with the control Property: Linked variable Applies to: Label, Textbox, Button, Grid, Checkbox Description: Name of the variable linked to the value of the control Property: Linked variable form id Applies to: Label, Textbox, Button, Grid, Checkbox Description: Either empty (for a global type variable), or the id of the current form (for a

local type variable) Property: Read-only Applies to: Label, Textbox, Button, Grid, Checkbox Description: Read-only controls show up greyed out Property: Required Applies to: Textbox Description: 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.

Property: Selected index Applies to: Grid Description: Selected index


Property: Text Applies to: Label, Textbox, Button, Literal HTML, Checkbox Description: Literal text to use instead of a label (you can use AX sys labels here) Property: Validate textbox Applies to: Button Description: See “Required” Property: Visible Applies to: Label, Textbox, Button, Grid, Checkbox Description: 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: Grid column Description: Order of the column within the grid. Make sure the numbers are consecutive

(no numbers are skipped). Property: Label id Description: Reference to label shown in header of the column. Property: Column width Description: Width in pixels of the column. Use a width of 0 to hide the column. Property: Query result list Description: If a result list is used to populate the grid, this references the struct field used

for this column. Property: Linked variable Description: Name of the variable linked to the value of this column. Property: Linked variable form id Description: Either empty for a global type variable, or the id of this form for a local type

variable. Creating a column definition for a data grid is not required. If the developer doesn’t provide one, all of the columns in the data linked to the data grid are displayed.


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


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.

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

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.

Variable linked to control

Uniquely identifies this variable.

Associated AX extended data type.

Default value.


Control Type Allowed Base Type Linked property

Checkbox Enum (of type NoYesId) Checked

Data grid Interger, Int64 SelectedIndex

Textbox or label Date, Guid, Integer, Int64, Real, String, Time, Enum Text

Grid column Type should be compatible with the data displayed 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

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.

Definition of available devices along with their resolution

Definition of available fonts


4. A case: Hello World part 1

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

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

The result should look something like this:

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

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

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

2. Create the labels.

3. Create the menu items.

4. Set the main menu and title label.


4.2 Adding forms to your application Next, we’ll 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

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

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


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 can’t change name or type anymore.

Finally, add a user control of the type button named BtnOk (don’t forget to set the control type before saving), and set the properties as in the sample below.

We now have a form that displays a single fixed line of text, and has a button that exits the form.

2 Only properties appropriate to the control are show. If you don’t see the properties change, save your record, reselect the record or refresh the screen.

Don’t forget to select the control type.

Literal HTML tags need to be XHTML (conform to XML).

Use tab order to set the order in which controls show up in your form.

Causes the form to exit when pressed.


4.2.2 Configuring the logout form

Next, select the form configuration grid and press F5 to refresh it.

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.

Default button will show up after you press F5.


Add a button, named BtnNo.

And one named BtnYes.

Now, we’ll change the default button for the logoff form to BtnYes. You’ll 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.

Logs the user out when pressed.


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 we’re 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 you’re creating a new user, don’t 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.


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 don’t 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 you’re 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 you’re not accidently entering a character other than the “/” character as the separator character (open up notepad to test this if you are not sure).


You now see the main menu (it may look slightly different depending on the type of browser you’re 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.


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.


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. 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 don’t 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.

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;

}


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. 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 onLoad()

{


ret = super();

// initialize a user control and variable

this.btnPrint().visible(NoYes::No);

this.getMain().varSelectedItemId("");

return ret;

}

public D2MFWEventHandleResult onReactivate(D2MFWFormInstanceID _returnedFromFormID,

D2MFWFormResult _formResult)

{


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;

}


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.


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 don’t 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 don’t require the return of a result value). Use either the return value of super, or return D2MFWEventHandleResult::OK if you didn’t 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. 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.

public D2MFWEventHandleResult onReactivate( D2MFWFormInstanceID _returnedFromFormID,


{

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;

}


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, we’ll add a form to our Hello World application where the user scans or enters a unit id, and we’ll 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 we’ll add two forms called ScanItemId and ShowItemName (don’t 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.

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:___”)

Set up a linked variable to this control here.


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.


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.

And add a label called LblItemName.

Linked variable set to captured item id.

Linked variable set to queried item name.


Again, add a horizontal line.

And finally, add a button called BtnOk.

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

Using show form (create or return) instead of return from form, so the load of ScanItemId is triggered, and the textbox is cleared.


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. Next, save and compile your code.

public D2MFWEventHandleResult onFormSubmit(D2MFWControlInstanceID _submitTargetID)

{



;

// 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;

}


6.4 Testing your modifications First, log out of the application if you haven’t already (if you don’t, your changes might not show up). If your web session has expired, you’ll need to log in first to be able to log out! If you’re 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 wasn’t valid).


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.

Here, you’ll 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, you’ll find an answer here. For instance:

7.2 Cleaning up the transaction log There’s 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.

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

Events received from the portal (newest on top).

Response from the framework.

Contents of the AX info log after handling the event.

You may find error messages in the response.


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, you’ll 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.


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

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

Next, we’ll look up the transaction in the transaction log.

Remove the throw, set a breakpoint.

The thrown error shows up here.


7.3.3 Debugging your code

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

Next, press the button Debug Transaction. If AX is set up correctly for debugging code, the debugger will pop up.

The text from the error throw shows up here.

This button starts debugging the transaction.

The run button will take you to your breakpoint.


Press the Run button to jump to your breakpoint.

You can now debug your code.

We’re now in our own code, and can debug it.


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, we’ll 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, we’ll display a grid with all the items, where the user can select an item.


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 you’re unsure how to do this). Then, add a button control called BtnBack.

Next, add a button control called BtnOK.

Finally, select the form ListItems, and set the default button to BtnOK.

Set this so the OK button selects data from the grid.


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. 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, we’ll 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. 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, we’ll set up the data to display.

private container qryItems ()

{

str structBuild = "str ItemId; str ItemName; str ItemGroupId";

struct s;

List resultList = new List(Types::Class);


;

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();

}

public D2MFWEventHandleResult onLoad()

{


ret = super();

this.getGridItems().fillFromList(this.qryItems());

return ret;

}


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.

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.

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.


8.4 Navigate to the new form Finishing up, select the form ScanItemId, and add a button to navigate to the new form.

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

Set tab order to 1.5 so it shows up behind the textbox.

Navigate to form ShowItemName.

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


8.5 Test the modification

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

Select the item info option . Press F3: Items to display the list

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 you’re feeling up to it, maybe add the current stock level of the item to the grid, too.

Select this button

Select an item and press OK

The item shows up here


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.


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 doesn’t 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.


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, don’t 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.


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 can’t 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.


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 don’t 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 we’d be skipping the business logic we added to the onSubmit method in chapter 6, so the item name would not be filled in. Instead, we’ll leave it as it is, and in the form ScanItemId, we’ll add code to the OnReactivate method, where we’ll first determine if the user pressed OK on the ListItems form, and if the user did, we’ll 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 don’t remember how to do this, please refer to chapter 6). Change it so it looks like this. Save and compile the code.

public D2MFWEventHandleResult onReactivate(D2MFWFormInstanceID _returnedFromFormID,


{


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;

}


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.


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.

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

Logged Employee.

Device IP addresses.

Log-on date/time.

Events sent to AX.

Resolution of client device.

Web session ID.

Detected browser.

Current active process.

Last active date/time.

Check to allow user to transfer session.

Delete sessions that have expired (can be batched).


11.3 Framework Parameters

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

Toggles between just the last line and full infolog on an error.

Prevents users from logging in on multiple devices.

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.

Specifies whether to log all, slow or no transactions.

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

Number sequences used by the framework. Refer to the Installation guide for a description on how to set them up.


12. Notes

Documents

DG DAW 2010-01-20.Framework Development Guide.v2.0.0.0