Sets

After creating the "Hello, World!" template presented in Chapter 2, Templates, you might need to make the list of configurable proxies dynamic. A dynamic list enables users to add proxies for additional protocols like GOPHER, SOCKS, and SSL . Sets enable you to accomplish this task.

The use of sets for the proxy page is for demonstration purposes only. Neither StarOffice nor OpenOffice can handle this example, because their implementation expects the original layout of the configuration tree.

Figure Figure 3–1 depicts a dynamic list of proxies instead of using a fixed number of edit fields:

Figure 3–1 Dynamic proxy set

Proxies are added if you click on the New button. A dialog prompts for the name of the new protocol to use a proxy for. Specify FTP the first time, then click New again and type HTTP as the name for the second protocol. The result looks likeFigure 3–1. The two entries are links. If you click on one of the links, the Content Area is loaded with the content that you see in Figure 3–2:

Figure 3–2 Proxy set sub-page

The functionality described in the two preceding figures is implemented by modifying the "Hello, world!" example as follows: Delete the four properties HTTPProxy, HTTPPort, FTPProxy, and FTPPort. Then add a set element, as seen in the annotated section in the following code example:

<?xml version="1.0" encoding="UTF-8"?>
<DOCTYPE apt:template SYSTEM "policytemplate.dtd">
<apt:template>
  <category apt:name="StarOffice" apt:label="StarOffice">
    <category apt:name="Internet" apt:label="Internet">
      <page apt:name="Proxy" apt:label="Proxy">
        <section apt:name="Settings" apt:label="Proxy Server">
          <property apt:name="ProxyServer" apt:label="Proxy Server"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyType"
                    oor:type="xs:int">
            <visual apt:type="radioButtons"/>
            <constraints>
              <enumeration oor:value="0" apt:label="None"/>
              <enumeration oor:value="2" apt:label="Manual"/>
            </constraints>
          </property>
          <property apt:name="NoProxyFor" apt:label="No Proxy For"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetNoProxy"
                    oor:type="xs:string"/>
        </section>
<!-- Beginning of set element to be added -->
        <set apt:name="ProxyList" apt:label="Proxy List" 
             apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyList">
          <page apt:name="ProxyPage" apt:label="Proxy">
            <section apt:name="Proxy" apt:label="Host and Port">
              <property apt:name="HostName" apt:label="Host Name" 
                        apt:dataPath="./$queriedId/HostName"
                        oor:type="xs:string"/>
              <property apt:name="Port" apt:label="Port" 
                        apt:dataPath="./$queriedId/Port"
                        oor:type="xs:string"/> 
            </section>    
          </page>    
        </set> 
<!-- End of added set element -->        
      </page>
    </category>
  </category>
</apt:template>

The apt:dataPath attribute of the set element points to the place where the set is stored in the back end. The set element contains a page element, which contains a section element, which in turn contains a property element. This hierarchy correlates to the element hierarchy below a category element. It is rendered as a page in the same way, except that it is triggered by clicking the link in the set table.

In comparison to a category page, the set page properties HostName and Port use a special notation for the apt:dataPath. The path begins with a dot, meaning that the path is relative to the first path definition found ascending the element hierarchy. The first parent element with anapt:dataPath is the set element, so the Configuration Manager translates the relative path of, for example, the Port property to org.openoffice.Inet/Settings/ooInetProxyList/$queriedId/Port. The other peculiarity in this path is the $queriedId variable. Since all data in the configuration repository needs to be uniquely identified, every element in a dynamic data structure needs to have a unique name. The $queriedId variable instructs the Configuration Manager to query the user for that name when the Add button is clicked. The resulting set element is stored with the specified name at the position determined by the position of the variable. Therefore, in the case of the FTP set element, the path to its port property is org.openoffice.Inet/Settings/ooInetProxyList/FTP/Port.

Another example: You can also use sets to display the NoProxyFor property. If the string of host names becomes long, the use of an edit field for this property can be problematic. Users then need to scroll to view the entire string in the edit field. A list of proxy names that are implemented with a set avoids that extra scrolling.

To use a set instead of a string for the NoProxyFor property, delete the NoProxyFor element with all its sub-elements. Then add the set element that is shown in annotated section in the following code example:

<?xml version="1.0" encoding="UTF-8"?>
<DOCTYPE apt:template SYSTEM "policytemplate.dtd">
<apt:template>
  <category apt:name="StarOffice" apt:label="StarOffice">
    <category apt:name="Internet" apt:label="Internet">
      <page apt:name="Proxy" apt:label="Proxy">
        <section apt:name="Settings" apt:label="Proxy Server">
          <property apt:name="ProxyServer" apt:label="Proxy Server"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyType""
                    oor:type="xs:int">
            <visual apt:type="radioButtons"/>
            <constraints>
              <enumeration oor:value="0" apt:label="None"/>
              <enumeration oor:value="2" apt:label="Manual"/>
            </constraints>
          </property>
        </section>
<!-- Beginning of set element to be added -->
        <set apt:name="NoProxyFor" apt:label="No Proxy For" 
             apt:dataPath="org.openoffice.Inet/Settings/ooInetNoProxySet">
          <page apt:name="HostNamePage">
            <section apt:name="HostNameSection">
              <property apt:name="HostNameProp"
                        apt:dataPath="./$queriedId/HostName" oor:type="xs:string"
                        apt:storeDefault="true">
                <visual apt:type="hidden"/>
                <value>$queriedId</value>
              </property>
            </section>
          </page>
        </set> 
<!-- End of set element to be added -->
        <set apt:name="ProxyList" apt:label="Proxy List"
             apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyList">
          <page apt:name="ProxyPage" apt:label="Proxy">
            <section apt:name="Proxy" apt:label="Host and Port">
              <property apt:name="HostName" apt:label="Host Name" 
                        apt:dataPath="./$queriedId/HostName"
                        oor:type="xs:string"/>
              <property apt:name="Port" apt:label="Port" 
                        apt:dataPath="./$queriedId/Port"
                        oor:type="xs:string"/> 
            </section>    
          </page>    
        </set> 
      </page>
    </category>
  </category>
</apt:template>

Figure 3–3 Proxy Set — “No Proxy For”

The entries in the table are no longer links, but rather the entries represent a flat list of single-valued elements. This is achieved by using the apt:storeDefault attribute and the visual element in combination with the value element. The value element can define a default value for a configuration setting. A default value is not stored in the configuration repository by default. The apt:storeDefault attribute instructs the Configuration Manager to override that default and to automatically store the default value in the back end. In this case, the default value is the value that the user enters in the dialog when a new set element is added. If the apt:type attribute of the visual element is specified as "hidden", the only section in that page is left empty. If a set page is empty, it makes no sense to display the page, so the Configuration Manager does not provide a link.