XForms/Selecting Codes From File

Motivation
People who design forms frequently have to maintain many code tables. These code tables may change frequently and there may be processes that update a database of centrally maintained code tables. So you want each form to dynamically get the current relevant codes from an XML file or a RESTful web service.

This sample program demonstrates how to read a list of codes with labels directly from a file or code-table web service. In this example the file that contains the codes is just a well-formed XML file in the same directory that the form is located in.

Loading XML instance data from a local file or web service
The following code fragment, usually in the HTML head, demonstrates how to read XML data from a local file in the same directory as the form by using the "src" attribute of the instance.

Loading Codes from a Web Service
It is common to have a single web service load all code tables. This service can be passed parameters such as the name of the code table as well as the group the person is a part of. This can narrow down the list of selections for long lists.

Loading all Codes into a single Instance
The problem with loading individual code tables into individual instances is that you must perform a separate HTTP get for each code table. This is not a problem for forms with one or two small selection lists. But for large forms with many selection lists this can slow down form response time. The solution is to load all codes into a single instance with a single HTTP GET request. Each code table can then be selected from this instance.

In this second example all the codes in the entire form are generated by a service of the Metadata Registry (MDR). The data returned by this server is a collection of codes for each select1 control in the form.

This will look for a well-formed XML file in the current directory and load it into the model instance.

Note that in this case the model is given an id. This is necessary to allow multiple code tables to each be read into their own separate model.

Screen Image
Here is a screen image of the program. As the user selects from the drop-down list, the value of the output is immediately updated.



Note that label on the screen is not the same as the label stored in the model.

Sample Program
   This selection list was read from a file.  Select XML Schema data type:        Value of MyXMLSchemaTypeCode:  

Sample XML Data
Note that to be well-formed the XML file MUST contain a root data element that must match the node-set argument.

Extracting data from an XML REST web service
You can replace the instance src attribute with a path directly to a XML REST web service. For example, if you put all your code tables into a project resources collection the path would look like the following:

or if your system codes are stored in a single XML file and you have a wrapper XQuery

Selection Lists From A Single Instance
To keep your forms fast, it is usually better to do a single HTTP GET operation for all your codes. Forms that have many selection lists will take a long time to load if each list does a separate HTTP GET operation. For large forms it is easy to get a 10x speedup in form load times.

Structure of Code Tables Instance
The following is a sample structure of all codes loaded into a single instance:

Sample Select1
Once your data is loaded into your model, each of your select1 or select controls can get its data directly from the model using the xf:itemset element. Itemset works just like repeat and uses nodeset (not ref) to get all its values. Here is an example of how to get the itemset data from your code-tables instance.

Note that the predicate [code-table-name='MyElementCode'] will only put the items for that code into the selection list.

Auto Generation of Code Tables from Metadata Registry
Because XML Schema does not contain information for presentation we use the following workflow as a "best practice".


 * 1) Store all label/value pairs in external code table files or get this information from a web service.
 * 2) For each form, create a web service that will generate a code-tables element for all the codes used in that form.
 * 3) Load the code-tables element into a separate  instance in your model with an id of "code-tables".
 * 4) Select the code table out of that instance for each select1 or select element by getting a code table with that name.

Discussion
When a group of complex forms that share common codes needs to be placed in their own directory and yet still link to a central directory of codes, you can also use relative code table linking. For example a sibling directory could be called "code-tables" and the src="MyCode.xml" statement could be modified to be src="../code-tables/MyCode.xml".

If you have an XML Schema for the form you can also extract a list of all enumerations for each simpleType. This list of codes can then be passed to a web service that creates a list of all the codes in your registry. This allows the form to automatically be updated when new codes are added to the XML Schema.

If you have a RESTful web service that contains all the codes for a form, you can replace this web service URI for the XML file.