Business Object Wizard displays the agent-property value in the Value column of the Configure Agent (configuration property) or BO Properties dialog box. As part of the process of initializing an agent property, you must address the following tasks:
Business Object Wizard uses the following AgentProperty metadata to determine the type of control for displaying the property value:
Table 51 illustrates the possible combinations for displaying the property-value control.
Table 51. Possible property-value control types.
Cardinality | Displays multiple values (isMultiple) | Are valid
values (all ValidValues) provided? |
Explanation |
---|---|---|---|
1 |
false |
No | The property value displays as a plain edit control; that is, a simple box in which users can enter and edit one value. |
1 |
true |
Yes | The property value displays as a drop-down list that displays the specified valid values (see Figure 71). From this list, users can choose only one value. |
n |
true |
Yes | The property value displays as a drop-down list that contains the specified valid values. Each value in this list displays with a check box that, if selected, allows the value to be included in the property's value set (see Figure 71). |
n |
true |
No | The property value displays as a grid control that contains no displaying values. Initially, this grid displays a sub-grid with one empty row. If users enter text in that row, Business Object Wizard inserts another empty row. This process continues until users finish entering new rows. To delete a value, users delete the value's text. Business Object Wizard includes only non-empty rows in the property's value set. |
When Business Object Wizard displays a single-cardinality property that does not have valid values, it just leaves the property's Value field empty. You can, however, define a default value for the property. In this case, Business Object Wizard displays the default value in the Value field. For more information, see Specifying default values.
Figure 71 illustrates two controls that display multiple values (isMultiple = true) in Business Object Wizard.
Figure 71. Single- and
multiple-cardinality controls for properties with multiple
values.
Figure 71 shows single- and multiple-cardinality controls, both of which display multiple values in a drop-down list:
To specify a default value for an agent property, you provide its default value (or values) in the its allDefaultValues member variable. This member variable is an array of Object values. The number of elements in this array must correspond to the cardinality of the property, as follows:
Business Object Wizard assigns the default value to the property before it displays the property. If users do not override this default by specifying a property value, this default value remains as the property value.
Table 52 summarizes the behavior of default values.
Table 52. Default values for agent properties
Cardinality | Contents of allDefaultValues | Display |
---|---|---|
Single | One element |
With valid values (isMultiple=true): With no valid values (isMultiple=false): default value displays in the property's Value field. |
Multiple | One or more elements | Default values display as "checked" items in the drop-down list of valid values. |
To initialize a single-cardinality agent property, take the following steps:
If you do not provide a list of valid values, set the isMultiple variable as false and do not pass in a valid-value array.
The following code fragment initializes a single-cardinality agent property that does not provide a list of values to choose from, and has a default value of 256:
defaultVal[0] = 256; AgentProperty("Property1", AgentProperty.TYPE_INTEGER, "Description of property", false, false, ODKConstant.SINGLE_CARD, null, defaultVal);
To initialize a multiple-cardinality agent property, take the following steps:
If you do not provide a list of valid values, Business Object Wizard provides a sub-grid for users to specify each property value.
The code fragment in Figure 65 initializes a multiple-cardinality agent property named Verbs, which has a list of valid values and default values.