Structured Properties

A structured property is one that is used in a grid-like structure such as a table control on a dialog.

Format

The format for structured properties uses a Structure section in which the structure is defined, and consisting of a number of Attribute elements, as follows:

<PropertyTypes>
     <PropertyType id="identifier" valueType="structure" isList="true_false">
          <Structure>
               <Attribute name="column_ID" valueType="value_type" isList="true_false" 
                    label="column_label" labelKey="label_key" defaultValue="value" 
                    description="description" descriptionKey="description_key" />
           ...
          </Structure>
     </PropertyType>
</PropertyTypes>

where the PropertyType element attributes are:

• id is a unique identifier for the property type.
• valueType indicates that the property type is structured.
• isList indicates whether the property is a list of values of the specified value type (true) or a single value (false).

and the Attribute element attributes are:

• name (required) is the identifier of the column.
• valueType specifies the type of value that the contents of this column can take, and is one of:

  string

  encryptedString

  integer

  double

  boolean

  date

  enum

• isList indicates whether the attribute is a list of values of the specified value type (true) or a single value (false). In this way, a keyed property can be associated with either a fixed set of known attributes (for example, Boolean attributes representing the different aggregation operations to be performed on a particular field) or a list of values (for example, associating a list of field names with some other field names).
• label (required) is the display name for the column as it is to appear on the user interface.
• labelKey identifies the label for localization purposes.
• defaultValue is a value that is to appear in the column when it is displayed.
• description is a description of the column.
• descriptionKey identifies the description for localization purposes.

Example - Table Control

For an example of how structured properties are used in a table control, see Table Control.

Examples - Keyed Property Types

The first of these examples illustrates the use of a keyed property type where each associated value is a structure representing which aggregation operation to apply to a field from a fixed set of operations:

<PropertyType id="aggregateOps" isKeyed="true" valueType="structure">
  <Structure>
    <Attribute name="MIN" valueType="boolean" label="Min" />
    <Attribute name="MAX" valueType="boolean" label="Max" defaultValue="true"/>
    <Attribute name="SUM" valueType="boolean" label="Sum" defaultValue="false"/>
    <Attribute name="MEAN" valueType="boolean" label="Mean" defaultValue="false"/>
    <Attribute name="SDEV" valueType="boolean" label="SDev" defaultValue="false"/>
  </Structure>
</PropertyType>

Thus a property declared to use the aggregateOps property type might be:

<Property name="aggregationSettings" scriptName="aggregation_settings" type="aggregateOps"/>

Here the property consists of multiple values, each value having a different key. For example, the key name is the name of a field (MIN, MAX and so on).

In the next example of a keyed property type, each associated value is a structure containing a single attribute. In this case the attribute is a list of double-precision expressions representing multipliers to be applied to a field:

<PropertyType id="multiplierOps" isKeyed="true" valueType="structure">
  <Structure>
    <Attribute name="multipliers" valueType="double" isList="true"/>
  </Structure>
</PropertyType>

A property declared to use the multiplierOps property type might be:

<Property name="multiplierSettings" scriptName="multiplier_settings" type="multiplierOps"/>