Examploforms

3.1. Datatype library for limited-length values

A common requirement of forms of all types is that certain existing datatypes have an additional limitation as to the length of allowed values. For example, the name field in a database might be limited to 45 characters, and thus the form that eventually produces that string should enforce the same limitation. In some cases, a minimum length limit is also desirable.

This datatype library consists of the set of all datatypes that can be derived from existing XML Schema datatypes defined in either XML Schema part 2 or XForms, restricted by either 1) the maxLength facet alone, or 2) the maxLength and minLength facets. Like all such datatype libraries, it is defined in a namespace. The offical namespace name, however, has not yet been defined. In this document, the prefix dt: represents this library.

The name of a datatype that defines only a maxLength facet is as follows:

dt:dtname-99

where dt: is the prefix assigned to the datatype library's namespace name, dtname is the name of a datatype defined in either XML Schema part 2 or XForms, - is a literal dash character, and 99 represents any positive integer and is the value assigned to the maxLength facet.

The name of a datatype that defines both maxLength and minLength facets is as follows:

dt:dtname-88-99

where dt: is the prefix assigned to the datatype library's namespace name, dtname is the name of a datatype defined in either XML Schema part 2 or XForms, - (both occurrences) is a literal dash character, 88 represents a positive integer and is the value assigned to the minLength facet, and 99 represents any positive integer and is the value assigned to the maxLength facet. The maxLength value must be greater than or equal to the minLength value.

Thus, the name of a datatype in this library contains sufficient information to construct a full XML Schema part 2 derived datatype. For example, a name restricted to 45 characters would be dt:string-45, shorthand for this:

<xs:simpleType name="string-45">
  <xs:restriction base="xs:string">
    <xs:maxLength value="45"/>
  </xs:restriction>
</xs:simpleType>

3.2. Datatype library for enumerated values

A common requirement of forms is that certain allowed values are restricted to a finite enumeration, often presented in a list format. For example, the officer field in a data collection system might be required to have one of the values president, vice_president, or treasurer.

This datatype library consists of the set of all datatypes that can be derived from the XML Schema string datatype, restricted by the enumeration facet with specified values. Like all such datatype libraries, it is defined in a namespace. The official namespace name, howerver, has not yet been defined. In this document, the prefix dt: represents this library.

The name of a datatype that defines an enumerated type is as follows:

dt:enum-val1-val2-val3

where dt: is the prefix assigned to the datatype library's namespace name, enum and all occurrences of - are literal strings, and val1, val2, val3, and any subsequent hypen-delimited strings, are possible values of the enumeration. Enumeration values cannot contain hyphens or any character not allowed in a datatype name.

Thus, the name of a datatype in this library contains sufficient information to construct a full XML Schema part 2 derived datatype. For example, and enumeration of president, vice_president, or treasurer would be dt:enum-president-vice_president-treasurer, shorthand for this:

<xs:simpleType name="enum-president-vice_president-treasurer">
  <xs:restriction base="xs:string">
    <xs:enumeration value="president"/>
    <xs:enumeration value="vice_president"/>
    <xs:enumeration value="treasurer"/>
  </xs:restriction>
</xs:simpleType>

4.1. Getting started.

This first example document can be used to create a simple form:

<?xml version="1.0" encoding="UTF-8"?>
<foo xmlns:eg="http://examplotron.org/0/">
  <bar eg:content="dt:string-20">My first Examploform.</bar>
  <baz>Hello World!</baz>
</foo>

This document represents a form with a single input control, with an initial value of "My first Examploform", which as it happens, is longer than the maximum-allowed 20 characters. After that problem is corrected by the user, the form can be submitted as XML, using the data structure shown. The actual data entered by the user would replace any initial values given.

Note: This is not to say that POSTing an XML instance is automatically the best thing a form can do during submission. In many cases, a RESTful GET is the appropriate solution, and one that XForms handles smoothly. Even with GET, though, the form data still needs to be initially modeled as XML.

XML documents can have many nodes, not all of which are intended to be mapped to fillable form controls. In the example above, bar is mapped to a form control, while baz remains avaialable as data, but not mapped to a form control. In classic HTML forms, this would be called a "hidden field". A later section describes the rules for determining how form controls map to the instance data.

4.2. Model Item Property definitions

Much of the power of XForms comes from the ability to define XPath-based relationships between various nodes of the instance data, including dynamic control over calculations, validations, and whether a node is required, read-only, or relevant. The combination of an XPath node with these properties is called a Model Item Property, and Examploforms makes these easeier to write and visually inspect, since they appear 'inline', at the point where they take effect.

The following Model Item Properties can be controlled through Examploforms:

ex:calculate

The value of this attribute is the XPath expression that calculates the value for this element node.

ex:constraint

The value of this attribute is the XPath expression that must return true for this element node to be considered valid.

ex:required

The value of this attribute is the XPath expression that, when evaluating to true, indicates the element node is required.

ex:readonly

The value of this attribute is the XPath expression that, when evaluating to true, indicates the element node is read-only.

ex:relevant

The value of this attribute is the XPath expression that, when evaluating to true, indicates the element node is relevant, and will thus be included in data submission.

The following example illustrates.

<taxpayer xmlns:eg="http://examplotron.org/0/" xmlns:ex="http://examploforms.org/0/">
  <name eg:content="dt:string-45">Full name here</name>
  <married eg:content="dt:enum-married-single-divorced"/>
  <spouse_name eg:content="dt:string-45" ex:relevant="../married='married'">Spouse name here</spouse_name>
</taxpayer>

4.3. Binding

A bind element will be generated for all leaf element nodes, including "hidden fields". The binding will include any Model Item Property definitions defined by examploforms attributes from the previous section. If an eg:content attribute is present, it will be used to assign a type Model Item Property, otherwise the following iconic datatype strings, if present as element content, will decide the datatype:

• boolean: identified by the values "true" or "false".
• integer: identified by any integer value such as "1", "-10" or "+5".
• decimal: identified by its decimal point, eg: "3.14", ".5" or "-3.".
• double: identified by its exponent, eg: -5.2E3 or 1E0.
• date: identified by its ISO 8601 format, eg: 2003-01-31

4.4. Form Controls

A form control will be generated for only leaf element nodes, according to the following rules:

• Element nodes with child elements (non-leaf) are not mapped.
• Leaf element nodes are mapped to controls if they have any examploforms attributes or eg:content or eg:occurs.
• Other leaf element nodes are treated as "hidden" fields, usable by the form for calculations or other purposes but not mapped to controls.
• Form controls within repeating sections are handled specially, as described in the next section.

The type of form control generated will be an input, unless one of the following conditions apply:

• If the datatype is an enumerated-value datatype, the control will be a select1
• If the code is a limited-length datatype based on string and having a maxLength of over 100 characters, the control will be a textarea

All form controls will have a label taken from the ex:label element, if present, otherwise a default label will be constructed based on the local name of the element node.

4.5. Repeating Sections

A repeating section will be generated for any element node on which eg:occurs="+" is present. Such elements will generally not be leaf element nodes; the element content will be repeated.

This example will create a simplified purchase order with repeating line items:

<po>
  <to>Company Name</to>
  <from>Company Name</from>
  <line_item eg:occurs="+">
    <part_no ex:label="Part Number">123</part_no>
    <desc ex:label="Description">Description</desc>
    <price eg:content="xs:decimal">1.23</price>
    <quan ex:label="Quantity">1</quan>
    <ext_price ex:calculate="../price * ../quan"/>
  </line_item>
  <total ex:calculate="sum(/po/lineitem/ext_price)"/>
</po>