Chapter 3 Advanced Templates

The chapter provides information about building and using more complex templates.

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.

Action Handlers

An action handler is used to execute user-defined actions whenever an event occurs. At the point, only one action handler is available: the XML handler, which generates JavaScript code in the client-side browser.

The XML handler can be used to implement a feature of the StarOffice/ OpenOffice Proxy dialog not yet covered by the templates presented so far: selecting the value "None" for the "Proxy server" setting disables the edit fields.

The annotated areas in the following template show the necessary changes in the original "Hello, world!" template in order to enable or disable the edit fields if the "Proxy server" setting is set to "Manual" or "None":

<?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="Settings">
          <property apt:name="ProxyServer" apt:label="Proxy Server"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetProxyType"
                    oor:type="xs:int"
           <!-- The following line should be added to original "Hello, world!" template -->
                    apt:xmlHandler="switchState">
            <visual apt:type="radioButtons"/>
            <constraints>
              <enumeration oor:value="0" apt:label="None"/>
              <enumeration oor:value="2" apt:label="Manual"/>
            </constraints>
          </property>
          <property apt:name="HTTPProxy" apt:label="HTTP Proxy"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyName"
                    oor:type="xs:string"/>
          <property apt:name="HTTPPort" apt:label="HTTP Port"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyPort"
                    oor:type="xs:int"/>
          <property apt:name="FTPProxy" apt:label="FTP Proxy"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetFTPProxyName"
                    oor:type="xs:string"/>
          <property apt:name="FTPPort" apt:label="FTP Port"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetFTPProxyPort"
                    oor:type="xs:int"/>
          <property apt:name="NoProxyFor" apt:label="No Proxy For"
                    apt:dataPath="org.openoffice.Inet/Settings/ooInetNoProxy"
                    oor:type="xs:string"/>
        </section> 
<!-- Beginning of section to be added to original "Hello, world!" template -->
        <xmlHandler apt:name="switchState"> 
          <event apt:type="onChange" />
          <action>
            <choose>
              <when apt:test="ProxyServer.value=0">
                <command>HTTPProxy.enabled=false</command>
                <command>HTTPPort.enabled=false</command>
                <command>FTPProxy.enabled=false</command>
                <command>FTPPort.enabled=false</command>
                <command>NoProxyFor.enabled=false</command>
              </when>
              <otherwise>
                <command>HTTPProxy.enabled=true</command>
                <command>HTTPPort.enabled=true</command>
                <command>FTPProxy.enabled=true</command>
                <command>FTPPort.enabled=true</command>
                <command>NoProxyFor.enabled=true</command>
              </otherwise>
            </choose>
          </action>
        </xmlHandler> 
<!-- End of section to be added -->      
      </page>
    </category>
  </category>
</apt:template>

By adding the apt:xmlHandler attribute to the property ProxyServer, you associate the xmlHandler element with the same name (here: "switchState") to that property.

Action handlers are triggered by events. Which events are considered by an action handler is defined by the apt:type attribute of the event element. At this point, there is only one event available: the onChange event. This event is thrown when a user enters new data for a property. In the preceding example, the event is used to trigger the XML handler when the value of the ProxyServer property changes.

The action element contains the actions that are executed if any of the events specified by the event element occur. In the preceding example, the first action is to check the value of the ProxyServer property and to change the state of the other edit fields accordingly. This is achieved by using the choose, when and otherwise elements. All edit fields are disabled, if the ProxyServer property is set to "None". The edit fields are enabled, if the ProxyServer property is set to "Manual".

Help

There are two different types of help: the online help and the inline help.

The online help is a detailed, context-sensitive help that is displayed in a new window when the user clicks the Help link in the masthead. If the last action was taken in the Content Area, the online help document defined in the template currently displayed in the Content Area is shown. If the last action was taken somewhere else, the general online help is shown. The apt:onlineHelp attribute of the page element is used to bind the HTML help file to a template. You need to specify the fully qualified path to the file and its base name, for example,

<page apt:name="Proxy">
      apt:label="Proxy"
          <apt:onlineHelp="/StarOffice/Internet/proxy">

references ./web/StarOffice/Internet/proxy.html.

You can use absolute and relative paths in HTML files. If you place an image in a directory that is called images, alongside of the HTML file, any of the following notations can be used in the HTML file:

• <img src="/StarOffice/Internet/images/image.gif">

• <img src="./images/image.gif">

The inline help is a brief text providing additional information for category, page and property pages. The inline help is displayed in the "Comment" column for a category element, below the page title for a page element and below the configuration setting for a property element. The help text is specified by the apt:inlineHelp attribute of any of the three elements category, page or property. For example,

<property apt:name="HTTPProxy" 
          apt:label="HTTP Proxy"
          apt:inlineHelp="Specify no proxy (None) or a manually defined proxy (manual)."
          apt:dataPath="org.openoffice.Inet/Settings/ooInetHTTPProxyName"
          oor:type="xs:string"
</property>

You should provide resource keys for the label to facilitate localization.