OpenUI SDK Concepts, Usage, and Guidance
The OpenUI SDK provides the interface to support the development of custom display controls within the Agentry Client for Android, iOS, and Windows .NET. These controls override the default appearance and behavior of the detail screen fields that make up the Agentry application project.
Before using the OpenUI SDK, investigate the standard field edit types available to make sure there isn't already one you can use in your application project. If there is not, however, you can use the OpenUI SDK to create almost limitless variations.
In addition to the code that creates the custom control, you must also modify the Agentry application project using the Agentry Editor, to support the field definition. These changes include modifying the attributes of the field to be overridden, providing information about the class containing the override code, specifying the values and actions available to the custom control within the application project, and finally, the values that are available to the Agentry Client from the custom control.
General Procedure for Creating Custom Controls
- Install the OpenUI SDK API component for the target client platform, following the instructions Setting Up the Development Environment for Agentry Toolkit.
- Use Agentry Editor to modify the application project by defining the detail screen field to be overridden by the custom control. Specify the Extension Adapter Name, Extension Values, Agentry Values, and Agentry Actions.
- Use the client platform IDE to create the custom control using the OpenUI API.
- Build the project within the IDE, which results in either a full Agentry Client build that includes the custom control logic (Android, iOS); or a DLL containing the customer control logic to be deployed with the Agentry Client executable (Windows .NET).
- Deploy the Agentry Client to a device, and test all behaviors. Repeat the build and deploy steps until the functionality is fully developed and ready for distribution.
- Distribute the application to the client devices according to the standard procedures of the client device platform.
Distributing the Agentry Client with Custom Controls
For both Android and iOS devices, you must rebuild and re-sign the Agentry Client.
For Windows devices, you can repackage the Agentry Client using the Agentry Client Branding SDK.
The sample resource projects included in the OpenUI SDK for both Android and iOS can be modified to both re-sign the application, as well as rebrand it as needed. When you build the distributable application, an .apk file is created for Android; and an .ipa file for iOS.
Developer Requirements and Responsibilities
When you develop custom controls using the OpenUI SDK, you must also provide certain information about the control to the Agentry Client at runtime. This includes the field’s behavior and appearance. Additionally, it includes items such as the size of the control that appears on the detail screen, and whether this size is dictated by the Agentry Client via the sizing attributes of the field definition, or by the custom control. You must also specify and create logic for the values that are available to the Agentry Client.
Included in the logic for all custom controls, should be appropriate behavior related to the various states a field can be in, for example, enabled/disabled or visible/hidden. Enabled and disabled fields can both still be visible, so the custom control must allow for this, and show the field appropriately. For example, some control types are dimmed, or have an otherwise different appearance to indicate visually that the user cannot interact with the field. If the field is hidden, the Agentry Client does not show the custom control to the user.
The login for the control must account for this state, and handle any values appropriately. For a hidden field in an enabled state, the Agentry Client must still enforce any requirements regarding the value returned by the field, for example, a minimum string length. The custom control should provide a reasonable default value. Values are not validated for disabled fields, regardless of whether they are visible or hidden. A read-only field is not the same as a disabled field; the enabled/disabled state is controlled by the Enabled attribute of a field definition, which is typically set at runtime on the Agentry Client based on a return value from a rule. When implementing custom control logic, you should have a full understanding of a field definition’s defined behavior.
Runtime Behavior of the Agentry Client with Custom Controls
The Agentry Client attempts to load the referenced custom control based on the settings of the External Adapter Name attribute within the detail screen field definition, when that field is displayed on its parent detail screen. If it cannot find an adapter with the referenced name, it shows the field that is defined within the Agentry application project according to that field’s edit type.
The user sees a custom control on the detail screen as if it were a built-in control. The behavior of the custom control is dictated by the logic you have implemented for it.