Creating a Custom Configuration Schema

OpenOffice.org Developer's Guide

Configuration Management

< Previous Section

Next Section >

• Object Model
• Configuration Data Sources

• Connecting to a Data Source
• Using a Data Source

• Reading Configuration Data
• Updating Configuration Data
• Customizing Configuration Data

• Creating a Custom Configuration Schema
• Preparing a Custom Configuration Schema
• Installing a Custom Configuration Schema

< Previous Page

Next Page >

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

Not all schemas that can be described using the OOR Registry Component Schema Format are accepted by the current version of Apache OpenOffice. In particular support for extensible nodes is limited: Only group nodes that otherwise contain no child elements may be marked as extensible. Such nodes are represented as set nodes having property elements in the API.

As an example, consider the schema of the rg.openoffice.Office.Addons component. For details about configuration for Addon components, see Configuration.

  <?xml version='1.0' encoding='UTF-8'?>
  <oor:component-schema oor:name="Addons" oor:package="org.openoffice.Office" xml:lang="en-US" xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <templates>
          <group oor:name="MenuItem">
              <prop oor:name="URL" oor:type="xs:string"/>
              <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>
              <prop oor:name="ImageIdentifier" oor:type="xs:string"/>
              <prop oor:name="Target" oor:type="xs:string"/>
              <prop oor:name="Context" oor:type="xs:string"/>
              <set oor:name="Submenu" oor:node-type="MenuItem"/>
          </group>
          <group oor:name="PopupMenu">
              <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>
              <prop oor:name="Context" oor:type="xs:string"/>
              <set oor:name="Submenu" oor:node-type="MenuItem"/>
          </group>
          <group oor:name="ToolBarItem">
              <prop oor:name="URL" oor:type="xs:string"/>
              <prop oor:name="Title" oor:type="xs:string" oor:localized="true"/>
              <prop oor:name="ImageIdentifier" oor:type="xs:string"/>
              <prop oor:name="Target" oor:type="xs:string"/>
              <prop oor:name="Context" oor:type="xs:string"/>
          </group>
          <group oor:name="UserDefinedImages">
              <prop oor:name="ImageSmall" oor:type="xs:hexBinary"/>
              <prop oor:name="ImageBig" oor:type="xs:hexBinary"/>
              <prop oor:name="ImageSmallHC" oor:type="xs:hexBinary"/>
              <prop oor:name="ImageBigHC" oor:type="xs:hexBinary"/>
              <prop oor:name=”ImageSmallURL” oor:type=”xs:string”/>
              <prop oor:name=”ImageBigURL” oor:type=”xs:string”/>
              <prop oor:name=”ImageSmallHCURL” oor:type=”xs:string”/>
              <prop oor:name=”ImageBigHCURL” oor:type=”xs:string”/>
          </group>
          <group oor:name="Images">
              <prop oor:name="URL" oor:type="xs:string"/>
              <node-ref oor:name="UserDefinedImages" oor:node-type="UserDefinedImages"/>
          </group>
          <set oor:name="ToolBarItems" oor:node-type="ToolBarItem"/>
      </templates>
      <component>
          <group oor:name="AddonUI">
              <set oor:name="AddonMenu" oor:node-type="MenuItem"/>
              <set oor:name="Images" oor:node-type="Images"/>
              <set oor:name="OfficeMenuBar" oor:node-type="PopupMenu"/>
              <set oor:name="OfficeToolBar" oor:node-type="ToolBarItems"/>
              <set oor:name="OfficeHelp" oor:node-type="MenuItem"/>
          </group>
      </component>
  </oor:component-schema>

The schema has an XML root node that contains two parts, a list of template definitions and a definition of the component tree. The root node also declares XML namespaces that are used within the schema. Template definitions describe configuration tree fragments, which can be reused within the schema by reference or as element type of set nodes. In the case of set elements they serve as blueprints from which new instances of set items are built by the configuration management API components. Templates can either be group nodes or set nodes. The component part describes the actual data tree of the component. The component node is a special group node that represents the root of the component tree. Both parts are optional in the schema definition. A schema may provide only templates for reuse by other components, or it may describe only a component tree without defining any templates of its own.

The tree structure is built from group nodes, set nodes. Properties are represented as prop nodes. The XML elements contain the information necessary to identify the node and its type as attributes. They may further contain extra child elements that contain human-readable descriptions of the node or that specify constraints on the permissible or meaningful values of properties. Property elements may also contain a default value.

A schema must be installed into the backend to be usable. Once a schema is installed the component it describes can be accessed through the configuration management API. An installed schema is assumed to not change anymore.

Known Issues regarding schema handling

• Reinstallation of an addon does not activate the new version completely.

Content on this page is licensed under the Public Documentation License (PDL).