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 a Single Codes Table into a Single Instance

src="XMLSchemaTypeCode.xml" id="XMLSchemaTypeCode"/>

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.

id="ApprovalCodes" src="/db/mdr/services/all-codes.xq?code=ApprovalCodes&group=editor"/>

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.

id="code-tables" src="/db/mdr/services/all-codes.xq?form=DataElementManager&group=admin"/>

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

xmlns="http://www.w3.org/1999/xhtml"
xmlns:xf="http://www.w3.org/2002/xforms" >

Select List From File

/* the default model */

id="save-data" xmlns="">

id="code-tables" src="XMLSchemaTypeCode.xml"/>

This selection list was read from a file.

ref="/MyData/MyXMLSchemaTypeCode">
Select XML Schema data type:
ref="instance('code-tables')/XMLSchemaTypeCode/item">
ref="label"/>
ref="value"/>

ref="instance('save-data')/MyXMLSchemaTypeCode">
Value of MyXMLSchemaTypeCode:

Sample XML Data

XML Schema Type:

Date and Time
dateTime

Time (HH:MM:SS-06:00)
time

Date (yyyy-mm-dd)
date

Year and Month
gYearMonth

Year (nnnn)
gYear

Month and Day
gMonthDay

Day of Month (1 .. 31)
gDay

Month (1 .. 12)
gMonth

String
string

Boolean (true/false)
boolean

Base 64 Binary
base64Binary

Decimal (0.00)
decimal

Any URI
anyURI

Integer (...,-2,-1,0,1,2,...)
integer

Non-Positive Integer (...,-2,-1,0)
nonPositiveInteger

Negative Integer (...,-2,-1)
negativeInteger

Long (-9,223,372T .. 9,223,372T)
long

Int (-2,147,483,648 .. 2,147,483,647)
int

Short (-32,768 .. 32,767)
short

Byte (-128 .. 127)
byte

Non-negative Integer (0..N)
nonNegativeInteger

Positive Integer (1..N)
positiveInteger

Unsigned Long (0 .. 18,446,744T)
unsignedLong

Unsigned Int (0 .. 4,294,967,295)
unsignedInt

Unsigned Short (0.. 65,535)
unsignedShort

Unsigned Byte (0..255)
unsignedByte

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:

src="../resources/code-tables/PersonGenderCode.xml"/>

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

src="../resources/code-tables/get-codes-for.xq?element=PersonGenderCode"/>

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:

id="code-tables">

MyElementCode

Joe Smith
42

Sue Johnson
47

ColorCode

Red
1

Orange
2

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.

ref="instance('save-data')/MyElementName">
My Element:
nodeset="instance('code-tables')/code-table[code-table-name='MyElementCode']/items/item">
ref="label"/>
ref="value"/>

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

• Store all label/value pairs in external code table files or get this information from a web service.
• For each form, create a web service that will generate a code-tables element for all the codes used in that form.
• Load the code-tables element into a separate instance in your model with an id of "code-tables".
• 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.

Where this page came from

This page was imported from Wikibooks. From “XForms” on Wikibooks, by its contributors, under CC BY-SA 4.0. Changed here: set as a page; navigation and edit links left out; each image under its own licence, credited in its caption.

Nobody has written it yet — it is the source material at a new address, which is why search engines are asked to skip it and why no one earns from it. It is up for grabs: take it on, and it is yours to rewrite and to earn from.