[This local archive copy is from the official and canonical URL, http://www.uwi.com/xfdl/xfdl4-980902.htm, 1998-10-07; please refer to the canonical source document if possible.]
Copyright ©1998 UWI Unisoft Wares Incorporated
This document is the initial draft of the specification of the XFDL facility. It is intended for review and comment and is subject to change.
This document describes an XML syntax for the Extensible Forms Description Language (XFDL). The purpose of XFDL is to solve the body of problems associated with digitally representing complex forms such as those found in business and government. The requirements include support for high precision layout, supporting documentation, integrated computations and input validation, multiple overlapping digital signatures, and legally binding auditable transaction records, by maintaining the whole form as a single unit such that digital signatures can capture the entire context of transactions.
This document describes a class of XML documents called Extensible Forms Description Language (XFDL) Forms and partially describes the behavior of computer programs that process them. An XFDL processor is a software program that reads, processes, and writes XFDL forms. Processing may include such tasks as GUI rendering, data extraction, or modification.
From 1993 to 1998, UWI.Com developed the Universal Forms Description Language (UFDL). XFDL is the result of developing an XML syntax for the UFDL, thereby permitting the expression of powerful, complex forms in a syntax that promotes application interoperability and adherence to worldwide Internet standards. The current design goals of XFDL are to create a high-level computer language that
This version of the XFDL specification may be distributed freely, as long as all text and notices remain intact.
[1] Boyer, J. Lexical and Syntactic Specification for the Universal Forms Description Language (UFDL) Version 4.0. UWI.Com – The Internet Forms Company. 6 SEP 1997.
[2] Bray, T., Paoli, J. & Sperberg-McQueen, C.M. (Eds.) Extensible Markup Language (XML) 1.0. W3C Recommendation. http://www.w3.org/TR/1998/REC-xml-19980110. 10 FEB 1998.
[3] Gordon, M. (Ed.) UFDL v4.0.1 Specification. UWI.Com – The Internet Forms Company. 1993-1998.
Terms are defined in Section 1.2 of the XML specification [2].
XFDL instances are XML documents; the form definition is encoded using XML elements and attributes. In addition, XFDL imposes many constraints on the contents of the elements and the values of the attributes. In this specification, the nesting and sequence relationships between the elements and attributes are given, where possible, in DTD notation, while the constraints on element contents and attribute values are given in the BNF notation found in the XML specification. The DTD-syntax description of the elements and attributes is "almost complete" because XFDL allows the insertion of arbitrary non-XFDL elements in certain well-defined places. Furthermore, the allowed content of several XFDL elements depends on the value of a particular attribute; once again, neither of these facts is expressible using DTDs.
To serve its purpose, XFDL requires comprehensive presentation control and data typing machinery. This document describes a set of elements and attributes that meet these requirements. It may be the case that the presentation controls can be replaced by a W3C-specified stylesheet facility; however, it is not clear which one should be used for this purpose. In this specification, all elements and attributes that are candidates for replacement by a standardized style mechanism are marked [Display].
Similarly, it is almost certainly the case that XFDL's data typing controls can and should be replaced by a W3C-standardized set of data type specifiers when one becomes available. In this specification, all elements and attributes that are candidates for replacement by standardized data type specifiers are marked [Types].
An XFDL form is an XML document whose root element type is XFDL. The root element has a required version attribute, which is a numeric dotted triplet consisting of the major, minor, and maintenance versions of the XFDL to which the element content conforms. The XFDL element may also have a sid attribute; the sid attribute gives a scope identifier, which is discussed in Section 2.5.
|
[1] <!ATTLIST XFDL version CDATA #REQUIRED> [2] <!ATTLIST XFDL sid CDATA #IMPLIED> |
Here are the lexical constraints of the values of the version and sid attributes:
|
[3] versionAttrValue ::= Digit+ '.' Digit+ '.' Digit+ [4] sid ::= Letter (Letter | Digit | '_')* |
An XFDL element contains zero or more option elements followed by one or more page elements. The option elements that occur before the first page are referred to as form global options. They typically contain information applicable to the whole form or default settings for options appearing in the element content of pages.
|
[5] <!ELEMENT XFDL (%options;*, page+)> |
A page element contains zero or more page global options followed by zero or more item elements. Page global options typically contain information applicable to the whole page or default settings for options appearing within element content of items, and they take precedence over form global options. A page is also required to have a sid attribute.
|
[6] <!ELEMENT page (%options;*, %items;*)> [7] <!ATTLIST page sid CDATA #REQUIRED> |
The intention of using of multiple pages in a form is to show the user one page at a time. Each page should contain items that describe GUI widgets which allow users to switch to different pages without contacting a server program. XFDL allows the page switching items to be defined in the form so the form developer can add computations that control the flow of pages based on context.
An item is a single object in a page of a form. Some items represent GUI widgets, such as buttons, checkboxes, popup lists, and text fields. Other items are used to carry information such as an enclosed word processing document, a digital signature, daemon client-side actions, or application-specific job descriptions (such as workflow or ODBC requests).
An item can contain zero or more option elements. The options define the characteristics of the item. An item with zero options is completely defined by the option defaults. Each item is required to have a sid attribute.
|
[8] <!ELEMENT %items; (%options;*)> [9] <!ATTLIST %items; sid CDATA #REQUIRED> |
The parameter entity reference to "%item;" could be defined partially as
|
[10] <!ENTITY % item "(action | box | button | cell | check | combobox | data | field | help | label | line | list | popup | radio | signature | spacer | toolbar)" >> |
The details of each type of item listed in rule 10 are discussed in Section 5 and summarized here for convenience.
This is only a partial list of items. XFDL allows application-defined items in the form. Simple, static application-specific information can be expressed using XML processing instructions, but many server side applications for workflow and ODBC require complex instructions that can include the use of the XFDL compute system to collect information from around the form.
Options can appear as form globals, page globals, or as the contents of items. An option defines a named attribute of an item, page, or form. The parameter entity reference to "%option;" could partially be defined as follows:
|
[11] <!ENTITY % option "(activated | active | bgcolor | borderwidth | coordinates | data | datagroup | delay | editstate | filename | focused | fontcolor | fontinfo | format | group | help | image | itemlocation | justify | label | labelbgcolor | labelborderwidth | labelfontcolor | labelfontinfo | mimedata | mimetype | mouseover | next | previous | printsettings | saveformat | scrollhoriz | scrollvert | signature | signdatagroups | signer | signformat | signgroups | signitemrefs | signitems | signoptionrefs | signoptions | size | thickness | transmitformat | triggeritem | type | url | value | visible)" > |
Again, the definition is partial because XFDL also supports application-defined options. Typically, application-defined options occur in application-defined items, but they are also sometimes used in XFDL-defined items to store intermediate results of complex computations, thereby allowing the form developer to arbitrarily break down a problem into manageable pieces.
The options are fully discussed in section 6 and summarized here:
The content of an option can take one of three formats: simple character data, a compute, or an array of subordinate XML elements. The content attribute identifies which type of content will appear.
|
[12] <!ATTLIST %options; content (simple|compute|array) "simple"> |
The default is simple, and the content attribute is not required if the content is simple, in which case the option must contain text with no child elements:
|
[13] <!ELEMENT %options; (#PCDATA)> |
If the content expresses a compute, then the content must be present with the value "compute". The option may contain a cval element, which should contain simple character data for the current computed value of the option. If the cval element is absent, XFDL defines this to be equivalent to the presence of <cval></cval>. The option must contain a compute element. The compute element should contain a computational expression. It is typical to have a form run its computes on a client machine, then have server modules simply read the current values, ignoring the content of the compute element. In essence, an application can treat the compute content as character data unless it must run the computes. See Section 3 for details on how the compute expression is represented.
|
[14] <!ELEMENT %options; (cval?, compute)> [15] <!ELEMENT cval (#PCDATA)> [16] <!ELEMENT compute (#PCDATA)> |
The third case for an option's content is an array of subordinate elements. In this case, the content attribute is required and must be set equal to "array". The option must contain one or more array elements:
|
[17] <!ELEMENT %options; (%ae;+)> |
An example of an option that uses array element depth is bgcolor:
<bgcolor content="array"> <ae>255</ae> <ae>248</ae> <ae>220</ae> </bgcolor>
The array element takes the same content attribute that option elements do, and its contents are controlled by the value of this attribute in the same way.
This recursive definition permits arbitrary depth for XFDL arrays. In XFDL, the form developer is permitted to give names other than ae to array elements. The default array element name is ae, but a name can be assigned even if XFDL does not define it. For example,
<bgcolor content="array"> <red>255</red> <green>248</green> <blue>220</blue> </bgcolor>
A number of the XFDL-defined options use array elements (such as bgcolor, itemlocation, and format). XFDL does not often assign names to the array elements, so the default tag name of ae is used. Since the form developer can assign names to array elements, the parameter entity reference to "%ae;" can only be partially defined as follows:
|
[18] <!ENTITY % ae "(copies | dialog | length | message | orientation | pages | printpages | range | template | ae)"> |
The ampersand (&) and left angle bracket (<) are not permitted in character data content of XML elements since these characters mark the beginning of entity references and XML tags, respectively. Character content can include the ampersand and left angle bracket in a few different ways, such as using the XML entities & and < or simply wrapping the character content in a CDATA section. The character sequence ]]> also must not appear in character data content, but it also cannot appear in a CDATA section since it is the delimiter token that marks the end of a CDATA section. If the sequence ]]> must appear as character data, then the right angle bracket (>) should be expressed with an entity reference such as >.
These rules apply to all XFDL elements, but they are usually utilized when constructing XFDL computes, which use the left angle bracket for a less-than symbol and the ampersand for the logical-and operator. For example:
<active content="compute">
<compute>
<![CDATA[ AgeField.value < "18" && EmployedCheck.value=="on" ? "on" : "off" ]]>
</compute>
</active>
The close CDATA token (]]>) cannot appear in an XFDL compute except in a quoted string literal. Therefore, XFDL computes need not encode the right angle bracket (>) when using it to express the greater-than symbol (>) or the dynamic reference operator (->).
In XFDL, the mimedata option is used to store base-64 encoded binary data such as digital signatures, images, enclosed word processing or spreadsheet documents, etc. Base-64 encoding uses no characters that are illegal in character data, so mimedata content can be stored in a mimedata option element as simple character data. The only caveat is that since binary data tends to be long, XFDL processors are expected to "pretty print" the lines of base 64 using tabs, spaces and linefeeds such that the content appears to be indented with respect to the mimedata tags in text editors that wrap lines after 80 characters.
However, since XML preserves whitespace in element content, base-64 decoders for XFDL must be able to ignore an arbitrary amount of whitespace in the data.
An XFDL scope identifier, or sid, uniquely identifies an element within the scope of its logical parent. An XFDL element may have a sid attribute which uniquely identifies the form within a system of forms in a large deployment. Each page element must have a sid attribute that uniquely identifies the page within the surrounding XFDL form element. An item element must have a sid attribute that uniquely identifies the item within the surrounding page element.
In XFDL, each option element is defined to be uniquely identified within the scope of the surrounding item element by its XML tag, which is why options (and array elements) do not require a sid attribute. In XFDL, there are two kinds of array elements, unnamed and named. An unnamed array element is surrounded by <ae> and </ae> tags. A named array element has its XML tag as its sid. Named array elements cannot begin with the tag <ae>. Further, since the XML tag of a named array element is a sid, the XML tag of a named array element must be unique within its parent element.
The lexical structure of a sid differs from the XML language rule Name, which used to define the lexical structure of attribute values of type ID. The dash, period, and colon are not permitted in a sid due to conflicts with their use as the subtraction symbol, relative scope membership operator, and ternary conditional operator (?:), respectively. The lexical structure of a sid is not designed as a replacement for the XML ID feature, which assigns a globally unique name to an element.
XFDL processors are expected to preserve the XML prolog and epilog, the comments within the XFDL element, and all element attributes appearing in start tags but not specifically defined by XFDL. The attributes must be associated with their respective start tags, and the comments must be associated with the respective pages, items, options, or array elements to which they apply. The XFDL processor must be able to reproduce these language components for digital signatures and for saving or transmitting the form.
An XFDL compute can appear between <compute> and </compute>. This section defines the default infix notation for expressing computation expressions. As other appropriate XML languages are approved, they could be used in the content of a compute by defining a format attribute for the compute start tag. The default should be "infix" but the enumeration could be extended to include the names of supported formats. This version of XFDL only defines the default infix notation:
|
[19] <!ATTLIST compute format (infix) #FIXED "infix"> |
Most XFDL processors only need to preserve the compute as character data, but some applications must parse the text of computes, constructing a list of expression tree data structures to represent all computes in a form. This is necessary if the application must change the content of options or suboptions that are referred to by a compute. This section describes the syntax and operation of computes. Except for some minor modifications, the language rules in this section appear in Figure 2 of [1] as rules 6 to 19.
XFDL computes automatically support the notion of free form text found in most programming languages. With the exception of the contents of quoted strings (see Section 3.4), unlimited whitespace is permitted. Adding S? before and after every lexical token in every BNF rule in this section would unnecessarily obfuscate the presentation of what is essentially the standard BNF for mathematical and conditional expressions. Therefore, it is stated once here for the reader that all whitespace appearing outside of quoted strings is ignored.
An XFDL compute can be either a mathematical or conditional expression. A conditional expression has three parts separated by the ternary ?: operator. The first part is a Decision, which yields a boolean result. The consequences for a true and false boolean result recurse to the definition of Compute, permitting arbitrary nesting of decision logic.
|
[28] Compute ::= Expr | Decision '?' Compute ':' Compute |
The decision logic can apply logical-or (||), logical-and (&&), and logical negation (!) to the results of logical comparisons. The logical operators are left associative, and the comparators cannot be chained (e.g. a < b < c is illegal). The order of operations gives greatest precedence to negation, then logical-and, and least precedence to logical-or. To override this, parentheses can be used (e.g., the parentheses in (a<b || c<d) && e!=f cause the logical-or to occur first, and no parentheses are required if the logical-and should be performed first).
| [20] Decision ::= Decision ‘||’ AndDecision
| AndDecision [21] AndDecision ::= AndDecision ‘&&’ NotDecision | NotDecision [22] NotDecision ::= ‘!’ Comparison | Comparison [23] Comparison ::= ‘(’ Decision ‘)’ | Expr (‘<’ | ‘>’ | ‘<=’ | ‘>=’ | ‘==’ | ‘!=’) Expr |
Note that since Decision is capable of performing comparisons on the results of mathematical expressions, a Decision can ultimately start with an Expr. Therefore, a simple LR-type parser is required by XFDL computes.
A mathematical expression, denoted Expr, can include addition, subtraction, string concatenation, multiplication, division, integer modulus, unary minus, and exponentiation. All mathematical operators are left associative except unary minus and exponentiation. Further, proper order of operations is observed. Parentheses can be used to override the order of operations as shown in the non-terminal Value (defined later).
| [24] Expr ::= Expr ‘+’ Term |
Expr ‘-’ Term | Expr ‘+.’
Term | Term [25] Term ::= Term ‘*’ NFactor | Term ‘/’ NFactor | Term ‘%’ NFactor | NFactor [26] Nfactor ::= Factor | ‘-’ Factor [27] Factor ::= Value ‘^’ NFactor | Value |
A value can be a compute in parentheses, which provides an override for the order of operations. A value can be a quoted string (Section 3.4). A value can be an XFDL reference to an element whose text data should be obtained when the compute is evaluated (Section 3.5). Finally, a value can be obtained as the result of a function call (Section 3.6).
|
[28] Value ::= ‘(’ Compute ‘)’ | qstring | UFDLReference | FunctionCall |
The rules for recognizing a quoted string are quite difficult to express in BNF, but they are the usual rules that many high-level programming languages use to process quoted strings. The language rules for computes permit the recognition of a quoted string token using the italicized token name qstring.
An XFDL quoted string must be surrounded by double quotes. Whitespace before the open quote and after the close quote is ignored. Double quotes can be included by escaping them with a backslash (\). The escape sequences \n and \t result in a newline and a tab, respectively, in the quoted string content. Since the backslash is the escaping character, it must also be escaped to be inserted into the string content (e.g., \\). Finally, any byte value except 0 can be inserted into the quoted string content using \x followed by a two-digit hexadecimal number.
Quoted strings can also be of arbitrary length in XFDL. To increase human readability, XFDL supports multiline string continuation. If the next non-whitespace character appearing after a closing double quote is an open double quote, then the closing quote, whitespace, and open quote are discarded from the input stream.
Because each XFDL element’s scope identifier (sid) is unique only within the surrounding parent element, XFDL can support relative referencing. For example, in an element identified as Field1, if a computation includes the reference Field2.value, this means obtain the character data of the value option in the item Field2 on the same page. If Field2 is on a separate page, say Page2, then a compute in Field1 can still access its value using Page2.Field2.value.
XFDL references can also grow arbitrarily in the opposite direction to describe unbounded array element depth. This is accomplished by introducing a second scoping operator, the square brackets, to describe depth below the option level. For example, given the following piece of XFDL for a format option:
<format content="array"> <ae>dollar</ae> <range content="array"> <ae content="compute"> <cval>35</cval> <compute> Bill.value * "0.05" </compute> </ae> <ae content="compute"> <cval>700</cval> <compute> Bill.value </compute> </ae> </range> </format>
the reference format[0] yields ‘dollar’ and the reference format[range][1] yields ‘700’. If an array element is not named, then the zero-based numeric position of the array element is used in the square brackets. If the array element is named, then the scope identifier can be used in the square brackets. However, the numeric position can also be used, e.g.format[1][1] also yields ‘700’.
The above description covers static references. Dynamic references are a second important component of the UFDL referencing model. The left associative operator ->, known as the indirect membership operator, expects to receive a static or dynamic reference as a left operand. The run-time value of the static or dynamic reference must conform to the syntax of the ItemRef non-terminal. The right operand of the indirect membership operator is an option reference. At run-time, the left operand is evaluated, yielding a static item reference to an XML element representing a UFDL item. This run-time item reference is combined with the right operand of the indirect membership operator to yield an option or array element whose simple data is the result of the evaluation.
The simplest example of a dynamic reference is retrieving the text of the selected cell in a UFDL listbox or popup. As is discussed in Section 6, the value option of a list or popup is equal to the item reference of the cell item for the selected cell. Thus, given an example popup that offers a selection of days of the week, the text for the day of week selected by the user is obtained by Popup_DayOfWeek.value->value.
Finally, note that XFDL references support forward referencing. An XFDL reference can refer to any option or array element.
| [29] UFDLReference ::= StaticRef | StaticRef ‘->’
DynamicRef [30] StaticRef ::= ItemRef ‘.’ OptionRef | OptionRef [31] ItemRef ::= ((sid ‘.’)? sid ‘.’)? sid [32] DynamicRef ::= DynamicRef ‘->’ OptionRef | OptionRef [33] OptionRef ::= sid (‘[’ (Digit+ | sid) ‘]’)* |
Function calls run code that may be external to the XFDL form definition. A set of predefined functions for doing standard mathematical operations, string manipulations, etc. is given in Section 7. The LibName allows functions to be grouped into separate namespaces, but predefined functions do not require a LibName.
| [34] FunctionCall := (LibName ‘.’)? FunctionName
‘(’ (Compute (‘,’ Compute)*)?
‘)’ [35] LibName ::= sid [36] FunctionName ::= sid |
This section presents a high-level algorithm describing how a XFDL Compute System must run the computes in a form. When a form starts, it must run all computes to provide content for the current value tags. This is accomplished by passing nil to RunXFDLComputes() as the change list. Each time an event, such as user input or an API call, causes a change to the simple data content or current value of an option or array element, RunXFDLComputes() is called with a change list containing only the element that changed.
|
Function: RunXFDLComputes Input: F (all form elements), C (computes), E (list of changed elements) Output: Z (set of all elements that changed due to running computes) Z = empty list Do { NewChangeList = empty list For I = 1 to n(C) do Pertinent = (E == nil) ? true : false For J = 1 to n(E) If CI contains EJ, then Pertinent = true If Pertinent FP = parent element containing CI If current value of FP is not equal to eval(CI) NewChangeList += FP Z += FP cval(FP) = eval(CI) E = NewChangeList } while (E is not empty) return Z |
If a string of simple data is assigned to an element via a public API call (e.g. as the result of user input or server-side processing), then the compute and its current value are destroyed.
The algorithm refers to the computes using one-based indexing (even though the computes may not be represented by an array in a given implementation). The symbol n denotes the number of computes in the form. For each compute CI, the expression tree is checked to see whether it contains a static or dynamic reference to any element EJ in the change list. If so, then CI is dependent on EJ and must be evaluated. The result of eval(CI) does not equal the current content of the element parent FP of CI, then FP is added to the new change list and the current value (the cval content) of FP is set equal to the result of eval(CI)—using a non-public API call such that the compute is not destroyed.
The algorithm does not show the semantics for dealing with circular references. Circular references are defined to be invalid XFDL. The computational output that results from running a circular chain of references is undefined. However, the behavioral result is defined. An XFDL processor should terminate in a finite amount of time upon encountering a chain of circular references. There is one exceptional case that the RunXFDLComputes algorithm is designed to permit. A compute that contains a self-reference is, in a graph theoretic sense, a circular reference. However, XFDL processors must support computes that use conditional logic to terminate computations after one iteration. Here is an example:
<user_email content="compute"> <cval></cval> <compute> user_email == "" ? prefs.p1.ReturnAddress.value : user_email </compute> </user_email>
In the first iteration, the current value of user_email is empty, so the compute runs and changes the current value to be equal to the content of a particular value option in another form called prefs. The change causes user_email to enter the NewChangeList. During the following iteration of the loop, the compute runs again, but the current value of user_email does not change, so user_email does not enter the new change list.
The evaluation function must perform run-time type identification on operands. The only permitted operation on strings is addition (by + or +.). Dates can only be added and subtracted. Numeric addition should only be performed if both operands are numeric.
The first example in Figure 1 is designed to show a whole XFDL form. After the XML prolog, the root XFDL element declares a version of 4.1.0. There is a form global variable stating that all pages should have a medium gray background color given by the RGB triplet (128, 128, 128). However, the page global background color is set to RGB (192,192,192)-- light gray. Since page globals override form globals, the page will have a light gray background.
The background color option uses element depth to express an array. This is not needed if the color is given by name, but it is required if the background color is given as an RGB triplet. XFDL options and array elements are consistent in their use of element depth.
The page global options also contain a label option that declares the caption bar text for the window used to display the form page. Note that 'label' is one of those keywords that is used both as an item type and an option scope identifier. Widgets such as fields and comboboxes can have text labels associated with them, but image and text labels can also be placed anywhere on the form, so a separate label item is required in the language. The XFDL parser distinguishes a global option from an item based on the absence or presence, respectively, of the 'sid' attribute.
After the global options, the page contains three fields: the first two collect side lengths for a right triangle; the third computes the length of the hypotenuse of the right triangle with the given side lengths. An editstate of readonly is given to prevent the user from accidentally destroying the compute by entering a value for field C.
<?xml version="1.0"?> <XFDL version="4.1.0"> <bgcolor content="array"> <ae>128</ae> <ae>128</ae> <ae>128</ae> </bgcolor> <page sid="Pythagorean_Theorem"> <bgcolor content="array"> <ae>192</ae> <ae>192</ae><ae>192</ae> </bgcolor> <label>Pythagorean Theorem Form</label> <field sid="A"> <label>Enter A:</label> <value>3</value> </field> <field sid="B"> <label>Enter B:</label> <value>4</value> </field> <field sid="C"> <label>Hypotenuse length C:</label> <editstate>readonly</editstate> <value content="compute"> <cval>5</cval> <compute>sqrt(A.value^"2" + B.value^"2")</compute> </value> </field> </page> </XFDL> |
The second example in Figure 2 does not include the XML prolog nor the declarations for the root XFDL element and page. The example only shows two items. It is designed to demonstrate deeper element depth and more computes than the form shown in Figure 1.
The first item is a field that purports to ask the user what portion of a bill, such as a credit card bill, will be paid. The format option contains a number of array elements. The first of them contains the word 'dollar' and represents the type of user input that will be permitted in the field. In the typical format option (see Section 6), the input type is not named and would therefore appear between the <ae> and </ae> tags. However, the form developer can assign names to array elements that are not required by the XFDL specification to have a name. The second and third array elements in the format option are unnamed. They provide additional information about the format, such as the fact that user input is mandatory (i.e., emptiness is not a permitted response), and that a dollar sign should be prepended to the user's input.
The last array element declared in the format option in Figure 2 is named 'range', and it contains an array of two elements that define the lower and upper bounds of the user's input. For a credit card bill, the range of payment is typically bounded above by what the cardholder owes and bounded below by some small percentage of the current balance. Thus, the format option shows the possibility of unlimited array element depth as well as the inclusion of computes deep within the element hierarchy. The XFDL offers what is known as a fine-grain compute system.
The second item element in Figure 2 is a label that demonstrates a longer compute expression, including several array element references. Note that at the end of the compute, the 700 is concatenated to the end of the string rather than added to the 35. Because addition is left associative, the entire portion of the string prior to the 700 has already been constructed. Therefore, due to run-time type identification, the last + operator performs string concatenation.
<field sid="PayNow"> <label>What portion of this bill do you want to pay now?</label> <value>0</value> <format content="array"> <type>dollar</type> <ae>add_ds</ae> <ae>mandatory</ae> <range content="array"> <ae content="compute"> <cval>35</cval> <compute> Balance.value * "0.05" </compute> </ae> <ae content="compute"> <cval>700</cval> <compute> Balance.value </compute> </ae> </range> </format> </field> <label sid="DemonstrateSuboptionReferencing"> <value content="compute"> <cval>dollar add_ds 35700</cval> <compute> PayNow.format[type] + " " + PayNow.format[1] + " " + PayNow.format[range][0] + PayNow.format[range][1] </compute> </value> </label> |
Items are the basic elements of a page. The syntax of an item definition is as follows:
<itemType sid="itemTag"> |
The sid attribute uniquely identifies an item. Every item tag in a page must be unique. The ItemType element identifies the type of item to create. (For example, <field…> defines the item as a field.) This section contains information about XFDL-defined item types and the options available for each.
Note: Defining an option more than once in an item’s definition is not allowed.
See the section "6. Details on Options and Array Elements" for descriptions of each option type.
Specifies form-initiated actions that execute automatically. The actions can be any of the following types: link, replace, submit, done, display, print, cancel.
See the type description in the 'Options' section for a description of each of these actions.
Action items can be defined to occur only once or repeat at specified time intervals. They can be defined to occur after the page opens but before the page appears. See the section on the delay option for information on timing options.
Action items can trigger either background actions or actions involving user interaction. In fact, if the form contains only hidden items such as action items, then the whole form operates in the background. Such forms are called daemon forms.
activated, active, data, datagroup, delay, transmitformat, type, url
Repeating automatic actions is one method of creating a sparse-stated connection. It allows the form to indicate periodically to a server application that it is still running. Use the delay option to specify repetition.
Actions, by the form definition rules, reside on a page; therefore, actions occur only when the page is open, and repeating actions stop when the page closes. Actions defined to occur before the page displays, occur each time the page opens.
The following action will send a status message to the server. The transaction happens automatically every 10 minutes (600 seconds).
<action sid="sendStatus_action"> <delay content="array"> <ae>repeat</ae> <ae>600</ae> </delay> <type>submit</type> <url content="array"> <ae>http://www.server.com/cgi-bin/recv_status</ae> </url> </action>
Specifies a square box on the form. Other items may be positioned on top of boxes (using itemlocation). The purpose of box items is simply to add visual variety to the form.
bgcolor, borderwidth, fontinfo, itemlocation, size
To make the box more visible, assign a background color that differs from the page background color (the default).
When setting the size option of a box, the height and width of the box will be based on the average character size for the font in use (set with the fontinfo option).
The following example shows a typical box description. The box is 25 characters wide and 4 characters high. The background color is blue.
<box sid="blue_box"> <bgcolor content="array"> <ae>blue</ae> </bgcolor> <size content="array"> <ae>25</ae> <ae>4</ae> </size> </box>
Specifies a click button that performs an action when selected. Buttons can request data from a web server, submit or cancel the form, sign the form, save it to disk, or enclose external files.
activated, active, bgcolor, borderwidth, coordinates, data, datagroup, focused, fontcolor, fontinfo, format, help, image, itemlocation, justify, mouseover, next, signature, signdatagroups, signer, signformat, signgroups, signitemrefs, signitems, signoptionrefs, signoptions, size, transmitformat, type, url, value
The button’s label is defined by the value option. If no value option exists, the default label is blank.
When setting the size option of a button, the height and width of the button will be based on the average character size for the font in use (set with the fontinfo option).
If a button's image option points to a data item that dynamically changes its mimedata (but not its item tag), then the button will update the image it displays. For information on how to update an image by enclosing a new one, see the data option description.
The format option is available in buttons in order to force users to sign forms before submitting them.
There are two steps to making a signature button mandatory:
Assign the following elements to the format option: string and mandatory.
Set the button's value equal to the button's signer option setting.
Setting the format to mandatory specifies that the button must have a value setting that is not empty before the user submits the form. Equating the value to the setting of the signer option ensures that the only way a button's value is set is if somebody uses it to sign the form. (The signer option stores the identity of the person who signed the form using the button.)
Behavior of Buttons in Digital Signatures
A digital signature button is the means by which the user can digitally sign a form. To make a button a signature button, set its type to signature.
A signature button can be set up to sign the whole form or just part of it by setting up filters on the signature, using the signdatagroups, signgroups, signitemrefs, signitems, signoptionrefs, and signoptions options.
Important: At a minimum, the triggeritem and coordinates options should always be filtered out. These options change when a submission is triggered or when a user clicks an image button, respectively. Filtering out parts of the form that a subsequent user will change, including subsequent signatures and signature buttons and custom options that might change (like odbc_rowcount), should also be taken into consideration.
Signature buttons allow users to do the following:
Sign the form or portion of the form the button specifies.
Delete their signatures (a signature can be deleted only by the user whose signature it is, and if the signature is currently valid and not signed by some other signature).
View the signature and view the XFDL text of what the signature applies to.
All option references, calculations, and other formulas in any signed portion of a form are frozen once they have been signed. Their setting will be valued at the setting they contained at the moment when the signature was created. If the user deletes the digital signature, however, then the formulas will become unfrozen, and will change dynamically as normal.
The usual options for other buttons (i.e. size, image, value) can also be used with signature buttons.
Buttons that trigger form processing requests must have a type option setting of submit or done. The definition for such a button might look like this:
<button sid="submit_button"> <value>Process Form</value> <fontinfo content="array"> <ae>Helvetica</ae> <ae>18</ae> <ae>bold</ae> <ae>italic</ae> </fontinfo> <type>done</type> <url content="array"> <ae>http://www.server.com/cgi-bin/formProcessor</ae> </url> </button>
This button encloses an external file in the form. The action to enclose a file is enclose. The datagroup option identifies the list of datagroups, or folders, in which the user can store the enclosed file. An enclose button might take the following form:
<button sid="enclose_button"> <value>Enclose File</value> <fontinfo content="array"> <ae>Helvetica</ae> <ae>18</ae> <ae>bold</ae> <ae>italic</ae> </fontinfo> <type>enclose</type> <datagroup="array"> <ae>Images_Asia</ae> <ae>Images_Eur</ae> <ae>Images_SAmer</ae> </datagroup> </button>
This button will allow users to enclose files into one of three datagroups (folders): Images_Asia, Images_Eur, Images_SAmer.
Populates combobox, list and popup items. A cell can belong to multiple comboboxes, lists and popups. See the combobox, list and popup item sections for information on associating cells with these items.
Cells fall into two categories according to their behavior
activated, active, data, datagroup, group, label, transmitformat, type, url, value
The following example shows a list with three cells. To learn how to get the value of the user's selection, see Usage Notes below.
<popup sid="CountryPopup"> <label>Country</label> <group>country</group> <format content="array"> <ae>string</ae> <ae>mandatory</ae> </format> </popup> <cell sid="albCell"> <value>Albania</value> <group>country</group> <type>select</type> </cell> <cell sid="algCell"> <value>Algeria</value> <group>country</group> <type>select</type> </cell> <cell sid="banCell"> <value>Bangladesh</value> <group>country</group> <type>select</type> </cell>
Use the type option to establish a cell’s behavior. Select cells that have a type of select (the default type).
Cells can have both value and label options. These options affect the form differently depending on whether the cell is linked to a combobox, a popup, or a list. In general, the label of the cell will be displayed as a choice, while the value of the cell will be displayed if that cell is selected. For more information, refer to the appropriate item type.
Cells take their color and font information from the combobox, list and popup items with which they are associated. In this way, a cell’s appearance can vary according to the list the user is viewing.
To get the value of a cell that a user has selected from a list, it is necessary to dereference it in the following manner:
page_tag.list_tag.value->value
For example:
<compute>page1.countryPopup.value->value</compute>
When a user selects a cell from a list, the item tag of the cell is stored as the value of the list. Hence the dereference syntax.
Provides a simple check box to record a selected or not selected answer from a user. A selected check box appears filled while a deselected box appears empty.
The exact appearance of the check box is platform dependent; but the shape is rectangular. The check box appears as a normal check box for the users of each platform.
active, bgcolor, editstate, focused, fontcolor, fontinfo, help, itemlocation, label, labelbgcolor, labelborderwidth, labelfontcolor, labelfontinfo, mouseover, next, size, value
The value option setting indicates the user’s answer. If the user selects or checks the check box, the value option contains on, otherwise it contains off. The default value is off.
Check boxes do not belong to groups like radio buttons—each check box may be turned on or off independently of the others.
The label option defines the label for the check box. The label appears above the check box and aligned with the box's left edge. There is no default label.
When setting the size option of a check box, the height and width of the bounding box will be based on the average character size for the font in use (set with the fontinfo option).
The fontcolor option determines the color of the check box fill pattern (default is red).
This value option setting in this check box is on, so the check box will appear selected when it displays. The item’s label is Activate Health Plan, and the label will display in a Times 14 Bold font colored blue.
<check sid="healthPlan_check"> <value>on</value> <label>Active Health Plan</label> <labelfontinfo content="array"> <ae>Times</ae> <ae>14</ae> <ae>bold</ae> </labelfontinfo> <labelfontcolor content="array"> <ae>blue</ae> </labelfontcolor> </check>
Comboboxes act like a hybrid of a field and a popup. Unopened, a combobox with a label occupies the same space as two labels, and a combobox without a label occupies the same space as a single label. After a user chooses a cell, the combobox closes (that is, returns to its unopened state).
If none of the cells are appropriate, the user can type other information into the combobox. When information is typed in, it is stored in the value option of the combobox. When a cell is selected, the value option stores the value of that cell.
A combobox’s label appears above the combobox item.
activated, active, bgcolor, editstate, focused, fontcolor, fontinfo, format, group, help, itemlocation, label, labelbgcolor, labelborderwidth, labelfontcolor, labelfontinfo, mouseover, next, previous, size, value
Place cells in a combobox by creating a group for the combobox and assigning cells to the group. Create a group using the group option in the combobox definition. Assign cells to the group using the group option in the cell definition.
Cells that have a label option will display that label in the list. Otherwise, the value of the cell will be displayed. When a cell is selected, the value of that cell will be displayed in the combobox and stored internally.
To get the value of a cell that a user has selected from a list, it is necessary to dereference it in the following manner:
page_tag.list_tag.value->value
For example:
<compute>page1.countryPopup.value->value</compute>
When a user selects a cell from a list, the item tag of the cell is stored as the value of the list. Hence the dereference syntax.
Combobox, popup, and list items with the same group reference display the same group of cells.
When first viewed, a combobox will display its value. If no value is set, the combobox will be empty.
The value option will contain one of the following:
The value of the most recently chosen selection.
Nothing if an action was most recently chosen.
The text entered if something was typed in most recently.
When setting the size option of a combobox, the height and width of the popup will be based on the average character size for the font in use (set with the fontinfo option).
The label option sets the text displayed above the item, as with a field.
When setting the editstate option, the combobox will behave in the following manner:
A readwrite setting will cause it to function normally.
A readonly setting will cause the combobox to refuse all input, although it will function normally otherwise and formulas will still be able to change the value.
A writeonly setting will cause the combobox to use "password" characters in its field contents, but the list of choices will still be displayed in plain text.
When a format is applied to a combobox, the formatting will be applied to the value of each cell linked to the combobox. Those cells that fail the check will be flagged or filtered. Those cells that pass the check will have their value replaced with a formatted value. See the format option for more information.
If any two comboboxes, lists, or popups use the same set of cells, they must apply the same formatting.
This is an example of a combobox containing a set of selections allowing users to choose a color.
<combobox sid="CATEGORY_POPUP"> <group>combo_Group</group> <label>Choose a Color:</label> </combobox>
The default label is "Choose a Color:". This will display above the combobox. Until the user types in something or makes a selection, the field area of the combobox will be blank.
These are the cells that make up the combobox. They are select cells and they belong to the same group as the combobox: combo_Group.
<cell sid="RED_CELL"> <group>combo_Group</group> <type>select</type> <value>Red</value> </cell> <cell sid="WHITE_CELL"> <group>combo_Group</group> <type>select</type> <value>White</value> </cell> <cell sid="BLUE_CELL"> <group>combo_Group</group> <type>select</type> <value>Blue</value> </cell>
Stores an information object such as an image, a sound, or an enclosed file in an XFDL form. Data in data items must be encoded in base64 format.
Data items are created automatically when files are enclosed in a form. Enclose files using items with a type option setting of enclose.
datagroup, filename, mimedata, mimetype
Store the data in the mimedata option, and the data’s MIME type in the mimetype option.
If a button or cell of type enclose contains a data option that points to a data item (as opposed to using the datagroup option), then special rules apply to the data item's behavior. If a user encloses a new data item using that button, the new information overwrites the old. For example, if the data item originally contained a jpeg image of a dog, and then a user enclosed a png image of a house, then the data item's mimedata, mimetype, and filename options update themselves to contain the information about the house image.
This is an example of a data item produced as the result of enclosing a file (the data component used here is artificial, and is only for demonstration purposes).
<data sid="Supporting_Documents_1"> <filename>smithltr.doc</filename> <datagroup content="array"> <ae>Supporting_Documents</ae> </datagroup> <mimetype>application/uwi_bin</mimetype> <mimedata>R0lGODdhYABPAPAAAP///wAAACwAAAAAYABPAAAC/4SPqcvtD02Y Art68+Y7im7ku2KkzXnOzh9v7qNw+k+TbDoLFTvCSPzMrS2YzmTE+p yai3YUk9R6hee2JFP2stju+uG0ptvdeKptb+cX8wfY1jdYU4ehKDi3pdJw 44yAJEqcW28cA5M0oEKnqKasZwydrK9Wo6JTtLG9p5iwtWi8Tbi/b7E0 rvKixzbHJyrDq2uNggaXUs1NlLi36AW3AGv7VWhIPA7TzvdOGi/vvr0Of ft3Nrx89JewCQJYTirxi2PwgnRpNoMV5FIIboOnqTszFLFIMhQVI0yOz </mimedata> </data>
The field item creates a text area where users can display and enter one or more lines of data. The field’s characteristics determine the number of lines, the width of each line, and whether the field is scrollable.
Field data can be protected from modification, made to display in the system password format (typically, hidden from view), and forced to conform to data type and formatting specifications.
active, bgcolor, editstate, focused, fontcolor, fontinfo, format, help, itemlocation, justify, label, labelbgcolor, labelborderwidth, labelfontcolor, labelfontinfo, mouseover, next, size, value
When setting the size option of a field, the height and width of the field will be based on the average character size for the font in use (set with the fontinfo option).
The editstate option determines whether the field is read only, write only (for passwords, for example) or available for both reading and writing.
The format option specifies the data type of the field’s data. It also contains flags that allow the application of specified edit checks and formatting to the data.
The label option defines the field’s label. The label is placed above the field and aligned with the field's left edge.
The scrollvert and scrollhoriz options govern a field’s scrolling characteristics. They must be set to always to permit scrolling. With scrolling enabled, scroll bars display along the bottom (horizontal scrolling) and right (vertical scrolling) edges of the field.
This is an example of a single line field item that allows 20 characters of input. An initial value of 23000 has been defined for the field. When the form appears, the field will contain this value.
<field sid="income_field"> <label>Annual income</label> <value>23000</value> <size content="array"> <ae>20</ae> <ae>1</ae> </size> <fontinfo content="array"> <ae>Courier</ae> <ae>12</ae> <ae>plain</ae> </fontinfo> <labelfontinfo content="array"> <ae>Helvetica</ae> <ae>12</ae> <ae>plain</ae> </labelfontinfo> <labelfontcolor="array"> <ae>blue</ae> </labelfontcolor> </field>
Defines a help message that can be used to support various external items in the form. Separate help item can be created for every item supported, or one help item can be used to support several items.
active, value
The help item’s value option contains the help message text.
The link between the help item and the supported item is created by the help option in the supported item’s definition. The help option contains the help item’s item reference.
This is an example of a button for which help information is available.
The following is the button definition with the help item’s item reference in the help option:
<button sid="fullPicture_button"> <value>View Full-Sized Picture</value> <help>button help</help> <fontinfo content="array"> <ae>Times</ae> <ae>14</ae> <ae>plain</ae> </fontinfo> <type>link</type> <url content="array"> <ae>http://www.server.com/application/fullPic.frm</ae> </url> </button>
The following example shows the help item referred to in the button definition. The contents of the value option are used as the help message when the user asks for help with the button.
<help sid="button_help"> <value>Pressing this button will bring a full-sized image in a form down to your viewer.</value> </help>
Defines a static text message or an image to display on the form. If both an image and a text message are defined for the label, the image takes precedence in viewers able to display images.
active, bgcolor, fontcolor, fontinfo, format, help, image, itemlocation, justify, size, value
To define the text for a label, use the value option. To define an image for a label, use the image option.
To create a multiple line text message, add line breaks to the message text. Use the escape sequence ‘\n’ to indicate a line break.
When setting the size option of a label, the height and width of the label will be based on the average character size for the font in use (set with the fontinfo option).
If a label's image option points to a data item that dynamically changes its mimedata (but not its item tag), then the label will update the image it displays. For information on how to update an image by enclosing a new one, see the data option description.
The label's background color defaults to being transparent– and thus the label will take the background color of whatever item it is over. For example, it is possible to place a label inside a colored box (in order to make a title section that stands out) without specifying a background color for the label.
This is an example of a multiple-line text label.
<!--Specify right justification for this label.--> <label sid="RHYME LABEL"> <value>Little miss Muffet Sat on her tuffet, Eating her curds and whey. When along came a spider, who sat down beside her, and frightened miss Muffet away!</value> <fontinfo content="array"> <ae>Times</ae> <ae>16</ae> <ae>italic</ae> </fontinfo> </label>
Draws a simple vertical or horizontal line on the form. Lines are useful for visually separating parts of a page.
fontcolor, fontinfo, itemlocation, size, thickness
Specify the dimensions of a line using the size and thickness options. The size option determines whether the line is vertical or horizontal. If the horizontal dimension is set to zero, then the line is vertical. If the vertical dimension is set to zero, then the line is horizontal. Size is calculated in characters.
The thickness option determines how thick the line will be. Thickness is calculated in pixels.
The fontinfo option information is used when calculating the line’s size. The size option’s unit of measurement is characters; therefore, choice of font can affect the size. See the size option for more information.
The fontcolor option defines the color of the line.
This is an example of a horizontal line with a thickness of five pixels.
<line sid="BLUE_LINE"> <size content="array"> <ae>40</ae> <ae>0</ae> </size> <thickness>5</thickness> </line>
Creates a list from which users can make selections (as in a list of names) and trigger actions (such as enclosing files and submitting the form). A list can contain both selections and actions.
The entries in the list are cell items. Selections are cells with a type option setting of select. Actions are cells with any other type option setting.
active, bgcolor, editstate, focused, fontcolor, fontinfo, format, help, itemlocation, label, labelbgcolor, labelborderwidth, labelfontcolor, labelfontinfo, mouseover, next, size, value
Place cells in a list by creating a group for the list and assigning cells to the group. Create a group using the group option in the list definition. Assign cells to the group using the group option in the cell definition.
Cells that have a label option will display that label in the list. Otherwise, the value option of the cell will be displayed.
To get the value of a cell that a user has selected from a list, it is necessary to dereference it in the following manner:
page_tag.list_tag.value->value
For example:
<compute>page1.countryPopup.value->value</compute>
When a user selects a cell from a list, the item tag of the cell is stored as the value of the list. Hence the dereference syntax.
List, combobox and popup items with the same group reference display the same group of cells.
The value option will contain one of the following:
The item reference of the most recently chosen cell if the cell was of type "select".
Nothing if the cell most recently chosen was of any type other than "select".
Define the list’s label using the label option.
When setting the size option of a list, the height and width of the list will be based on the average character size for the font in use (set with the fontinfo option).
A vertical scroll bar will appear beside the list if the number of cells is greater than the height (defined with the size option) of the list.
When a format is applied to a list, the formatting will be applied to the value of each cell linked to the list. Those cells that fail the check will be flagged or filtered. Those cells that pass the check will have their value replaced with a formatted value. See the format option for more information.
If any two comboboxes, lists, or popups use the same set of cells, they must apply the same formatting.
This is an example of a list containing three actions: submit form, save form, and cancel form.
Here is the list definition.
<list sid="MAINMENU_LIST"> <group>list_Group</group> <label>Options Menu</label> <labelfontcolor content="array"> <ae>blue</ae> </labelfontcolor> <size content="array"> <ae>3</ae> <ae>20</ae> </size> </list>
These are the cells that make up the list. They are action cells and they belong to the same group as the list: list_Group.
<cell sid="SUBMIT_CELL"> <group>list_Group</group> <type>submit</type> <url content="array"> <ae>http://www.server.com/cgi-bin/processForm</ae> </url> <value>Submit Form</value> </cell>
<cell sid="SAVE_CELL"> <group>list_Group</group> <type>save</type> <value>Save Form</value> </cell>
<cell sid="CANCEL_CELL"> <group>list_Group</group> <type>cancel</type> <value>Cancel this Form</value> </cell>
Creates a popup menu from which users can make selections (as in a list of names) and trigger actions (such as enclosing files and submitting the form). A popup can contain both selections and actions.
The entries in the popup are cell items. Selections are cells with a type option setting of select. Actions are cells with any other type option setting.
Popups act like a hybrid of a label, a button, and a list. Unopened, a popup occupies only the space required for its label. Open, the popup displays a list of selections and actions. After a user chooses a selection or an action, the popup closes (that is, returns to its unopened state). A popup’s label displays inside the popup item.
activated, active, bgcolor, borderwidth, editstate, focused, fontcolor, fontinfo, group, help, itemlocation, justify, label, mouseover, next, size, value
Place cells in a popup by creating a group for the popup and assigning cells to the group. Create a group using the group option in the popup definition. Assign cells to the group using the group option in the cell definition.
Cells that have a label option will display that label in the list. Otherwise, the value of the cell will be displayed. When a cell is selected, the value of that cell will be displayed in the popup.
For example, if cell had a value of "USA", and a label of "United States of America", the full version would be shown in the popup list. Once the cell was selected, the popup would display the abbreviation.
To get the value of a cell that a user has selected from a list, it is necessary to dereference it in the following manner:
page_tag.list_tag.value->value
For example:
<compute>page1.countryPopup.value->value</compute>
When a user selects a cell from a list, the item tag of the cell is stored as the value of the list. Hence the dereference syntax.
Popup, combobox and list items with the same group reference display the same group of cells.
The value option will contain one of the following:
When setting the size option of a popup, the height and width of the popup will be based on the average character size for the font in use (set with the fontinfo option).
The label option contains the popup’s default label. When the value option is empty, the default label displays. Otherwise, the label of the cell identified in the value option appears.
When a format is applied to a popup, the formatting will be applied to the value of each cell linked to the popup. Those cells that fail the check will be flagged or filtered. Those cells that pass the check will have their value replaced with a formatted value. See the format option for more information.
If any two comboboxes, lists, or popups use the same set of cells, they must apply the same formatting.
This is an example of a popup containing a set of selections allowing users to choose a category.
Here is the popup definition. The default label is "Choose a Category:". This will display until a user makes a selection. Afterwards, the cell’s value will display as the label.
<popup sid="CATEGORY_POPUP"> <group>popup_Group</group> <label>Choose a Category:</label> </popup>
These are the cells that make up the popup. They are select cells and they belong to the same group as the popup: popup_Group.
<cell sid="HISTORY_CELL"> <group>popup_Group</group> <type>select</type> <value>World History</value> </cell>
<cell sid="SCIENCE_CELL"> <group>popup_Group</group> <type>select</type> <value>Physical Sciences</value> </cell>
<cell sid="MUSIC_CELL"> <group>popup_Group</group> <type>select</type> <value>Music</value> </cell>
Intended for use with one or more other radio button items. A group of radio buttons presents users with a set of mutually exclusive choices. Each radio button represents one choice the user can make.
There is always one selected radio button in the group. As well, since radio buttons present a mutually exclusive set of choices, only one radio button in a group can be selected. When a user chooses a radio button, that radio button becomes selected.
A selected radio button appears filled in some way. All other radio buttons in the group appear empty.
active, bgcolor, borderwidth, editstate, focused, fontcolor, fontinfo, group, help, itemlocation, label, mouseover, next, size, value
Group radio buttons by assigning them to the same group. Do this by including the group option in each radio button’s definition, and using the same group reference in each case.
The value option contains the status indicator. It can be either on or off. The value on indicates a status of chosen. The value off indicates a status of not chosen. The default status is not chosen.
When the form opens, if no radio button has the status chosen, then the last radio button defined for the group becomes chosen. If multiple radio buttons are chosen, then only the last ‘chosen’ radio button retains that status.
The label option defines a label to appear above the radio button and aligned with its left edge.
When setting the size option of a radio button, the height and width of the bounding box will be based on the average character size for the font in use (set with the fontinfo option).
The fontcolor option determines the color of the radio button fill pattern (default is red).
This example shows a group of three radio buttons. The first radio button is the initial choice: the value option setting is on. The buttons all belong to the group search_Group.
<radio sid="NAME_RADIO"> <value>on</value> <group>search_Group</group> <label>Search by Name</label> </radio>
<radio sid="NUMBER RADIO"> <group>search_Group</group> <label>Search by Number</label> </radio>
<radio sid="OCCUPATION RADIO"> <group>search_Group</group> <label>Search by Occupation</label> </radio>
As shown here, only the chosen radio button needs to have a value option setting. The remaining radio buttons will receive the (default) value setting of off.
Contains a digital signature and the data necessary to verify the authenticity of a signed form. It is created by a form viewer or other program when a user signs a form (usually using a digital signature button). The signature item contains an encrypted hash value that makes it impossible to modify the form without changing the hash value that the modified form would generate. To verify, one can generate the hash value and then see if it matches the one in the signature.
mimedata, signature, signdatagroups, signer, signformat, signgroups, signitemrefs, signitems, signoptionrefs, signoptions
When a user signs a form using a signature button, the viewer creates the signature item as specified in the button's signature option. The viewer also associates the signature with the signature button, using the signature's signature option.
When a user signs a form, the signer, signformat, signgroups, signitemrefs, signitems, signoptionrefs, and signoptions options are copied from the button description to the signature description.
A copy of the XFDL description of the form or portion of the form that is signed is included in the signature's mimedata option. This data is encrypted using the hash algorithm specified in the button's signformat option.
When a program checks a signed form, it compares the data in the mimedata option with that of the portion of the form that is apparently signed. If the descriptions match, then the signature remains valid. If the signatures do not match, the signature breaks, and the user is prompted.
An attempt to create a signature will fail if:
The item named by the signature button's signature option already exists.
The signature button is already signed by any signature in the form.
The signer's private key is unavailable for signing.
Filters can be used to indicate which items and options to keep and to omit. The explicit and implicit settings of an existing filter take precedence over an implication that might be drawn from a non-existing filter. Set up these filters in the signature button description.
To use digital signatures, it is necessary for the user to obtain a digital signature certificate.
This example shows a signature item below the signature button that created it.
<button sid="empSigButton"> <type>signature</type> <value content="compute"> <compute>signer</compute> </value> <signer></signer> <format content="array"> <ae>string</ae> <ae>mandatory</ae> </format> <signformat>application/x-xfdl;csp="Microsoft Base Cryptographic Provider v1.0";csptype=rsa_full;hashalg=sha1</signformat> <signoptions content="array"> <ae>omit</ae> <ae>triggeritem</ae> <ae>coordinates</ae> </signoptions> <signitemrefs content="array"> <ae>omit</ae> <ae>PAGE1.mgrSigButton</ae> <ae>PAGE1.admSigButton</ae> <ae>PAGE1.empSignature</ae> <ae>PAGE1.mgrSignature</ae> <ae>PAGE1.admSignature</ae> </signitemrefs> <signature>empSignature</signature> </button> ... <signature sid="empSignature"> <signformat>application/x-xfdl;csp="Microsoft Base Cryptographic Provider v1.0";csptype=rsa_full;hashalg=sha1</signformat> <signer>Jane D Smith, jsmith@insurance.com</signer> <signature>PAGE1.empSignature</signature> <signitemrefs content="array"> <ae>omit</ae> <ae>PAGE1.mgrSigButton</ae> <ae>PAGE1.admSigButton<ae> <ae>PAGE1.empSignature</ae> <ae>PAGE1.mgrSignature</ae> <ae>PAGE1.admSignature</ae> </signitemrefs> <signoptions content="array"> <ae>omit</ae> <ae>triggeritem</ae> <ae>coordinates</ae> </signoptions> <mimedata>MIIFMgYJKoZIhvcNAQcCoIIFIzCCBR8CAQExDzANBgkg AQUFADALB\ngkqhkiG9w0BBwGgggQZMCA36gAwSRiADjdhfHJl 6hMrc5DySSP+X5j\nANfBGSOI\n9w0BAQQwDwYDVQQHEwhJbn< Rlcm5ldDEXMBUGA1UEChM\nOVmVyaVNpZ24sIEluYy4xNDAKn 1ZlcmlTaWduIENsYXNzIDEgQ0Eg\nLSJbmRdWFsIFN1YnNjcmliy ZXIwHhcNOTgwMTI3MwMDAwOTgwM\M1OTU5WjCCARExETA </mimedata> </signature>
Creates space between items on a form. It can be any size specified. It is invisible.
fontinfo, itemlocation, label, size
A spacer can be sized either by giving it length and width dimensions (using size), by expanding the default size using the itemlocation option or by giving it a label. If a label is used, the spacer equals the size of the text typed into the label. The label does not appear; it is simply used to determine the spacer’s size.
When setting the size option of a spacer, the height and width of the spacer will be based on the average character size for the font in use (set with the fontinfo option).
This example shows a spacer item that uses the size option to define the amount of space it will occupy.
<spacer sid="3_SPACER"> <size content="array"> <ae>1</ae> <ae>3</ae> </size> </spacer>
This example shows the spacer item that uses a label to define the amount of space it will occupy. This sizing technique is useful when creating a spacer that is exactly the same size as a real label on the form.
<spacer sid="WELCOME_SPACER"> <label>Welcome to Information Line</label> </spacer>
Allows the definition of a toolbar for a page. A toolbar is a separate and fixed area at the top of the page. It functions much like a toolbar in a word processing application. Typically, items placed in the toolbar are those users are to see no matter what portion of the page they are viewing.
The toolbar is visible no matter what portion of the page body is visible. However, if the toolbar is larger than half the form window, it is necessary to scroll to see everything it contains.
bgcolor, mouseover
The background color of the toolbar becomes the default background color for items in the toolbar.
Add items to the toolbar using the within modifier of the itemlocation option. Code the itemlocation option in each included item’s definition.
This example shows a toolbar that contains a label, a spacer, and two buttons.
Here is the toolbar definition:
<toolbar sid="TOOL_BAR"> <bgcolor content="array"> <ae>cornsilk</ae> </bgcolor> </toolbar>
Here is an item that will appear in the toolbar.
<label sid="COMPANY_NAME"> <value>My Company</value> <itemlocation content="array"> <ae content="array"> <ae>within</ae> <ae>TOOL_BAR</ae> </ae> </itemlocation> </label>
Allow form designers to add application specific information to the form definition. This is useful when submitting forms to applications requiring non-XFDL information. An example of non-XFDL information might be an SQL query statement.
All XFDL options and any custom options can be used with custom items.
The naming conventions for a custom item are as follows:
It must begin with an alphabetic character.
It must contain characters only from the following list: A-Z, a-z, 0-9 and underscore.
It must contain an underscore.
This is an example of a custom item definition. It includes both an XFDL and a custom option.
<ma_event sid="STATUS_EVENT"> <active>off</active> <ma_id>UF45567 /home/users/preferences01</ma_id> </ma_event>
For simple character data content:
<optionTag>content</optionTag>
For computed options:
<optionTag content="compute"> <cval>current value data</cval> <compute>expression</compute> </optionTag>
For array options:
<optionTag content="array"> <!suboption elements --> </optionTag>
An option defines a characteristic given to a form, a page, or an item. For example, a fontinfo option set at the form global level defines the default font characteristics for the entire form. A fontinfo option set at the item level defines the font characteristics for only the item it is in.
The definition of an option consists of content between start and end tags. The element tag defines the type of option. This type must be one of the option types defined in this specification, or a user-defined option that follows the rules in the "custom option" description in this specification.
The content of an option can take one of three formats: simple character data, a compute, or an array of subordinate XML elements. The content attribute identifies which type of content will appear.
The default is simple, and the content attribute is not required if the content is simple, in which case the option must contain text with no child elements. For example:
<value>This is the value</value>
If the content expresses a compute, then the content attribute must be present and be set equal to "compute". The option may contain a cval element, which should contain simple character data for the current computed value of the option. If the cval element is absent, XFDL defines this to be equivalent to the presence of <cval></cval>. The option must contain a compute element. The compute element should contain a computational expression. For example:
<value content="compute"> <cval></cval> <compute> price1Field.value+price2Field.value*"0.07" </compute> </value>
It is typical to have a form run its computes on a client machine, then have server modules simply read the current values, ignoring the content of the compute element. In essence, an application can treat the compute content as character data unless it must run the computes. See Section 3 for details on how the compute expression is represented.
The third case for an option's content is an array of subordinate elements. In this case, the content attribute is required and must be set equal to "array". The option must contain one or more array elements. For example:
<bgcolor content="array"> <ae>255</ae> <ae>248</ae> <ae>220</ae> </bgcolor>
The array element takes the same content attribute that option elements do, and its contents are controlled by the value of this attribute in the same way. This recursive definition permits arbitrary depth for XFDL arrays.
In XFDL, the form developer is permitted to give names other than ae to array elements. The default array element name is ae, but a name can be assigned even if XFDL does not define it. For example,
<bgcolor content="array"> <red>255</red> <green>248</green> <blue>220</blue> </bgcolor>
A number of the XFDL-defined options use array elements. XFDL does not often assign names to the array elements, so the default tag name of ae is used.
An option set at a lower level in the form hierarchy overrides a similar option set at a higher level. It overrides it for only the level it is in and any that come below it in the hierarchy. For example, the fontinfo option in the following example would override a global fontinfo setting for the page it is in, and also for any items in that page.
<page sid="Page1"> <fontinfo content="array"> <ae>Helvetica</ae> <ae>12</ae> <ae>plain</ae> </fontinfo>
Form global options are optional and must be defined after the XFDL start tag, but before the first page in a form. Page global options are optional and must be defined after the page declaration, but before the first item in a page. To determine whether an option is a valid form global or page global option, see that option's description later in this specification.
XFDL defines a set of data types that describe type of content allowed in an option. Each option description in this specification uses one or more of the following data type designators:
Data Type Description char a single ASCII character string a series of ASCII characters color a color name or an RGB triplet representing the color · The syntax of an RGB triplet is:
<bgcolor content="array">
<ae>red</ae>
<ae>green</ae>
<ae>blue</ae>
</bgcolor>
For example, the triplet for green is:
<ae>0</ae>
<ae>255</ae>
<ae>0</ae>coordinate whole number in the range 0 to 1,000 representing one coordinate of a position integer positive or negative whole number in the range -32,768 to 32,767 long int whole number in the range 0 to 2,147,483,647 short int whole number in the range 0 to 255 unsigned whole number in the range 0 t