Basic Data Elements: property, value, constraints

<!ELEMENT property (constraints?, value*, visual)>
<!ATTLIST property
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    oor:type (xs:boolean | xs:short | xs:int | xs:long | xs:double | 
              xs:string | xs:hexBinary |
              oor:any | oor:boolean-list | oor:short-list | oor:int-list | 
              oor:long-list | oor:double-list | oor:string-list | oor:hexBinary-list)
              #IMPLIED
    apt:storeDefault (true | false) #IMPLIED
    apt:xmlHandler IDREF #IMPLIED
    apt:extendsProperty CDATA #IMPLIED
>
<!ELEMENT visual (checkBox | chooser)?>
<!ATTLIST visual
 apt:type (textField | password | textArea | radioButtons | comboBox | stringList | 
           colorSelector | hidden) #IMPLIED
>

<!ELEMENT checkBox EMPTY>
<!ATTLIST checkBox
 apt:labelPost NMTOKEN #IMPLIED
>

<!ELEMENT chooser EMPTY>
<!ATTLIST chooser
 apt:labelPopup NMTOKEN #IMPLIED
 apt:listDataPath CDATA #IMPLIED
 apt:extendsChooser CDATA #IMPLIED
>
<!ELEMENT constraints (enumeration*, length?, minLength?, maxLength?, minInclusive?, 
                       maxInclusive?, minExclusive?, maxExclusive?)>
<!ELEMENT enumeration EMPTY>
<!ATTLIST enumeration 
    oor:value CDATA #REQUIRED
    apt:label NMTOKEN #IMPLIED
>
<!ELEMENT value (#PCDATA)>
<!ATTLIST value
    xsi:nil (true | false) #IMPLIED
    oor:separator CDATA #IMPLIED
>

The property element provides the visualization of configuration settings by way of GUI elements, such as checkboxes, radio buttons, and edit fields. It contains four attributes recognized by the category element: name, scope, label and inlineHelp. The inline help is displayed below the input fields (or in non-editable appearance below the value string) in the "value" column. The value of the label attribute is displayed as the label of the GUI elements. The category, page, section and property names define the unique location and name of a page in the configuration policy tree.

The attribute apt:dataPath defines a path that points to the location in the data back end that stores the value of the property. The value of the dataPath attribute is an absolute component path, for example, org.openoffice.Office.Common/ExternalMailer/Program. See Appendix A, Configuration Path Mapping. The dataPath attribute of a property element must point to a data back-end property. Pointing to a data back-end node yields a runtime error.

The apt:type is used to specify the type of the repository configuration data. The following types are defined:

These types resemble the types defined in the StarOffice/OpenOffice registry (OOR) format. Wherever possible, the APOC templates use the syntax of the OOR format for the sake of reusability. For more information on types, use the OpenOffice.org Registry Format (OOR) documentation at http://util.openoffice.org/common/configuration/oor-document-format.html

The attribute apt:storeDefault instructs the Configuration Manager to store the default data in the data back end. The default data is defined by the value element (see below) and used to display the default to the user. If the user doesn't change the value or explicitly requests storing the default data by executing the "Apply Default" action in the Content Area, the default data is not stored in the repository. By setting the value of the storeDefault attribute to true, the default data is stored even if the user does not change the value or executes "Apply Default".

A property element has three sub-elements: constraints, value and visual.

The visual element defines the visual type of the property on the GUI. The following visual types are recognized: checkBox, radioButtons, comboBox, stringList, textField, password, textArea, chooser, colorSelector and hidden. Every GUI element has two appearances: editable and non-editable. The non-editable appearance is rendered if the administrator using the Configuration Manager has no write privileges for that property. See the following table for the visual appearances of the visual types:

Visual type	Editable appearance	Non-editable appearance
textField
password
textArea
checkBox
radioButtons
comboBox
chooser
stringList
colorSelector

The hidden property does not render a visual GUI element, but passes the value associated with the property to the browser in a hidden field. This feature proves useful, for example, if one value entered on the front-end has to be saved at more than one location in the back end.

The visual type is defined by the apt:type attribute of the visual element. There are two exceptions: checkBox and chooser. These two GUI elements need additional information in order to be displayed correctly, so they have their own sub-elements containing this information.

The checkbox property displays strings before and after the checkbox. It is represented by the checkBox element. Two additional strings are needed for displaying the checkBox GUI element in the non-editable appearance (see previous table). As a result, a checkBox GUI element needs four strings, which are displayed as follows:

1. In front of the checkbox. This string is defined in the label attribute of the property element.

2. After the checkbox. This string is defined in the apt:labelPost attribute of the checkBox sub-element. If that attribute is not defined, ".post" is appended to the string defined in the label attribute. This string is searched as key in the resource files.

3. Instead of a checked checkbox, if the checkbox is rendered in the non-editable appearance. The string is defined in the label attribute of the first enumeration sub-element of the constraints element. If no constraints are given, the postfix ".checked" is appended to the string defined in the label attribute of the property element. This string is searched as key in the resource files.

4. Instead of an unchecked checkbox, if the checkbox is rendered in the non-editable appearance. The string is defined in the label attribute of the second enumeration sub-element of the constraints element. If no constraints are given, the postfix ".unchecked" is appended to the string defined in the label attribute of the property element. This string is searched as key in the resource files.

The chooser property enables a value from a list of entries to be set. It is represented by the chooser element. In contrast to a combobox, the list of entries is editable. This list is stored in the back end at the location specified by the apt:dataPath attribute of the chooser element.

When the Edit button is clicked, a pop-up window opens, which provides a GUI for editing the list. The title of the content of the pop-up window is defined by the apt:labelPopup attribute of the chooser element. You can specify default values for the list by using the enumeration sub-element of the constraints element (see the paragraph dealing with the constraints below).

The apt:extendsChooser property of the chooser element is used to refer to another chooser element. This eases the reuse of previously defined chooser elements. All elements and attributes defined in that referred chooser are interpreted as if they were defined in the referring chooser. Sub-elements and attributes that are defined in the referring chooser overwrite elements and attributes of the chooser referred to. A property path is used to locate the referred chooser. A property path is a concatenation of the apt:name values of every element on the path from the root category to a property, delimited by forwards slashes ("/"). For example: /StarOffice/Internet/Proxy/Settings/MyChooser.

If the visual type is not specified, the GUI element used is derived from the type attribute. If the type is xs:boolean, a checkbox is used. If the type is a list type (e.g., oor:short-list), xs:hexBinary or oor:any, a text area is rendered. For all other types, an edit field is used. If neither the visual type nor the data type are specified, an edit field is rendered and the back-end data type is assumed to be xs:string.

The constraints element provides restrictions for the input fields. For example, if you want to allow a user to save only integer values between 1 and 5, providing an oor:type attribute with the value "xs:int" is not sufficient. You can specify the required restriction by specifying a minInclusive constraint of 1 and a maxInclusive constraint of 5.

There is a second application for the enumeration constraint if used with a checkbox property. The first enumeration constraints sub-element defines the value stored in the back end if the checkbox is checked, the second enumeration constraints sub-element defined the value stored in the back end if the checkbox is unchecked. If no constraint is given, the default values stored are true and false. The default strings displayed on the GUI in the non-editable appearance are "Enabled" and "Disabled".

The enumeration constraint has the same semantics for radiobutton and combobox properties as for checkbox properties, except that it is mandatory. The content of these elements is completely up to the developer. The name displayed on the GUI is defined by the label attribute of the constraint element. It is possible to omit the label attribute in the enumeration constraint. In that case the additional resources are specified by postfixes appended to the string defined in the label attribute of the property element.

For example, assume a drop-down box, whose property label is "securityList" and whose enumeration constraints contain the values "1", "2" and "3" but the enumeration constraint labels are not defined. The strings displayed to the user are determined by searching the resources keys "securityList.1", "securityList.2" and "securityList.3" respectively.

The list entries of chooser properties are not localized. As a consequence the apt:label attribute of the enumeration constraint has no effect on these properties.

For a complete discussion of the other constraints, see the Property Constraints section of the OpenOffice.org Registry Format (OOR) documentation.

The value element contains the default value for the property. This default value may be the same value contained in the default stratum, or it may be introduced at this point. It defines the value that is displayed by the Configuration Manager if no data can be found in the data back end.

The definition of the value element is similar to the definitions given in the OOR format. The value element has no sub-elements, but rather three attributes: nil, separator and lang. If the xsi:nil attribute is set to true, the value of the property is defined as "has no value". The oor:separator attribute is used to specify the string that is used as separator for list tokens, if the value element contains list type values.

The list entries of stringList properties are stored as value of type oor:string-list. The default separator is a semicolon (";").

For the apt:xmlHandler attribute, refer to Interaction Elements: xmlHandler, event, action, choose, command.