Developer

Defining the User Interface for Attached Documents

Prerequisites

The following items must be addressed prior to performing this procedure:
  • The object that encapsulates the files stored on the Agentry Client (hereafter referred to as the file object) must already exist and all properties it is to contain must be defined.
  • Though not a technical requirement, it is generally good form to define the synchronization logic for the objects prior to defining the user interface.
  • A part of the functionality implemented in this procedure includes the ability for users to select a file from a list of those on the Agentry Client and to display that file in the application associated with the file type. This functionality can be implemented in the Agentry application project at any time. However, it will not function properly unless the application is installed to the client device and is associated with the file type. This requirement must be met before deployment of this functionality.

Context

This procedure described how to build user interface definitions and functionality around files that have been transferred to the Agentry Client and/or attached to objects locally. The Agentry Client does not display files directly within the client interface, nor does it provide a means to edit these files to the user. However, the files can be displayed in an application for the file type, provided that application has been installed and is associated with the file type on the client device.

To list the files attached to a parent object, a list screen or one of the list types of detail screen fields can be used. The definition of these lists is the same as for the display of any other collection property. The collection is selected to be listed, and the properties from the object type within the collection are selected for display in columns for fields.

In this procedure a list is defined to display a collection of file objects. An action is then defined and a button is added to execute that action that displays the file currently selected in the list. This is accomplished with the definition of an action step of type Windows Command. This type of action step is used to execute commands on the client device. If the path to a non-executable file is defined as the command for the step, the Windows OS will execute the application associated with that file type and open the specified file.

In the example used in this procedure, the module data structure is Customers -> Documents, where Documents is a collection of Document objects to encapsulate the files attached to Customer objects. A screen set to display details of a selected Customer object is already defined and includes detail screens for the other properties of the Customer object. It is to this screen set, named ShowCustomerDetails, that the list screen will be added. The functionality to be implemented includes a list screen with columns displaying the name of the file stored on the client, and another to display the fill file path. On this list screen an action can be executed via either a double-click of an item in the list, or via a button click that displays the selected file in the application associated with its type.

Note that similar behavior can be defined to list the Documents object using other list controls available in Agentry, including List Tile View fields and List View fields, or any display definition that lists collections.

Procedure

  1. We will begin by defining the action to display the selected file in its associated application on the client device. Begin by adding a new action to the module. Set the Name and Display Name as deemed appropriate. The For Object attribute should be set to the file object containing the external data property. In the sample Mobile Northwind application this is the Document object definition.
  2. Once the action is defined, add a new step to it of type Windows Command. Again set the Name as Desired. Then set the attributes of this action step according to the guidance provided below this example:

    • Command: To display a file, the value here must be the fill path and file name of the file to open. A format string can be used here for the External Data property of the file object (In the Mobile Northwind this is the File property), e.g. %File
    • Wait: This attribute controls whether or not to wait for the executed process to complete before continuing execution of the action. When selected, a timeout value is required. For this operation such behavior does not make sense, as there is no way to know how long the user would view the file and setting a wait behavior would prevent the user from accessing the Agentry Client while the external application is still open. Therefore, leave this attribute set to false.
    • Error Message: This is displayed when an error occurs executing the command. For this step, the message can indicate there was a problem opening the file. Note that the operating system may also return an error message should this operation fail and both will be displayed to the user.
    • Timeout Message: This message has no affect on this step definition and can be left blank, as the Wait attribute is set to false.
    • OK and Cancel Labels: These are the buttons displayed in the error message dialog. In most cases either the OK or Cancel would be enabled, but no both. In the Mobile Northwind application this action contains only the single Windows Command step, with no additional steps being executed. Therefore, the OK is sufficient to acknowledge the error message on the Client. If additional steps are included in the action after the Windows Command step, then it should be determined if the user should be allowed to continue the action or not, and to enable the buttons appropriately.

    This step will now pass the full path and file name to the operating system, which will then result in the OS attempting to open the file in the application associated with the file type.

  3. Now the list to display the file objects stored in a collection can be defined. This can include a list screen, a List View detail screen field, or a List Tile View detail screen field. The collection should be the collection property of file objects. In the Mobile Northwind application project this is the Documents property of the Customer object. Typically the file name and file path are displayed. For the Document object this would be the FileName string property and the File external data property, respectively. The external data property type always displays the fill path and file name of the file being referenced when a UI definition targets it for display.
  4. Finally the control(s) are defined to execute the new action. This can include a button definition on the list screen, as defined in this example, that targets the selected Document object in the list. Additionally, or in place of the button, a double-click on-item action can be defined for the list screen that executes the OpenFile action as well, targeting the Document object. If a List View or List Tile View field is defined to list the Documents collection, a button can be defined on the parent detail screen that targets the selected object in the list field.

Results

Once this procedure is complete, a list of the file objects for a given parent object is defined. An action also exists that allows the user to display the selected file in the application on the client device associated with that file type.