Balisage Paper: Interactivity Three Ways

Background

When a conference is an in-person event at a particular location, there’s relatively little ambiguity in the schedule. If the clock on the wall at breakfast reads 9:45am and the first talk is scheduled for 10:00am, you have fifteen minutes.

The schedule for a virtual conference with attendees in many different time zones is another matter. In principle, you can publish the schedule in a single time zone and everyone can add or subtract the necessary offset to get “local time”. If the first talk is scheduled for 10:00am, in Rockville, and the clock on the wall at breakfast reads 9:45am, you have fifteen minutes — if you are in Rockville, or anywhere else on Eastern Daylight Time. If the clock is on Mountain Time because it and you are located in Denver, you’ve missed that talk!

Ask anyone who has participated regularly in activities organized simultaneously across several time zones and they will tell you stories about when they got it wrong or their colleagues did.

It’s just easier if you can see the times in your time zone.

For Balisage 2020, Norm attempted to make the Balisage schedule interactive such that a user could pick a timezone and the “schedule at a glance” table would be updated so that it displayed the times of the talks translated into that timezone.

The challenge at that time was to see if this could be done using entirely native JavaScript APIs (no third party libraries allowed), in a relatively straightforward way, that would work on many modern browsers.

It turned out that a couple of decades into the twenty-first century, this was a quite practical task. The complete solution was achieved in just under 200 lines of code. (Lines of code is arguably a poor metric generally, but this gives a sense of the magnitude. You could just about squeeze the whole thing onto the front and back of a single sheet of paper and it would still be legible.)

This year, the challenge is to achieve the same results using Saxon-JS and XForms. Then we’ll examine how those solutions compare.

Constraints

The first and most significant constraint is that adding the interactive schedule must not change the editorial process for producing the schedule page in any significant way. This is a perfectly fair and reasonable constraint. There is an existing process and retraining everyone who updates that page is beyond the scope of this project.

Luckily, as we’ll see in the next section, the Balisage organizers understand the value of markup and the page is already structured for reuse. And we aren’t forbidden from making any changes to the markup on the page, only those that would significantly interfere with the editorial process.

There are two additional constraints that stem from our requirement not to change the editorial process:

The freedom we’ve given ourselves to make “insignificant” changes to the page allows us to configure the schedule-at-a-glance table so that it will be easier to process. These changes only have to be done once and have no impact on the other editorial changes to the table.

First, we can add some markup to each cell in the “time” column to identify the time of the talk in a machine-readable way:

<time datetime="2020-07-27T14:00:00-04:00">14:00</time>

The datetime attribute contains an ISO 8601 value for time. This value includes a timezone and represents the moment to display, but we can assume they’ll all be in the timezone of Rockville, MD. (The content of the time element is the displayed value, which will change as a function of the selected local timezone.)

Additionally, we can add a data-slot attribute to each table cell where a talk occurs. The presence of that attribute identifies that a talk should be injected into this cell and the value of the attribute identifies the talk.

Markup for the table cell for the talk on Monday at 10:00am is

<td row-span="2" data-slot="Monday/10:00"></td>

The data-slot attribute identifies the talk by day and time, not by its XML identifier, to protect the schedule-at-a-glance against errors if the schedule changes at the last minute.

Requirements

For the purposes of this paper, the requirements below have been identified.

Markup

Historically, the schedule page was the “single source of truth” used to generate both web pages and a printed conference program. Consequently, the existing editorial process already adds sufficient markup to correctly identify the salient details about each talk: when it occurs, the title, authors, and so forth. You can easily explore this markup with “view source” on the schedule page.

In brief: there’s a div for each day. Each event has its own div within the day. The date and time, title, speakers, and abstract are encoded within that div. By way of example, Figure 1 shows how a talk scheduled for Monday at 10:00am would be tagged.

<div class="Program-Day" id="Monday">
  <h1>Monday, August 2, 2021</h1>
  <div class="ProgramEvent" id="M10">
    <span class="EventDateTime">
      <span class="Day">Monday</span>
      <span class="timestart">10:00</span>
      <span class="timeend">10:30 EDT</span></span>
      (+ Q&amp;A 10:30 - 10:50)
      <h2 class="EventTitle">The Title of the Talk</h2>
      <h2 class="Speakers">
          <a class="biolink" href="Bios.html#xxx">
            <span class="SpeakerName">J. Doe</span></a>,
            <span class="affil">Some affiliation</span>
      </h2>
      <p class="blurb">A short abstract of the talk.</p>
  </div>
  …

Observations about browser architecture

All three of the solutions discussed here ultimately run in the browser, using the architecture and features exposed there. XForms takes a robustly declarative position, freeing the user from many of the details, but the XForms implementation is still operating within the browser architecture.

The programming language environment supported by the browser is JavaScript. (There are XSLT 1.0 implementations as well in some browsers, but XSLT 1.0 stylesheets by themselves, as supported by browsers, aren’t sufficient to write interactive applications.) JavaScript is an interesting language. A full exploration of the features of JavaScript is well beyond our scope here. For our purposes, in this paper, it’s sufficient to think of JavaScript as a procedural programming language with a syntax in the style of C and Java. It is much more than “just” a procedural programming language, but we don’t need its advanced features (objects, prototypes, promises, etc.) for this simple application.

Browser implementations of JavaScript provide complete and robust access to the HTML documents rendered by the browser. They do not, natively, provide especially robust access to XML documents or XML document APIs. Most JavaScript applications use JSON to store data, not XML. The easiest data structures to create, query, and update in the browser using JavaScript are JSON objects and arrays.

There are rich JavaScript APIs for accessing information about the state of the browser, the web page being displayed, and the state of individual controls on the web page. You can easily, for example, ask if a checkbox is or is not checked. You can easily change its state as well. There are also APIs for querying and updating the values of class attributes, CSS properties, etc.

JavaScript is single threaded: if your browser is doing one thing in JavaScript, it can’t simultaneously be doing something else. In addition, the scheduler, the part of the browser that decides what bit of JavaScript to run, isn’t preemptive. If you write JavaScript code that “busy waits” for something to finish, you’re not just blocking your thread, you’re blocking all the threads. If you’ve ever seen the browser dialog box that says “this page isn’t responding, do you want to kill it or continue waiting?”, you’ve seen what happens if a thread busy waits for too long.

In order to avoid this, JavaScript programmers have to use “callback functions”. Imagine that your JavaScript code is going to run a query to find something on the page, a particular div, for example, and then process it. A naive implementation would ask the browser to run the query, wait for it to return the result, and then process it.

// This looks a little bit like JavaScript,
// but it's just pseudo-code

let myDiv = document.find("div.ProgramEvent");
processMyDiv(myDiv);

There are lots of other JavaScript functions waiting in the wings to run (even if you didn’t write them, chunks of the browser itself are waiting for their turn to run). Waiting for something to finish is bad practice. It’s your responsibility to give up control and let someone else have a turn!

What you do instead of waiting, and what many JavaScript APIs force you to do, is tell the engine what function to “call back” when the query results are ready.

// More pseudo-code
document.find("div.ProgramEvent", processMyDiv);

Execution of your script stops at the point where you call document.find. Someone else gets their turn, and when the results are ready, your processMyDiv function will be called. This mostly works just fine, even if it’s a little confusing at first.

Thing is, this is so common, that it would be tedious if you had to write a separate, named function (like processMyDiv) for every callback you used. JavaScript lets you just inline the function. Again, this may look a little confusing, but you get used to it.

// One final bit of pseudo-code
document.find("div.ProgramEvent", function() {
  // just write the code that processes the
  // div right here.
});

Another area where callback functions come into play is in handling events. From the perspective of your application, the browser is “out there” displaying HTML elements, scrolling the page, reacting to mouse clicks, and doing all the things that the browser does. These are all represented in the browser as events that occur: a button was clicked, the page scrolled, a web request finished, etc. There are lots and lots of kinds of events, we won’t try to enumerate them all here.

If your application wants to participate, it needs to tell the browser what events it cares about. It does that by registering a special kind of callback function, an event listener:

a_button.addEventListener('change', function(event) {
  // do something in response to the event
});

When the “this item changed” event occurs on the page element identified by “a_button”, the “listening” callback function will be run.

There’s lots more that could be said about JavaScript, including new features that are syntactically nicer than all those callback functions, but that’s enough of the conceptual framework for now.

Simple user-interaction controls and the ui instance

In this exercise, the direct user interaction is very simple and rather limited: the user gets a way to select a time zone, and a way to specify whether a 24-hour clock or a 12-hour clock is to be used. For selecting one value from a controlled list of values, XForms uses the xf:select1 control. In rough outline, the time zone control looks like this:

<xf:select1 id="timezone-selector" ref="instance('ui')/tz">
  <xf:label>Timezone: </xf:label>
  ...
  <xf:item>
    <xf:label>CDT  Chicago, IL, USA (UTC-05:00)</xf:label>
    <xf:value>-05:00</xf:value>
  </xf:item>
  <xf:item>
    <xf:label>EDT  Rockville, MD, USA (UTC-04:00)</xf:label>
    <xf:value>-04:00</xf:value>
  </xf:item>
  ...
  <xf:item>
    <xf:label>CEST Prague, CZE (UTC+02:00)</xf:label>
    <xf:value>+02:00</xf:value>
  </xf:item>
  ...
</xf:select1>

The basic structure will be familiar to many who have written forms: the control contains a list of possible values, each with the label to be used in offering the choice to the user. The list of options is wrapped in a xf:select1 element, which describes not the user interface widget to be presented to the user, but the semantic affect to be achieved: the user should select one value from among those listed. Whether the display engine uses a pull-down menu, a fully expanded menu, radio buttons, or some other mechanism to achieve that effect is not specified in the form or in the XForms spec. (An appearance attribute with possible values full, compact, and minimal can be used to give hints about what would work best. At that level of abstraction, a form processor working in a voice browser can try to make appropriate adjustments.) Note that the xf:label element appears at both levels: one label for the selection control as a whole and one for each item. By associating the label structurally with the thing labeled, XForms makes it easier for software to understand the logical structure of the form, which is why it provides a better experience for users employing voice browsers and assistive technologies.

But where is the selected time zone actually stored, once the user selects one?

XForms 1.0 and 1.1 do not define variables; all controls are bound to nodes in XML document instances. A common idiom, when the form needs to keep track of information that is not in any of the XML documents the form works with, is to add a document instance to contain that information and allow the form to manage it. In this case, the information is all concerned with the state of the user interface, so the instance has been given the name ui. Like the other instances used, the ui instance appears in the HTML header, inside the xf:model element, which in outline looks like this:

<head>
  <title>Balisage 2020 Program</title>
  ...

  <xf:model id="m1">

    <xf:instance id="program" src="./Program.xhtml"/>

    <xf:instance id="ui" xmlns="">
      <ui-info clock24="false">
        <tz>-04:00</tz>
	...
      </ui-info>
    </xf:instance>
    ...
  </xf:model>
  ...
</head>

As can be seen, the ui instance has a clock24 attribute on the root element and a child element named tz, and a bit more not shown here.

The ref attribute on the xf:select1 control binds the control to the tz element using the XPath expression instance('ui')/tz. The XForms function instance() identifies the outermost element of an instance document; instance('ui') thus refers to the ui-info element shown in the model.^[1] The result of the binding is that when the control is used to select a timezone, the value in the instance document is updated automatically.

The 24-hour clock checkbox is simpler. It uses the xf:input element:

<xf:input ref="instance('ui')/@clock24">
  <xf:label>24-hour clock: </xf:label>
</xf:input>

If the form knew nothing about the clock24 attribute, this would be roughly equivalent to an HTML input element of type text. But if we tell the form that the attribute holds a Boolean value, the form can use a more appropriate interface like a checkbox to present the value to the user. This we do with an xf:bind element which identifies a node in an instance document and identifies its (XSD) datatype.

<xf:bind nodeset="instance('ui')/@clock24"
         type="xsd:boolean" />

The xf:bind element has other uses, some of which will be seen later.

Injecting HTML into the host document

Because XForms is designed to display and allow user interaction with nodes in the document instances of the model, and not to modify the nodes of the host document itself, the parts of the exercise which specify that various pieces of information be injected into specific places in the conference program require a little adjustment in XForms.

The simplest example is perhaps the final item in the requirements list. In the Javascript and Saxon-JS solutions, an HTML p element in the program is given HTML content. The element originally looks like this:

<p id="schedlink"></p>

In the browser, it is to be modified to take the following form, or an equivalent:

<p id="schedlink">
  &#x261E; Interactive
  <a href="#schedule">schedule at a glance</a>.
</p>

This particular implementation tactic is not open to XForms, but we can do something conceptually similar. In the XForms solution to the task, the conference program is modified so that the paragraph in question contains an xf:output element, which XForms uses to display data from an instance document.^[2]

<p id="schedlink">
  <xf:output mediatype="text/html"
             ref="instance('ui')/schedlink"/>
</p>

The mediatype attribute on xf:output indicates the data format of the data to be displayed. (Operationally, it says “take this string and write it to the innerHTML property of the containing element.”) The mediatype attribute is particularly helpful for allowing the display of image data, but as can be seen here it can also be used to inject HTML elements into the display of the form. The ref attribute links this output control to the schedlink element in the ui instance document.

<xf:model id="m1">
    ...
    <xf:instance id="ui" xmlns="">
      <ui-info clock24="false">
        <tz>-04:00</tz>
        ...
        <schedlink>
          &#x261E; Interactive
          <a href="#schedule">schedule at a glance</a>.
        </schedlink>
      </ui>
    </xf:instance>

    <xf:bind nodeset="instance('ui')/@clock24"
             type="xsd:boolean" />

    ...
</xf:model>

The same pattern is used in the main part of the tabular display. Since an XForm cannot change elements in its host document, we need to introduce xf:output elements to show where the titles and authors of talks need to be displayed. So the td elements of the framework table are no longer empty. In the current workflow, for example, the first slot on Monday takes the following form.

<td rowspan="2" data-slot="Monday/10:00"></td>

In the XForm, it contains XForms elements to specify what needs to be displayed there:

<td rowspan="2" data-slot="Monday/10:00">
  <xf:group
      ref="instance('program')//xhtml:div
           [@class='ProgramEvent']
	   [xhtml:span[@class='EventDateTime']
           [xhtml:span[@class='Day'
	               and string() = 'Monday']]
           [xhtml:span[@class='timestart'
		       and string() = '10:00']]
           ]">
    <xf:output value="xhtml:h2[@class='EventTitle']"/>
    <span> &#x2014; </span>
    <xf:repeat
        nodeset="xhtml:h2[@class='Speakers']/xhtml:a">
      <xf:output mediatype="text/html"
                 value="serialize(.)"/>
    </xf:repeat>
  </xf:group>
</td>

As may be seen, this complicates the input significantly. A simpler approach is to use the transform() function, an extension offered by XSLTforms, which allows an XSLT stylesheet to be invoked on a specified node in an instance document. Using that approach, the same slot looks like this:

<td rowspan="2" data-slot="Monday/10:00">
  <xf:output mediatype="text/html"
             value="transform(instance('program'),
                              'single-item.xsl',
			      false,
			      'slot',
			      'Monday/10:00')"/>
</td>

The xf:output element here essentially says that the value to be displayed (as HTML) is whatever is produced by invoking the XSLT 1.0 stylesheet single-item.xsl on the program instance, with the stylesheet parameter slot given the string value Monday/10:00.^[3]

The program instance is, as the name suggests, a document containing authoritative information about the conference program. As explained above, that is the HTML document in which the form is embedded. But an XForm cannot extract data from its host document any more than it can modify the host document. To make the code just given work, therefore, it is necessary to make the host document available to the XForm as an instance document, which is done using an xf:instance element with the appropriate URI.

<xf:instance id="program" src="./Program.xhtml"/>

This is not quite as self-referential as it may look. In practice, the browser loads two copies of the file: one is the XHTML page actually displayed by the browser,^[4] and the other is an instance document accessible to the form. Changing the HTML in the instance document does not affect the document being displayed by the browser, except by means of the xf:output elements shown above.

An alternative implementation approach would resemble the Javascript and Saxon-JS examples more closely. In this approach:

Timezone calculations

The core idea of this exercise is to make the document interactive by making it react appropriately to the user’s choice of timezone. To do this, we:

In the XForm version of the program document, the table cells containing the time for each event take the following general form. This is the same as the current structure, except for the addition of the xf:output element.

<th id="r10" class="time" scope="row">
  <time datetime="2020-07-27T10:00:00-04:00">10:00</time>
  <xf:output
      mediatype="text/html"
      value="instance('ui')/slot-times/slot[@id='r10']"/>
</th>

As can be seen, the slot elements in the ui document instance have the same IDs as the corresponding cells in the table, to simplify joining them up.

In the ui document instance, a slot element has the following form.

<slot id="r10"
      datetime="2020-07-27T10:00:00-04:00"
      user-datetime="2020-07-27T10:00:00-04:00"
      user-time="" uh24="" uh12="" wrapped=""
      default="10:00">10:00</slot>

The id and datetime attributes are copies of those on the table cell and the time element inside it. The default attribute holds the original content of the table cell, in case we ever need it. (We don’t, as it turns out, but we didn’t know that at first.) The content of the element is what will ultimately be displayed to the user. The other attributes are there to hold intermediate values, partly as a way of simplifying the XPath expressions used in the calculation of the element content, and partly as a way of dividing the time zone calculation up into manageable pieces. It may be observed that they are initially blank, because they are only needed when calculating the time for a new time zone.

The calculation of the event’s time in the user’s time zone is handled by a series of xf:bind elements with calculate attributes. The calculate attribute is used, as its name suggests, to calculate the value of some node from other information already available. Its value is an XPath expression.

In an XForms implementation which had full support for XPath 2.0 functions, most of the intermediate values would not be needed and the entire process could be handled with a simple call to adjust-dateTime-to-timezone(), followed by a call to format-dateTime(). Since the current version of XSLTforms does not have an XPath 2.0 version of adjust-dateTime-to-timezone(), we cannot do it this way; we need to do the timezone arithmetic ourselves.

An alternative approach would be to implement the required XPath 2.0 functions in Javascript and install them as extension functions. This is possible, but details of how to do it vary among XForms processors, and it requires using Javascript, which some people try to avoid when possible.

Since calculating intermediate values by specifying XPath expressions and storing them in nodes in an XML document is easy to understand for any XSLT programmer, the xf:bind elements used to perform the time zone calculations will need hardly any commentary. But first we need to explain briefly how the calculations work.

XForms 1.1 specifies a number of functions for the XPath function library, including a seconds-from-dateTime() function which converts a dateTime expression into the number of seconds separating the dateTime indicated from the epoch at 1970-01-01T00:00:00Z.^[5] Its opposite number is seconds-to-dateTime(), which converts an integer number of seconds into a dateTime in UTC. We will compute the user’s local time by (1) converting the timezone offset into seconds, (2) converting the scheduled time of the event into seconds, (3) adding the two, and (4) converting the resulting number of seconds back into a dateTime expression.^[6]

First, we calculate the timezone offset in seconds by extracting the number of hours and minutes in the timezone offset value. To hold these, we add some blank attributes to the tz element: <tz h="" m="" sign="-" secs="">. The values to be assigned to those attributes are specified in the following bind elements.

<xf:bind nodeset="instance('ui')/tz/@h"
         type="xsd:integer"
         calculate="substring(.., 2, 2)"/>
<xf:bind nodeset="instance('ui')/tz/@m"
	 type="xsd:integer"
         calculate="substring(.., 5, 2)"/>
<xf:bind nodeset="instance('ui')/tz/@sign"
         calculate="substring(.., 1, 1)"/>
<xf:bind nodeset="instance('ui')/tz/@secs"
         calculate="if(../@sign = '-',
                    0 - (((../@h * 60) + ../@m) * 60),
                    0 + (((../@h * 60) + ../@m) * 60))"/>

It may need to be mentioned that the context item for interpretation of the calculate attribute is the node whose value is being calculated. Thus the calculation of the h and m attributes must refer to .. to fetch the string value of the tz element.

The last calculation uses the XForms function if(), which allows conditionals to be expressed inside XPath 1.0 expressions. It takes three arguments: the condition to be tested, the result if the condition evaluates to true, and the result if the condition evaluates to false.

Whenever the value of the tz element changes, all other values which are known to depend on it are recalculated. The dependencies expressed in the calculate expressions are known, and the XForms processor uses the same algorithm as a spreadsheet processor to decide on the order in which to calculate the values in any dependency chain. So no effort is needed on the part of the form author to specify that h and m and sign need to be calculated before secs. The processor takes care of all that.

The user-datetime value on any slot is calculated as described above.

<xf:bind nodeset="instance('ui')/slot-times
                  /slot/@user-datetime"
         type="xsd:dateTime"
         calculate="seconds-to-dateTime(
                    seconds-from-dateTime(../@datetime)
                    +
                    instance('ui')/tz/@secs
                    )"
         />

From the user-datetime value, we can extract several other useful values: the hours-and-minutes part of the dateTime expression (user-time), the hours part of the expression on a 24-hour clock (uh24), the hours part on a 12-hour clock (uh12), and finally a Boolean flag to show whether the clock has moved to the next day or not (wrapped).

<xf:bind nodeset="instance('ui')/slot-times
                  /slot/@user-time"
         type="xsd:string"
         calculate="substring(../@user-datetime, 12, 5)" />
<xf:bind nodeset="instance('ui')/slot-times/slot/@uh24"
         type="xsd:string"
         calculate="substring(../@user-time, 1, 2)" />
<xf:bind nodeset="instance('ui')/slot-times/slot/@uh12"
         type="xsd:string"
         calculate="((../@uh24 + 11) mod 12) + 1" />
<xf:bind nodeset="instance('ui')/slot-times/slot/@wrapped"
         type="xsd:boolean"
         calculate="substring(../@user-datetime, 9, 2)
                    > substring(../@datetime, 9, 2)" />

The final calculation of the string to be displayed to the user is complex enough to be worth explaining in more detail. The core calculation is: if the clock24 flag is set to false,^[7] then concatenate the 12-hour version of the hour value with a colon and the minutes value, and add either “am” or “pm” as appropriate. Otherwise (clock24 is true), just use the user-time value, which is on a 24-hour clock.

if(instance('ui')/@clock24 = 0
   or instance('ui')/@clock24 = 'false',
   concat(@uh12,
          ':', substring(@user-time, 4, 2),
          if(@uh24 > 11, 'pm', 'am')
         ),

   substring(./@user-datetime, 12, 5)
  )

But the time 12:00 should be displayed as “noon” or as “midday”, so the code just given is wrapped in a test for 12:00:

if(@user-time = '12:00',
   if(instance('ui')/@clock24 = 0
      or instance('ui')/@clock24 = 'false',
      'noon',
      'midday'),
   ... else-case as above ...
  )

A second complication is that if the time is past midnight in the user’s timezone, we are to add an HTML br element and the notice “(the next day)”. So the expression just given is wrapped in a call to concat(), together with a test for the past-midnight case.

concat(
       ... time expression as given above ...
       ,
       if(@wrapped = 'true' or @wrapped = 1,
          ' <br />(the next day)',
          '')
      )

The final complication is that if the user time is 00:00, then (a) the time should be displayed as “midnight”, and (b) the phrase “(the next day)” should not be used, since it would raise more questions than it answers. The full expression of the final step in the calculation is thus as follows.

<xf:bind nodeset="instance('ui')/slot-times/slot"
         type="xsd:string"
         calculate="if(@user-time = '00:00',
                    'midnight',

                    concat(
                    if(@user-time = '12:00',
                    if(instance('ui')/@clock24 = 0
		       or instance('ui')/@clock24 = 'false',
                    'noon',
                    'midday'),

                    if(instance('ui')/@clock24 = 0
		       or instance('ui')/@clock24 = 'false',
                    concat(@uh12,
                    ':', substring(@user-time, 4, 2),
                    if(@uh24 > 11, 'pm', 'am')
                    ),

                    substring(./@user-datetime, 12, 5)
                    )),

                    if(@wrapped = 'true' or @wrapped = 1,
                    ' &lt;br />(the next day)',
                    '')
                    ))

                    " />

With the help of the xf:bind element, the core interactivity of the document can be implemented in a purely declarative way. As can be seen from the first steps in the sequence, using instance-document nodes to hold intermediate values can help make the expressions at each step simpler; as can be seen from the final calculation, intermediate nodes are not strictly necessary, if one is willing to work with a more complex expression.

Event handling

The final part of the XForms implementation to be explained is the dependency of the clock24 flag on the timezone. Whenever the timezone changes, the clock24 flag should be updated: for time zones in (roughly) the Western Hemisphere, clock24 should be set false; for timezones in the Eastern Hemisphere, it should be set true.^[8]

We could use xf:bind with a calculate attribute for this task, but that would effectively prevent the user from changing the clock24 flag: calculate expresses an invariant relation between values in the instance document. We want to change the value, but let the user change it back.

XForms has an event model similar to (and derived from) that of the HTML document model as specified in DOM level 2. At various times during the life of a form, events are dispatched to appropriate targets to be handled by event handlers. Form authors can register new event handlers which observe specified locations in the form and can capture and handle them.

For the task at hand, the simplest thing to do is to listen for the event xforms-value-changed to be dispatched in response to a change to the tz element, and to handle the event by setting the value of the clock24 attribute appropriately. To do this, it suffices to add two xf:setvalue elements to the xf:select1 element bound to the tz element, thus:

<xf:setvalue ev:event="xforms-value-changed"
             ref="instance('ui')/@clock24"
             value="if(../tz/@sign = '-', 'true', 'false')"/>

Here, the ev:event attribute, in the XML Events namespace, gives the name of the event for which the xf:setvalue element is listening. (It does not need to specify which element it is interested in, because its parent select controller will only receive events related to the tz element.)

The ref attribute specifies the node whose value is to be updated. The value attribute specifies the new value.

In principle, this simple approach should solve the problem. For reasons thus far unexplained (probably an error somewhere in the form, or possibly in the development version of the engine), however, this simple approach does not work. The event is dispatched and captured, but setting the new value of the clock24 attribute appears to cause an infinite loop. So until the cause of the problem is found, another approach is needed.

Since the problem appears to be an infinite loop caused by the event xforms-value-changed being raised by the handler for that event, one plausible approach is to try to find some other event to be used as the trigger for resetting the clock24 flag.

When an item in an xf:select1 element is selected, or de-selected, appropriate events are dispatched to the item. So we should be able to reach our goal by putting an event handler on each item in the timezone selection control and making it listen for the event xforms-select. At the same time, partly to illustrate the user of user-defined events and partly because it makes it easier to insert debugging messages into the form to report on what is going on, the xf:setvalue action will be replaced by an xf:dispatch action which dispatches an appropriate user-defined event, whose handler will (possibly among other things) update the clock24 flag.

So instead of adding one xf:setvalue element as a child of xf:select1, we add one xf:dispatch element to each item in the select control. The item for Central Daylight Time (Chicago), for example, looks like this:

<xf:item>
  <xf:label>CDT  Chicago, IL, USA (UTC-05:00)</xf:label>
  <xf:value>-05:00</xf:value>
  <xf:dispatch ev:event="xforms-select"
               targetid="m1"
               name="bmt:set-12h-clock"/>
</xf:item>

As before, the ev:event attribute specifies which events this handler listens for. The name attribute give the name of the event to be dispatched by the handler, and the targetid gives the ID of the element which is the target of the event. Here, m1 is the ID assigned by the form author to the xf:model element, and bmt:set-12h-clock is a user-defined event (given as a QName) meaning the clock24 flag should be set false.^[9] A different event (bmt:set-24h-clock) is dispatched by handlers for time zones east of Greenwich.

Because the event handlers are now embedded in each item in the selection control, it is easy to make them follow a more complex pattern than “west, 12-hour clock; east, 24-hour clock”. Some sources claim, for example, that most Anglophone countries normally use 12-hour clocks, and other countries normally use 24-hour clocks (again, with exceptions and complications not covered here). If we believe this claim, we can make the selection of Australian or New Zealand time set the flag to a 12-hour clock, even though they have a positive timezone offset.

The user-defined events are dispatched to the model, and the handlers for those events are given as children of the xf:model element.

<xf:model id="m1">
  ...

  <xf:action ev:event="bmt:set-12h-clock">
    <xf:message if="instance('ui')/@debugging = 'true'"
                level="modal"
                >Clock should change to 12h.</xf:message>
    <xf:setvalue ref="instance('ui')/@clock24"
                 value="'false'" />
    <xf:message if="instance('ui')/@debugging = 'true'"
                level="modal"
                >Check it out!  The 24h clock switch <!--
		-->should have changed!</xf:message>
  </xf:action>

  <xf:action ev:event="bmt:set-24h-clock">
    <xf:message if="instance('ui')/@debugging = 'true'"
                level="modal"
                >Clock should change to 24h.</xf:message>
    <xf:setvalue ref="instance('ui')/@clock24"
                 value="'true'" />
    <xf:message if="instance('ui')/@debugging = 'true'"
                level="modal"
                >Did the 24h clock switch?</xf:message>
  </xf:action>
</xf:model>

The xf:action element is a wrapper for other XForms actions. It executes them one at a time in turn. The practical effect is that the ev:event attribute can be specified once on the enclosing xf:action and does not need to be repeated on its children. The xf:message element displays a message to the user (here displayed in a popup window, as suggested by level="modal"). The xf:setvalue element has been seen before.

The if attribute seen here on the xf:message element specifies an arbitrary condition on the execution of the action. If the condition holds, the action is performed, and if not, it is not performed. Here, a Boolean debugging attribute on the ui-info element is tested; if debugging is turned on, the messages are displayed, and otherwise not. Messages can in general display useful information about the course of events; these messages mostly serve to signal that the event handler has been activated.