Sun Desktop Manager 1.0 Developer Guide

Interaction Elements: xmlHandler, event, action, choose, command

<!ELEMENT xmlHandler (event+, action+)>
<!ATTLIST xmlHandler apt:name ID #REQUIRED>

<!ELEMENT event EMPTY>
<!ATTLIST event apt:type (onChange) #IMPLIED>

<!ELEMENT action (choose|command)+>

<!ELEMENT choose (when+, otherwise?)>

<!ELEMENT when (command+)>
<!ATTLIST when apt:test CDATA #REQUIRED>

<!ELEMENT otherwise (command+)>

<!ELEMENT command (#PCDATA)>

The xmlHandler element is used to execute JavaScript code on the client side. The code execution is triggered depending on changes in the environment. These changes are propagated by events. Events are thrown by properties if their state changes. The type of an event indicates the type of the change.

An XML handler is defined by specifying the xmlHandler sub-element of the apt:template element. It requires a name defined by the apt:name attribute. An XML handler is registered to listen for events thrown by a property by specifying the apt:xmlHandler attribute of the property element using the name of the XML handler as its value.

The event element is used to specify the events the xmlHandler listens to by using its apt:type attribute. For now, only the onChange element is defined. This event is thrown by a property if its value is changed by the user. The value of a property changes atthe very moment the user changes its input, for example, by typing a key in an edit field, by deselecting a checkbox, or by choosing an entry in a list box. Moving the focus to, or removing the focus from, a GUI element does not trigger this event.

If a handler has registered for an event at one or more properties, and that event occurs for one of these properties, the code defined in the action element is executed. The action element contains at least one choose or command element.

A command element specifies the instructions to be executed on the client side. It can (up to now) contain assignments only. There are no calculations allowed, either on the left-hand side or the right-hand side of the assignment. Assignments obey the scheme: <variable>=<value>.

Variables follow a dotted notation: <property>.<qualifier>. The <property> must be the name of a property. The <qualifier> can have two values: “value” and “enabled”. The value qualifier denotes the value of that property. The value of a variable can be read and set to any value, as long that value is compatible with the type specified for the property. The "enabled" qualifier contains "true" if the property is enabled (can receive the focus) and "false" otherwise. It can be read and set to "true" or "false". Example: propname.enabled=false.

The choose element is similar to the choose element defined in XSLT, and allows the conditional execution of commands. It must contain at least one when element and may contain one otherwise element at the end.

The when element has one or more command sub-elements and one apt:test attribute. The test attribute must specify an expression evaluating to a Boolean value.

An expression may consist of variables, numbers, strings, and the following tokens:

equal 

!= 

not equal 

&lt; 

less than 

&gt; 

greater than 

&lt;= 

less than or equal to 

&gt;= 

greater than or equal to 

( ) 

parentheses  

not() 

Boolean NOT 

and 

Boolean AND 

or 

Boolean OR 

true 

Boolean positive 

false 

Boolean negative 

Example: (propname.enabled!=false) and not(propname.value='foo').

If the expression evaluates to "true", the commands of the when element are executed and the choose statement is performed if it evaluates to "false" the next when element is evaluated. If none of the when elements is true and there is an otherwise element specified, the otherwise element commands are executed.