The OpenUI SDK provides the interface to support the development of custom controls for display within the Agentry Client for Android, iOS, and Windows .NET. These controls override the default display and behavior of the detail screen fields that are a part of the Agentry application project.
When looking to make use of the OpenUI SDK, you should first investigate the standard field edit types available to you to verify the behavior you desire is not already one which can be defined within the application project. Assuming there is a need, however, the OpenUI SDK can be used to create almost limitless variations in the user interface of the Agentry Client.
In addition to the necessary code written to create the custom control, it is also necessary to make modifications to the Agentry application project within the Agentry Editor, specifically within the field definition. These changes include modifying the attributes of the field to be overridden, providing information about the class containing the override code, as well as specifying the values and actions available within the Agentry application project the custom control can access and execute, and finally the values available to the Agentry Client from the custom control.
Once custom controls have been developed the Agentry Client must be rebuilt or repackaged, depending on the client platform, in order to distribute them to the mobile users. For both Android and iOS devices, this requires the Agentry Client to be rebuilt and resigned. For Windows devices, the Agentry Client can be repackaged using the Agentry Client Branding SDK.
The projects included in the OpenUI SDK for both Android and iOS are structured for this purpose. Included in both are resource projects which can be modified to both resign the application as well as rebrand it as needed. When built a distributable application (.apk file for Android; .ipa file for iOS) is created.
As a developer of custom controls using the OpenUI SDK, you are expected to provide certain information about the control to the Agentry Client at runtime. Of course this includes the field’s behavior itself, including all display aspects and behaviors. Additionally, it includes items such as size of the control displayed on the detail screen, including 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 available to the Agentry Client, including the value used to set the target property of the detail screen field being overridden.
Included in this behavior for all custom controls, regardless of the field edit type which they override, should be appropriate behaviors related to the various states a field can be in. This includes whether the field is enabled or disabled, and whether the field is visible or hidden. An enabled field and a disabled field can both still be visible, so the custom control should then allow for this and be displayed appropriately. As a basic example, some types of controls are grayed out or have an otherwise different appearance to indicate visually to the user the field cannot be interacted with. If the field is not visible, the Agentry Client will not display the custom control to the user.
In such a situation, the logic should account for this state and handle any values it would otherwise display or make available appropriately. In the event of a non-visible field that is in an enabled, state, the Agentry Client will still enforce any requirements regarding the value returned by the field, for example a minimum string length. In such a situation, a reasonable default value should be provided by the custom control. Disabled fields, regardless of visible state, will not have their values validated. Note that a read-only field is not the same as a disabled field within the Agentry Client. The enabled or disabled state is controled by the Enabled attribute for a field definition. This is typically set at runtime on the Agentry Client based on a return value from a rule. As such, it is important to have a full understanding of the field definition’s defined behavior while implementing the custom control logic.
The Agentry Client will look 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 it’s parent details screen. If it cannot find an adaptor with the referenced named, it will display the field defined within the Agentry application project according to that field’s edit type.
When a custom control is displayed, the user will see the custom control on the detail screen as if it were a built in control. The behavior of the custom control is then dictated by the logic the you have implemented for that control.