Java Desktop System Configuration Manager Release 1.1 Developer Guide

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".