Adding a Leaf to an Existing Node

From Apache OpenOffice Wiki
Jump to: navigation, search



Let us start with something simple and assume that we want to add a leaf under the "OpenOffice.org" writer node. The leaves and nodes, which we are talking about, appear in the tree view of the options dialog on the left side. A leaf has the meaning of an entry which cannot be expanded further. Selecting a leaf will cause the options page being displayed on the right side. Please do not confuse these node and leaves with the elements from the schema. The latter use uppercase names and the plural is indicated using a pipe symbol, such as "Node|s". There is also a xml element "node" in the xcu file. In case the meaning is unclear in the respective context, we will add small note.

The schema in the OptionsDialog.xcs defines two sets which we can add to. One contains Modules, which we do not need at the moment, and the other contains Nodes, which is the place we will add to. As the name suggest, it contains Nodes and not Leafs. But every Node contains a set of Leafs, which is named Leaves. This means, that we have to add a Leaf to the Leaves set of the writer Node. This is done by putting the following xcu file into the extension (do not forget to add the corresponding entry into the manifest.xml) .

<?xml version='1.0' encoding='UTF-8'?>
 
<oor:component-data oor:name="OptionsDialog" oor:package="org.openoffice.Office" 
  xmlns:oor="http://openoffice.org/2001/registry" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
  <node oor:name="Nodes">
    <node oor:name="Writer" oor:op="fuse">
      <node oor:name="Leaves">
        <node oor:name="org.openoffice.framework.desktop.test.deployment.options.leaf1" 
          oor:op="fuse">
          <prop oor:name="Id">
            <value>org.openoffice/framework/desktop/test/deployment/options/leaf1</value>
          </prop>
          <prop oor:name="Label">
            <value xml:lang="en-US">Writer leaf1 en-US</value>
          </prop>
          <prop oor:name="OptionsPage">
            <value>%origin%/dialogs/writer1/Writer1.xdl</value>
          </prop>
          <prop oor:name="EventHandlerService">
            <value>com.sun.star.comp.extensionoptions.DialogHandler</value>
          </prop>
        </node>
      </node>
    </node>
  </node>
</oor:component-data>

In the following examples I will leave out the xml, doctype and root element so we can focus on the relevant parts. In the previous example we see the lines:

<node oor:name="Nodes">
<node oor:name="Writer" oor:op="fuse">
<node oor:name="Leaves">

The first line represents the set Nodes. The second line shows that we add to the writer Node. And the last line represents the Leaves set within the writer Node. The names of Node|s should be unique, as we will see later. The name is the value of the oor:name attribute of the set entry. That is, there is no special property "name". The names for already existing Node|s and Module|s are rather short and are reserved exclusively for the office. The list of those names can be found here.

Currently the already existing nodes are not defined in the registry (but may be in future versions). Therefore, the node Writer, which is a set entry, may not exist yet, unless another extension has already added to this node. To make sure that there is this node we use the operation fuse. Leaves is the set within a Node (the type defined in the templates section of the schema) to which we add our leaf:

<node oor:name="Leaves">
  <node oor:name="org.openoffice.framework.desktop.test.deployment.options.leaf1" 
    oor:op="fuse">
    <prop oor:name="Id">
      <value>org.openoffice/framework/desktop/test/deployment/options/leaf1</value>
    </prop>
    <prop oor:name="Label">
      <value xml:lang="en-US">Writer leaf1 en-US</value>
    </prop>
    <prop oor:name="OptionsPage">
      <value>%origin%/dialogs/writer1/Writer1.xdl</value>
    </prop>
    <prop oor:name="EventHandlerService">
      <value>com.sun.star.comp.extensionoptions.DialogHandler</value>
    </prop>
  </node>
</node>

When we add to a set then we must provide a unique name for the oor:name attribute of the node element. We did this by calling it: org.openoffice.framework.desktop.test.deployment.options.leaf1

It is always good to use long names to ensure uniqueness. Starting with the reversed domain name is a good practice, because most developers or companies own a domain, which is already unique. Node names must use ASCII letters and special characters must be "xml encoded". That is signs, such as "<", ">", "&", etc must be replaced by "&lt;", "&gt;", "&amp;", etc. This is also valid for all other xml attribute values or the text between enclosing xml elements. Our leaf node also uses the fuse operator, to ensure that it is added to the set.

It is also useful to avoid "/" within oor:name. This will make it harder when using the API to access the values (see com.sun.star.container.XHierarchicalNameAccess). Then one need to encode the name in a particular way. See chapter Configuration Management.

The value of the property Id must be same as the extension identifier. The identifier is used to locate the leaves which belong to a particular extension. This happens when the options dialog is started in the Extension Manager. In this case only the entries for the selected extension are displayed.

The property Label contains the string which appears in the tree view. One can provide many different localized strings. However it is good to have at least an en-US string, which will be used as default in case there is no string which locale matches that of the office.

The property OptionsPage contains the URL to the xdl file of the dialog which shall appear when the user selects the corresponding entry in the tree view. Please note that it always starts with %origin% and is followed by the relative path to the file.

The property EventHandlerService contains the service name of the handler, which is also contained in the extension. One should take care to choose a unique name. It is not necessary to provide any IDL description or type library for the service.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages