Difference between revisions of "Documentation/DevGuide/Config/Preparing a Custom Configuration Schema"

Revision as of 12:53, 23 June 2010

A configuration data file is an XML file that conforms to the OOR Registry Update Format defined in http://util.openoffice.org/common/configuration/oor-document-format.html. Normally, configuration data files carry the extension .xcu.

A configuration data file contains changes to a configuration tree. When configuration data is read, an initial configuration tree is constructed from the component data described in the component schema. Then the configuration data files from all applicable layers are successively applied to this configuration tree. A layer is applied by applying the changes to the tree described by the data file while respecting any access control attributes and ensuring that the changes conform to the schema. Schema violations, like updates that specify a data type that disagrees with the type specified in the schema, are considered errors and result in complete failure to read the component.

As an example, consider data for a sample Addon component. For details about configuration for Addon components, see Configuration.

 <?xml version='1.0' encoding='UTF-8'?>
  <oor:component-data xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:name="Addons" oor:package="org.openoffice.Office">
      <node oor:name="AddonUI">
          <node oor:name="OfficeMenuBar">
              <node oor:name="org.openoffice.example.addon" oor:op="replace">
                  <prop oor:name="Title" oor:type="xs:string">
                      <value xml:lang="en-US">Add-On example</value>
                      <value xml:lang=”de”>Add-On Beispiel</value>
                  </prop>
                  <prop oor:name="Context" oor:type="xs:string">
                      <value>com.sun.star.text.TextDocument</value>
                  </prop>
                  <node oor:name="Submenu">
                      <node oor:name="m1" oor:op="replace">
                          <prop oor:name="URL">
                              <value>org.openoffice.Office.addon.example:Function1</value>
                          </prop>
                          <prop oor:name="Title">
                              <value xml:lang=”en-US”>Add-On Function 1</value>
                              <value xml:lang="de">Add-On Funktion 1</value>
                          </prop>
                          <prop oor:name="Target">
                              <value>_self</value>
                          </prop>
                      </node>
                  </node>
              </node>
          </node>
      </node>
  </oor:component-data>

The component-data root element of the configuration data XML corresponds to the component element of the associated schema. The elements of the update format do not reflect the distinction between set nodes and group nodes. All changes to structural nodes are expressed in the same way as simple node elements. Changes to property nodes use their own element tag. If a property has been declared as localized in the schema, the data file may contain different values for different locales. Changes may contain an operation attribute, which describes how the data is to be combined with preexisting data from the configuration tree, in order to obtain the result configuration data tree.

Changes also may contain access control attributes that restrict how the data can be overwritten by data in subsequent data layers. These access control attributes are not currently available directly through the configuration management API. But if a node in a default layer is protected from being overwritten by the user layer, the protection is reflected in the API by marking the corresponding node as read-only or non-removable.

Configuration data must be imported or installed into the backend to be effective.