Java Desktop System Configuration Manager Release 1.1 Developer Guide

Appendix B Element Dictionary

This appendix provides a reference description for every element and attribute possible in a template.

Header Elements: apt:template, resImport, helpImport

<!ELEMENT apt:template (resImport*, category)>
<!ATTLIST apt:template
    xmlns:apt CDATA #FIXED "http://www.sun.com/jds/apoc/2004/template"
    xmlns:oor CDATA #FIXED "http://openoffice.org/2001/registry"
    xmlns:xs  CDATA #FIXED "http://www.w3.org/2001/XMLSchema"
    xmlns:xsi CDATA #FIXED "http://www.w3.org/2001/XMLSchema-instance"
>

<!ELEMENT resImport EMPTY><!ATTLIST resImport
    apt:packagePath NMTOKEN #REQUIRED
>

The root element template has two sub-elements: resImport and category, which are described in Structure Elements: category, page, section.

The resImport element is used to import resource files. All resource keys of the imported resource bundle are announced to the template. You have to import the resource to use its resource keys in, for example, the apt:label attributes. See Structure Elements: category, page, section. The apt:packagePath attribute specifies the location of the resource file using a path. The delimiter is a dot ("."). The file postfix (.properties) must not be specified, as well as the ISO language code (ISO-639) and the ISO country code (ISO 3166). The root directory of the path is the res directory located below the package directory. See also Localization.

Structure Elements: category, page, section

<!ELEMENT category (category | page)>
<!ATTLIST category
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
>
<!ELEMENT page ((section | set)+, xmlHandler*)><!ATTLIST page
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:inlineHelp NMTOKEN #IMPLIED
    apt:onlineHelp CDATA #IMPLIED
>
<!ELEMENT section (property+)>
<!ATTLIST section
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
>

The category element is used to define the unique position of a page in the configuration policy tree. Its first attribute is the apt:name attribute. The name attribute is used to define a unique name for an element. It facilitates better orientation in large templates and referencing elements.

The second attribute of the category element is apt:scope. The scope attribute specifies to which tree the configuration setting can be applied. If the scope is "user", the configuration setting is applied to the organization tree only. If the scope is "host", the configuration setting is applied to the domain tree only. If the scope is "global", the configuration setting is applied to both trees. The default setting is "global". The elements inherit the scope from their parent elements, except if an element defines its own scope. If an element has a "user" scope and a configuration policy tree attached to a domain tree is displayed in the Content Area, that element is not displayed to the user. The same holds true if an element has "host" scope and a configuration policy tree attached to an organization tree is displayed.

The third attribute of the category element is apt:label. The label attribute specifies the name of the element displayed to the user and supports localization. The string specified by the label attribute is searched in the resource bundles first. If a key matching the string is found, its value is displayed on the GUI. If the string has no matching key in any of the resource bundles, the string itself is displayed on the GUI. If no label attribute is specified, the string specified by the name attribute is rendered in the GUI. If both attributes are not defined, no output is rendered.

The fourth attribute of the category element is apt:inlineHelp. The inlineHelp attribute specifies the help text displayed on the GUI. The help is displayed to the right of the category names in the "Comment" column. It supports localization in the same manner as the label attribute described in the preceding paragraph.

There is exactly one page element at the end of a category hierarchy. This element represents one option page. It contains four attributes recognized by the category element: name, scope, label, and inlineHelp. The value of the inlineHelp attribute is displayed below the page title. The value of the label attribute is displayed as the page title. The category and page names define the unique location and name of a page in the configuration policy tree.

The apt:onlineHelp attribute is used to make the HTML file containing the online help available to the Configuration Manager. The HTML page referred to by this element is displayed as context-sensitive help if the user clicks the Help link in the masthead of the Configuration Manager. The apt:filePath attribute specifies the location of the help file using a path. The delimiter is a forward slash ("/"). The file postfix (.html) must not be specified, as well as the ISO language code (ISO-639) and the ISO country code (ISO 3166). The root directory of the path is the web directory located below the package directory. See also Localization.

A page can contain an arbitrary number of sections or sets, followed by an optional list of xmlHandlers. Thus the page element contains the sub-elements section, set (see Dynamic Data Elements: set) and xmlHandler (see Interaction Elements: xmlHandler, event, action, choose, command).

The section element creates a visual group of all its property sub-elements in a table-like layout. It contains four attributes recognized from the category element: name, scope, and label. The value of the label attribute is displayed as the section title.

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:

xs:boolean	Boolean value (true/false)
xs:short	16 - bit integer number
xs:int	32 - bit integer number
xs:long	64 - bit integer number
xs:double	Floating point number (value range as for IEEE 64-bit double)
xs:string	Plain Text (Sequence of printable Unicode characters)
xs:hexBinary	Sequence of uninterpreted octets, hex encoded
oor:any	Encompasses all of the types mentioned previously
oor:*-list	List of any of the typed mentioned previously

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:

In front of the checkbox. This string is defined in the label attribute of the property element.
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.
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.
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.

Tip –

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.

Dynamic Data Elements: set

<!ELEMENT set (page)>
<!ATTLIST set
    apt:name ID #REQUIRED
    apt:scope (user | host | global) #IMPLIED
    apt:label NMTOKEN #IMPLIED
    apt:labelPopup NMTOKEN #IMPLIED
    apt:dataPath CDATA #REQUIRED
    apt:elementNamePath CDATA #IMPLIED
>

Up to now, all elements handled static back-end content. The set element is used to handle dynamic content. It is, like the section element, a sub-element of a page and displays sets of properties in a table.

It contains three attributes recognized by the category element: name, scope and label. The value of the label attribute is displayed as the table title.

The apt:dataPath attribute defines a path that points to the data back-end node that contains the set of elements. The value of the dataPath attribute is an absolute path in the form of org.openoffice.Office.Commands/Execute/Disabled (see AppendixAppendix A, Configuration Path Mapping) . The dataPath attribute of a set element must point to a back-end node. Pointing to a back-end property yields an error.

The dataPath attributes of descendants of the set must contain a dynamic part. This dynamic part specifies the location of the back-end nodes that are set members. The name of any back-end set member must be different to allow access to that member. To achieve this, variables are used.

Variables are prefixed with a dollar symbol: $variable_name. Valid variable names are queriedId and silentId. If the $queriedId variable is specified, the Configuration Manager displays an additional edit field that queries the user for a unique id. If the $silentId variable is specified, no ID is queried form the user; the Configuration Manager generates the unique IDby itself.

For example: The dataPath attribute of a property element has the value org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command. If the user creates a new set element, the user is additionally asked for the name of the set member. The concrete question string displayed on the GUI is specified by the apt:labelPopup attribute. If this attribute is omitted, the prompt Please enter a name for the new entry. is displayed.

It is possible to specify a relative path as the value of the dataPath attribute of sets or properties to minimize the length of the path strings. An example of a relative path is ./$queriedId/Command. The absolute path is constructed by ascending the template element tree and prefixing the relative path with the dataPaths of its ancestors, until an absolute path is constructed. Assuming the parent of a property is a set. This set specifies the dataPath value org.openoffice.Office.Commands/Execute/Disabled. The Configuration Manager combines this path with the relative path ./$queriedId/Command, resulting in the absolute path org.openoffice.Office.Commands/Execute/Disabled/$queriedId/Command.

It is not necessary to specify a dataPath attribute for the set, if all descendants of the set that support the dataPath attribute (set and property elements), specify an absolute path as the value of their dataPath attribute.

Recursive set structures (sets of sets) can also be handled. This is accomplished by having a set element containing a page element, which contains a set element again. The dataPath attribute of the sub set can specify a path relative to the super set.

If a set member is a back-end property, the value of the oor:name attribute of the back-end property is displayed as the label in the GUI. The value of the back-end property is displayed as the value of the GUI element.

If a set member is a back-end node, the value of the oor:name attribute of the back-end node is displayed as the name of the link. You can use the apt:elementNamePath attribute to override this naming scheme. The elementNamePath specifies a path relative to the back-end node. The path must point to a back-end property and its value is displayed as the name of the link. If the user clicks on such a link, the Content Area is refreshed, displaying the page specified by the page sub-ement of the set.

Interaction Elements: xmlHandler, event, action, choose, command

<!ELEMENT xmlHandler (event+, action+)>
<!ATTLIST xmlHandler apt:name ID #REQUIRED>

<!ELEMENT event EMPTY>
<!ATTLIST event apt:type (onChange) #IMPLIED>

<!ELEMENT action (choose|command)+>

<!ELEMENT choose (when+, otherwise?)>

<!ELEMENT when (command+)>
<!ATTLIST when apt:test CDATA #REQUIRED>

<!ELEMENT otherwise (command+)>

<!ELEMENT command (#PCDATA)>

The xmlHandler element is used to execute JavaScript code on the client side. The code execution is triggered depending on changes in the environment. These changes are propagated by events. Events are thrown by properties if their state changes. The type of an event indicates the type of the change.

An XML handler is defined by specifying the xmlHandler sub-element of the apt:template element. It requires a name defined by the apt:name attribute. An XML handler is registered to listen for events thrown by a property by specifying the apt:xmlHandler attribute of the property element using the name of the XML handler as its value.

The event element is used to specify the events the xmlHandler listens to by using its apt:type attribute. For now, only the onChange element is defined. This event is thrown by a property if its value is changed by the user. The value of a property changes atthe very moment the user changes its input, for example, by typing a key in an edit field, by deselecting a checkbox, or by choosing an entry in a list box. Moving the focus to, or removing the focus from, a GUI element does not trigger this event.

If a handler has registered for an event at one or more properties, and that event occurs for one of these properties, the code defined in the action element is executed. The action element contains at least one choose or command element.

A command element specifies the instructions to be executed on the client side. It can (up to now) contain assignments only. There are no calculations allowed, either on the left-hand side or the right-hand side of the assignment. Assignments obey the scheme: <variable>=<value>.

Variables follow a dotted notation: <property>.<qualifier>. The <property> must be the name of a property. The <qualifier> can have two values: “value” and “enabled”. The value qualifier denotes the value of that property. The value of a variable can be read and set to any value, as long that value is compatible with the type specified for the property. The "enabled" qualifier contains "true" if the property is enabled (can receive the focus) and "false" otherwise. It can be read and set to "true" or "false". Example: propname.enabled=false.

The choose element is similar to the choose element defined in XSLT, and allows the conditional execution of commands. It must contain at least one when element and may contain one otherwise element at the end.

The when element has one or more command sub-elements and one apt:test attribute. The test attribute must specify an expression evaluating to a Boolean value.

An expression may consist of variables, numbers, strings, and the following tokens:

=	equal
!=	not equal
<	less than
>	greater than
<=	less than or equal to
>=	greater than or equal to
( )	parentheses
not()	Boolean NOT
and	Boolean AND
or	Boolean OR
true	Boolean positive
false	Boolean negative

Example: (propname.enabled!=false) and not(propname.value='foo').

If the expression evaluates to "true", the commands of the when element are executed and the choose statement is performed if it evaluates to "false" the next when element is evaluated. If none of the when elements is true and there is an otherwise element specified, the otherwise element commands are executed.