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.