Description-Action Approach

An important thing to stress at this point is the way interactions are structured (or recommended to be structured) using the XForms package within the Webware framework. The recommended approach could be summarised as a "description-action" mechanism: if a user cannot supply appropriate data for an activity (or operation), the application describes the form of the data involved; then the user uses the description to provide the data required for the activity to be completed. At each point that the data is seen to be inappropriate or insufficient, a description is returned with the submitted data and information about the inappropriateness or insufficiency of the data. Later, we shall see that this requirement that the data is always returned by the user to the entity which described its form, dictates that the action employed in each HTML form always refers to the resource (or entity) which output that form.

Examples

This framework attempts to hide the mechanics of how data types are dealt with, requiring the developer only to specify the structure of each data type within an XForm definition file. The basic or standard form of such structure definitions look like this:

  <model>
    <string name="name" min="1" required="1"/>
    <group name="badgers">
      <string name="name" min="1" required="1"/>
      <number name="age" min="0"/>
      <group name="friends">
        <string name="name" required="1"/>
        <number name="age" min="0"/>
        <money name="status" min="0" max="1500"/>
        <boolean name="selected"/>
      </group>
      <boolean name="selected"/>
    </group>
    <operation name="_action_add_"/>
    <operation name="_action_remove_"/>
  </model>

Here, we see that our data type (or structure definition) consists of a "top level" name, a group of "badgers" and some operations. Each "badger" contains a name, an age and some friends, along with something called "selected". Each friend contains a name, an age, a status and something called "selected".

What this definition does is tell our framework that suitable form field data should be rearranged to fit this basic structure, if possible. However, it would also be nice to be able to generate the form which gives users the opportunity to provide such data. This is done using template or "instance" definitions, which look like this:

  <instance name="en_UK">
    Presenting <string name="name" min="1" required="1">&lt;br&gt;A name must be given!</string>:

    &lt;table border="1" cellspacing="0" cellpadding="5"&gt;
    <group name="badgers">
      &lt;tr&gt;
      &lt;th&gt;Name&lt;/th&gt;
      &lt;td&gt;<string name="name" min="1" required="1">&lt;br&gt;A name must be given!</string>&lt;/td&gt;
      &lt;/tr&gt;
      &lt;tr&gt;
      &lt;th&gt;Age&lt;/th&gt;
      &lt;td&gt;<number name="age" min="0">&lt;br&gt;Ages must be 0 or greater!</number>&lt;/td&gt;
      &lt;/tr&gt;
      &lt;tr&gt;
      &lt;td colspan="2"&gt;<boolean name="selected"/>&lt;/td&gt;
      &lt;/tr&gt;
      <group name="friends">
        &lt;tr&gt;
        &lt;th&gt;Name&lt;/th&gt;
        &lt;td&gt;<string name="name" required="1">&lt;br&gt;A name must be given!</string>&lt;/td&gt;
        &lt;/tr&gt;
        &lt;tr&gt;
        &lt;th&gt;Age&lt;/th&gt;
        &lt;td&gt;<number name="age" min="0">&lt;br&gt;Ages must be 0 or greater!</number>&lt;/td&gt;
        &lt;/tr&gt;
        &lt;tr&gt;
        &lt;th&gt;Status&lt;/th&gt;
        &lt;td&gt;<money name="status" min="0" max="1500">&lt;br&gt;Badgers only ever have up to 1500!</money>&lt;/td&gt;
        &lt;/tr&gt;
        &lt;tr&gt;
        &lt;td colspan="2"&gt;<boolean name="selected"/>&lt;/td&gt;
        &lt;/tr&gt;
      </group>
    </group>
    &lt;tr&gt;
    &lt;td colspan="2"&gt;<operation name="_action_add_" label="Add"/><operation name="_action_remove_" label="Remove"/>&lt;/td&gt;
    &lt;/tr&gt;
    &lt;/table&gt;
    <case name="status">
      <option value="0">Status set to zero.</option>
      <option value="1">Status set to one.</option>
    </case>
  </instance>

The first thing to note is the presence of lots of encoded HTML. Since XForms definitions are XML documents, they cannot really have lots of "out of place" tags (elements) which disrupt the structure of the document. Here, the structure of the document (or this part of the larger XForm definition document) is "marked out" using the data type elements used in the basic structure definition.

Indeed, it should be noted that the data type elements in use in the above template match (with some exceptions) the elements in use in the basic structure definition. This is obviously intentional, as we want the eventual output to lend itself to being used as a means for the user to provide input of the same form; if the eventual output from this template were lacking certain things, such as the badgers' friends, then it would be rather difficult for a user to add such things to the data under manipulation.

Of course, no-one is expected to write templates using encoded HTML - writing "normal" HTML is bad enough - so it would be envisaged that someone would first prepare a document which indicates the "expanded" form of the template; the "expanded" form meaning that every aspect of the template would be defined and no part of the data structure would be hidden. For example, in the above case, we would want someone to define how the badgers' friends section would look and not just leave it to our imagination. Here is what the above template would actually look like in a draft form:

After conversion to encoded HTML, the various "placeholders" in use would be replaced by the appropriate data type elements. These elements indicate the real data types in use, as opposed to vague HTML form field elements. Therefore, input elements of type text would be replaced by string, number or money XForm data type elements.

After this process has been completed, it would be appropriate to place the basic structure definition (inside its model element pair) along with our template definitions (inside their instance element pairs) together inside an xform element pair. For example:

<?xml version="1.0"?>
<xform id="Woodland" handler="woodland.py" action="test.xform" library="test_library.py">
</xform>

The attributes of the opening xform element tell us a lot about how the definition is to be deployed and how the data type elements are to be presented in output.

id

Although this is not currently used, it is envisaged that this will play a role in the coexistence of data from multiple activities.

handler

In the Webware framework, this indicates the program or module within the application which is to accept input in the form of the basic structure definition.

action

This should be named identically to the file within which the XForm definition is stored. As a consequence, any output generated using a template from this XForm definition will be verified against the correct basic structure definition (and not one belonging to another activity).

library

The library is a collection of functions within a module which dictate how the data type elements found in the template definitions should be presented in the eventual output. This provides the means to centrally define that, for example, boolean data types should always be presented using a checkbox.

Storyboards

The above description and examples only cover the operation of a single screen (or activity) within an application. However, it is very likely that a real application would involve a number of different screens. The storyboard framework attempts to make the connection of a number of XForm-based screens straightforward.

Consider a screen which requires information of a certain kind with strict validation on that data. For example, the details of a person might be highly restricted in that the application requires the details of a person within a particular database to be specified, as opposed to a random combination of first name and family name. In order to help the user find a suitable person, the application may provide a screen on which the searching activity can take place in a convenient way; some people call such screens "help screens".

The storyboard framework attempts to provide an easy way for developers to change the screen (or activity) presented to the user (whilst keeping the existing information that the user had given), to conduct the new activity, resuming the previous activity later on once the "subactivity" has been completed. This changing of the user experience is referred to as storyboarding because one can envisage a sequence of different screens (or scenes) which need to take place in a user's interactions with an application.

Starting a Sub Plot

To change the screen ("change scene", "introduce a sub plot" and so on) it should be sufficient to use the following function call within the storyboard module:

storyboard.start_sub_plot(trans, "next_screen.xform", some_information,
	xformdata, xform.action)

This call uses the Webware transaction trans to direct the "action" to next_screen.xform, providing that screen with some_information. It should be noted that the current screen's data is important to retain and is supplied to the call as xformdata. Finally, we tell the storyboard framework to come back to the XForm resource given by xform.action when the new activity has completed. (Of course, we could specify a screen to return to which is not the current screen at all. This would permit interesting possibilities.)

Now, upon reception of user input (usually given by a Web browser), the XForms framework separates the input into two categories: data recognised and structured according to a particular basic structure definition, and data which is unrecognised according to that definition. Whilst it may have seemed appropriate to discard the unrecognised data when just considering XForm definitions on their own, such unrecognised information needs to be retained as a means of remembering data from currently "inactive" screens whose activities have been suspended in the storyboard framework, in the trust that such screens may be visited in the future and use such data again.

Other information is passed to the new activity. It can be useful to start an activity with some basic information. This information is passed to activities using the special field name storyboard_data, and handlers need to check for the presence of such a field if they are to make use of its contents, which can generally take any form, although one might recommend the use of a dictionary in order to facilitate structure manipulation using the XForms framework.

Ending a Sub Plot

At the end of an activity ("scene" or "sub plot"), some information would be passed back to the suspended activity. It should be sufficient to use the following call to do this:

storyboard.end_sub_plot(trans, some_information, xformdata)

The principal difference between this call and the one which started the sub plot is that the next screen to be presented to the user will be the one specified in that previous call, as opposed to a screen explicitly specified in this call. The information passed back as some_information is also passed as storyboard_data, although this could be overly problematic and may be changed in the future.

Tutorial

NOTE: To be completed.

Rationale

Although a description of the technical aspects of this framework are given in the README file, it is probably wise to summarise the need for this framework in this document.

Presentation

The usual choice for developers is between:

*SP

Program code inside textual documents (typically HTML).

Programmatic

Generation of textual documents within programs.

Templates

Textual documents which include references to variables, the values of which are provided by the application.

The *SP and programmatic approaches mix presentation data with program code and thus do not always promote ease of maintenance of an application, since the program code (or application logic), the user interface (or appearance), and the data structures involved all seem to obscure each other.

Status

$Header: /home/paulb/CVS/XForms/Documents/index.html,v 1.4 2001/01/22 17:56:22 paulb Exp $