HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 00:09:04 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Mon, 27 Apr 1998 14:29:00 GMT ETag: "2e9a51-56d4a-3544962c" Accept-Ranges: bytes Content-Length: 355658 Connection: close Content-Type: text/plain INTERNET DRAFT David Manning, Richard Bennett, John Boyer, Sonja McLellan, Michael Mansell February 1998 Expires: August 04, 1998 Universal Forms Description Language Specification Version 4.0 Status of this Memo This document is an Internet-Draft. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsolete by other documents at any time. It is inappropriate to use Internet-Drafts as reference materials or to cite them other than as "work in progress." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), orftp.isi.edu (US West Coast) Abstract The Universal Forms Description Language (UFDL) describes complex business forms for use over the Internet. The objective of the UFDL is to enable the creation of cross-platform Internet business forms that (1) contain both the complex logic and precise layout that administrators require, (2) are simple to maintain and distribute, and (3) integrate easily with existing business systems. As more and more business is done over the Internet, the need for a form description language that incorporates these features grows. HTML is designed for Internet pages, and is severely limited as a form language. This document specifies the vocabulary, syntax, and meaning of the UFDL. CONTENTS PREFACE: UFDL DOCUMENTATION 1 1. INTRODUCTION 4 1.1 Introduction to the UFDL 4 1.2 UFDL Documentation 5 1.2a How This Document is Organized 5 1.2b Other UFDL Documentation 6 1.3 Requirement Levels for UFDL Elements 6 1.4 Implied Semantics for UFDL Viewers 7 1.5 Security Considerations 8 Universal Forms Description Language [page 1] 1.6 Responding to Errors in the Form Descriptions 8 2. THE UNIVERSAL FORMS DESCRIPTION LANGUAGE 9 2.1 What is the UFDL? 11 2.2 Features of UFDL Forms 11 2.3 Description of a UFDL Form 13 2.3a What is a Page? 13 2.3b What is an Item? 15 2.3c What is an Option? 16 2.3d Including External Files 16 2.3e Unrecognized Items and Options 17 2.4 Syntax of the UFDL 17 2.4a Basic Syntax Rules 17 2.4b Form Definition 17 2.4c Page Definition 18 2.4d Item Definition 19 2.4e Item Size 20 2.4f Item Placement 21 2.4g Toolbar Definition 22 2.4h Option Definition 23 2.4i Literals 23 2.4j References to Other Options 24 2.4k Dynamically Created Options 25 2.4l Operations 27 2.4m Arrays 30 2.4n Defining Tabbing and Paging 31 2.4o Including External Files 35 2.5 UFDL Language Elements 35 2.5a Identifiers 35 2.5b Custom Item Types and Custom Option Names 36 2.5c Reserved Words 36 2.5d Quoted Strings 36 2.5e Binary Data 37 2.5f Comments 37 2.5g Security 37 2.5h Filters 40 2.6 Processing Forms 42 2.6a Include Statements 42 2.6b Expressions 42 3. UFDL GLOBAL AND PAGE SETTINGS 42 3.1 Global Settings 43 3.2 Page Settings 44 4. UFDL FORM ITEMS 46 4.1 action 46 4.2 box 49 4.3 button 50 4.4 cell 53 4.5 check 55 4.6 combobox 57 4.7 data 59 4.8 field 60 4.9 help 63 4.10 label 64 4.11 line 65 Universal Forms Description Language [page 2] 4.12 list 66 4.13 popup 69 4.14 radio 72 4.15 signature 74 4.16 spacer 76 4.17 tablet 77 4.18 toolbar 79 4.19 81 5. UFDL FORM OPTIONS 81 5.1 active 84 5.2 bgcolor 85 5.3 bordercolor 86 5.4 borderwidth 86 5.5 coordinates 87 5.6 datagroup 88 5.7 delay 89 5.8 editstate 90 5.9 filename 91 5.10 fontcolor 91 5.11 fontinfo 92 5.12 format 93 5.13 group 99 5.14 help 100 5.15 image 100 5.16 itemlocation 101 5.17 justify 109 5.18 label 109 5.19 labelbgcolor 110 5.20 labelbordercolor 111 5.21 labelborderwidth 112 5.22 labelfontcolor 112 5.23 labelfontinfo 113 5.24 mimedata 114 5.25 mimetype 114 5.26 next 115 5.27 previous 116 5.28 printsettings 118 5.29 saveformat 119 5.30 scrollhoriz 122 5.31 scrollvert 122 5.32 signature 123 5.33 signdatagroups 124 5.34 signer 124 5.35 signgroups 125 5.36 signitemrefs 126 5.37 signitems 127 5.38 signoptionrefs 128 5.39 signoptions 129 5.40 size 129 5.41 thickness 131 5.42 transmitdatagroups 131 5.43 transmitformat 133 5.44 transmitgroups 136 5.45 transmititemrefs 137 Universal Forms Description Language [page 3] 5.46 transmititems 139 5.47 transmitoptionrefs 139 5.48 transmitoptions 141 5.49 triggeritem 142 5.50 type 142 5.51 url 144 5.52 value 145 5.53 version 146 5.54 147 6. UFDL FORM VIEWER DIRECTIVE 147 6.1 #include 148 6.2 #optinclude 149 APPENDIX A: QUICK REFERENCE TABLES 150 A.1 Table of Items and Form and Page Characteristics 150 A.2 Table of Options 150 APPENDIX B: DEFAULT SIZES 157 APPENDIX C: UFDL FOR C AND C++ PROGRAMMERS 159 C.1 Procedural vs. State Language 159 C.2 Globals and Functions (Pages) 160 C.3 References and Dynamic Option Reference 161 C.4 Arrays 162 C.5 Assignment 162 APPENDIX D: GLOSSARY 163 ------ 1. INTRODUCTION 1.1 Introduction to the UFDL This document specifies the Universal Forms Description Language (UFDL), which describes complex business forms for use over the Internet. The objective of the UFDL is to enable the creation of cross-platform Internet business forms that (1) contain both the complex logic and precise layout that administrators require, (2) are simple to maintain and distribute, and (3) integrate easily with existing business systems. This document specifies the vocabulary, syntax, and meaning of the UFDL. Since more and more business is being done over the Internet, the need for a form description language that incorporates the complexities of business systems is growing. Typically, an electronic business form is part of a process-intensive administration system. Users or server modules populate forms with data, the forms are distributed according to a work flow plan, and the data is stored in a database (or, in departments that have no complete electronic solution, the form is printed for storage). The forms, which can contain hundreds of input items, need to validate the data they receive, perform calculations and other logical operations, and integrate with existing data management systems. Universal Forms Description Language [page 4] Today, most Internet forms are inadequate and are being created with HTML. HTML is designed for the easy display of Internet pages. As a result, HTML is very good at creating the layout for web sites and has become the standard for web pages. Web designers and IS organizations are now trying to push HTML beyond what it was intended to do. HTML forms work well for collecting basic information over the Internet. However, most business forms are much more complex than the typical HTML order form. HTML was not designed to collect, validate, manipulate, or store information. In order to build significant intelligence into an HTML form, a developer has to use JavaScript. Business forms also may need to travel through nodes in distribution chains, being viewed or changed by people along the way. HTML forms submit merely the data they've collected-the user interface and intelligence don't accompany it, and so make it difficult to create a workflow system for the form. HTML forms also have a fairly inflexible layout, and it's impossible to create precise, complex HTML forms and print them the way people are used to. The UFDL was designed specifically for Internet business forms. It describes all components of a complex form: user interface, intelligent features, and input data. A UFDL form can be transmitted whole or in part from node to node in a distribution chain. The UFDL's precise layout specifications allow users to create and print forms that replicate the paper forms they're used to. The UFDL includes complex business logic so that intelligent features like user-input checking, calculations, and in-form decisions are part of the form itself, rather than a separate script, and travel with the form to the next user. The UFDL allows developers to extend the language to interface with other applications by adding their own customized information to forms. The syntax of the UFDL is high-level and easy to learn, but at the same time incorporates the logic needed for business transactions. C and Java programmers will recognize many features of the syntax. 1.2 UFDL Documentation This section outlines how this document is organized, and directs readers to other documents on the Universal Forms Description Language for further information. 1.2a How This Document is Organized The UFDL Specification is intended both for an academic audience and for form developers and people writing applications that use UFDL forms. For an introduction to the language and its elements, see Part 2: Introduction to the Universal Forms Description Language. It explains the concepts behind the UFDL and specifies the components of a UFDL form. It delineates the UFDL syntax and explains the Universal Forms Description Language [page 5] language elements. For a full description of form global settings, form items, form options, and directives for form viewers, see parts 2, 3, 4, and 5. For the Backus-Naur Form (BNF) of the UFDL, see 'Appendix A: Grammar of the UFDL'. C Programmers may find it useful to review 'Appendix B: UFDL for C and C++ Programmers'. 1.2b Other UFDL Documentation Those who want a hands-on introduction to making UFDL forms may want to download the Guide to Making UFDL Forms. It contains tutorials for making a simple form and for making a multiple-page form that contains advanced features, like decision logic, error checking and formatting, time-saving features, and more. Those who want to find out more about the grammar behind the UFDL may want to view or download the Lexical and Syntactical Specification for the UFDL. Both of these documents are available at http://www.uwi.com/UFDL 1.3 Requirement Levels for UFDL Elements This specification does not contain extraneous material, and therefore most implementers of the UFDL will want to include all elements specified here. However, not all elements are required, though all are suggested. This section specifies which elements are REQUIRED, RECOMMENDED, and OPTIONAL in an implementation. The criterion for determining whether an element of the language is REQUIRED is whether the exclusion of the element would prevent people from filling and transmitting the form. Unless specified in the list below, all elements are REQUIRED. An implementation that does not include an element MUST interoperate with another implementation that does include the element (though perhaps with reduced functionality). In the same vein, an implementation that does include the element MUST interoperate with one that does not (except, of course, for the feature the element provides). Also, before deciding to ignore an element that is RECOMMENDED, an implementor must understand the implications of not including the element. RECOMMENDED Elements (Elements that implementors SHOULD include) - bgcolor option - fontcolor option - labelbgcolor option - labelfontcolor option - next option - previous option - printsettings option OPTIONAL Elements (Elements that implementors MAY include) - help item - bordercolor option Universal Forms Description Language [page 6] - borderwidth option - help option - labelbordercolor option - labelborderwidth option - #include directive Note: For a definition of the words REQUIRED, RECOMMENDED, OPTIONAL, MUST, SHOULD, and MAY as used in this section, see RFC 2119. 1.4 Implied Semantics for UFDL Viewers There are a few behaviors that are "implied" but not explicit in the UFDL, and that are defining features of the UFDL. This section outlines those behaviors, and should be considered part of the UFDL Specification. Temporary Files A viewer that uses UFDL forms may create temporary files in the following locations: - web browser's temp directory - Windows temp directory - viewer's temp directory A viewer MUST NOT create temporary files in any other location on a user's computer. This prevents system files or permanent user files from being at risk if they're not in temp directories. A viewer may delete files from the three temporary directories listed above at its discretion, but it MUST delete ONLY files that are older than the last reboot of the operating system, or that it can positively identify as one of its own temporary files. The following UFDL form events may cause a UFDL viewer to create and/or delete temporary files: Opening a form; Closing a form; Submitting a form (a transaction of type "submit" or "done"); Emailing a form (if a viewer supports emailing forms); Enclosing files; Displaying enclosures. Permanent Files Certain UFDL form operations require a viewer to read or create permanent files. They are: Enclosing a File; Extracting a File; and Saving a form. Only button and cell items can initiate these operations. Automatic actions MUST NOT initiate actions that create permanent files on a user's computer. When a viewer performs an enclose, extract, or save operation, it MUST conform to the restrictions that follow. Enclosures: When the user activates an enclose button or cell, the viewer must prompt the user with a file browser so that the user can choose which file to enclose. This file browser must allow the user to cancel the enclose transaction without writing the enclosure into the form. Users may choose to enclose any files to which their operating system gives them access. Extractions: When the user activates an extract button or cell, the viewer must prompt the user with a file browser so that the user may choose both a location and a name for the file that's being extracted. Other than the usual restrictions on file names that the user's operating system imposes, the viewer must not restrict the file name the user chooses. If the user specifies a file name that already exists, then the viewer must warn the user that it exists, and ask the user whether to overwrite the existing Universal Forms Description Language [page 7] file. The user must be able to cancel the extract operation before the viewer has written the permanent file. Saves: When the user activates a save button or cell, the viewer must prompt the user with a file browser so that the user may choose both a location and a name for the saved form. (Save acts like "Save As".) Other than the usual restrictions on file names that the user's operating system imposes, the viewer must not restrict the file name the user chooses. If there is already a file with the file name that the user specifies, then the viewer must warn the user that it exists, and ask the user whether to overwrite the existing file. The viewer must allow the user to cancel the save operation before the viewer has written the permanent file. These rules have been created in order to allow users to perform the enclosures, extractions, and saves necessary when completing business forms, while at the same time protecting their computers by (a) limiting temporary files to temp directories, and (b) preventing uploads and downloads that users are not aware of. 1.5 Security Considerations The UFDL specifies the description of a form, but not the transport protocol for transmitting it. Any trasmission security issues that exist for the transport protocol submitting the form (for example, those used by mail programs and web browsers) exist when transmitting a UFDL form. (Note, however, that UFDL forms can be compressed using a compression algorithm before they are submitted. For more information, see the transmitformat option description.) UFDL forms cannot invoke programs on local computer drives. In addition, a UFDL viewer must save temporary files to standard temp directories only, as outlined in '1.4 Implied Semantics' above. A UFDL Viewer may only read and write permament files under strict conditions and then only with the user's knowledge (through presenting a file browser); see '1.4 Implied Semantics' for more information. 1.6 Responding to Errors in the Form Description Any UFDL form interpreter must parse a UFDL form for non-compliance to the UFDL specification. This debugger should treat non-compliances in the following manner: Flag as Warnings - All item types and option types that are not part of the UFDL. These must be flagged as warnings and not as errors because the UFDL allows developers to create custom items and options for inserting application-specific information into forms. Forms containing non-compliances that generate warning messages may still be displayed. The non-compliances must be ignored when displaying the form, and the defaults used instead (if applicable). A UFDL Viewer may implement a mechanism that allows users to turn off the warning messages. Flag as Errors - Anything that might (but also might not) adversely affect the appearance or functionality of the form. Forms that Universal Forms Description Language [page 8] contain non-compliances that might affect the appearance or functionality of the form may be displayed. The non-compliances must be ignored, and the defaults (if applicable) must be used when displaying the form. Flag as Fatal Errors - Anything that will adversely affect the appearance or functionality of the form. Forms containing non-compliances that generate fatal error messages must not be displayed. In addition, the UFDL debugger must check the version number of the form it parses. The version number denotes which version of the UFDL specification the form complies with. The parser must check for non-compliances based on the version of the UFDL that the form was written with. This provides backwards compatibility. ------ 2. Introduction to the Universal Forms Description Language 2.1 What is the UFDL? Summary The Universal Forms Description Language (UFDL) is a language that describes complex electronic business forms much the way HTML describes web pages. It is cross-platform, easy to learn, and its features are tailored to business needs. Note: Because UFDL version 4.0 includes the start value element in an option name, any code written to work with the UFDL BNF version 3.3.1 or earlier will not be able to parse a version 4.0 form. Details The UFDL is a platform-independent, high-level language that describes electronic business forms. It was designed specifically for creating forms that are capable of replacing paper forms systems. That is, it creates forms that: - Create auditable records, by viewing a form as an object that includes layout instructions and data, and that can be passed whole from node to node in a distribution chain, archived, and retrieved later for verification. - Let users work offline or online. - Perform logical operations. - Give users editing and error checking tools. - Allow users to digitally sign the whole form or parts of the form. - Appear the same on any platform and under any screen resolution and system font size. - Interface with other applications. The UFDL incorporates the following design concepts: Familiar Syntax The UFDL is easy to pick up, because it is syntactically similar to Universal Forms Description Language [page 9] two industry standard programming languages: C++ and Java. Here is the description of a very simple UFDL form: version = "3.2.0"; page_1 = new page { body_label = new label { value = "This is a UFDL form."; } } Essentially, the form consists of one or more pages. A page contains zero or more items, like the label item in the example above. The items can be made from item types that are part of the UFDL (labels, buttons, fields, automatic actions and so on), or from item types form designers create themselves. Pages and item types have certain default characteristics that form developers can modify by specifying various options. Declarative Language Statements in a UFDL form description are always maintained as being true, much as formula fields in a spreadsheet are maintained as true. The simplest example of this is a total field that adds up the contents of various dollar fields in a form. If one of the dollar fields changes,so does the total field. What makes the UFDL different from languages like C++ and Java in this respect is that the constant evaluation of dependencies is inherent in the language. A UFDL form requires no special procedures to be written in order to run evaluations; the evaluations run automatically whenever dependent data changes. Extensible Syntax The UFDL was designed to be easily extensible for both form developersand the creators of the UFDL. - Form developers can create their own item and option types within forms (although currently they cannot set up inherited attributes for each type they create). - The authors of the UFDL can add new features to each new version of the UFDL. Open Protocol The UFDL is an open protocol. This gives developers the freedom to manipulate UFDL forms any way they want. Scripts can be written to dynamically create forms, modify forms, or extract specific information from forms. UFDL forms can themselves make requests to databases and populate themselves with the information returned. This flexibility allows developers to integrate UFDL forms into any application. People with knowledge of C or C++ may wish to refer to Appendix C: UFDL for C and C++ Programmers. This appendix outlines the UFDL's Universal Forms Description Language [page 10] similarities to those languages. ------ 2.2 Features of UFDL Forms A UFDL form looks and behaves just the way you imagine an electronic form should. It can contain graphical elements, modifiable fields, and action items. You can organize a UFDL form into pages similar to the pages in a paper form and you can include navigational aids such as toolbars, tabbing instructions, and scroll bars. In addition, you can code the form to make logical decisions, to interface with otherapplications, and to automatically format and check user's entries. A desktop form viewer application displays the forms. This UFDL form viewer allows users to enter input, enclose and view external files, and print and save forms. When it is convenient, the user can perform a simple action, such as pressing a button, to submit the completed form to an application for processing. Some of the features that make UFDL forms ideal for every-day business use are outlined here. Versatile Form Design The UFDL is very versatile. It provides many features you can use to customize both the appearance and functionality of your form. Absolute and Relational Positioning Schemes The UFDL supports both an absolute positioning scheme and a relational positioning scheme. The absolute positioning scheme allows a form designer to place visible form items in fixed locations on a form. This is useful for beginners and for GUI design applications that use a drag-and-drop method for designing forms. But an absolute positioning scheme is not a cross-platform solution. Used in conjunction with relational positioning, however, it can create modularized blocks of a form that can be easily moved around. The UFDL's relational positioning scheme allows designers to create forms that appear the same on any platform. It aligns visual elements in relation to other visual elements on the form, ensuring forms look consistent on all computers and at all screen resolutions. If an item changes size-either to accommodate a dynamically created value or a system font size-items aligned to it will shift in relation to it. This relational positioning scheme is flexible, giving developers freedom to create original layouts. Support for User-Defined Objects The UFDL lets designers define their own form objects. These objects have no visible properties and initiate no actions, which means that form developers can store specialized information in the form without harming its appearance or behavior. A form viewer application respects references to custom objects in the form Universal Forms Description Language [page 11] definition, allowing a custom object to accumulate information and also allowing other elements in the form to be altered according to the custom object's contents. Input and Format Control The UFDL permits form designers to specify an item's availability, edit state, and input and output formats. This means the form can perform much of the data checking and formatting typically performed by form processing applications. Digital Signatures Version 4.0 and higher of UFDL supports digital signatures, for secure, tamper-proof documents. Digital signatures are incorporated into the description of the form, and allow the developer to specify that a user may sign the entire form or parts of the form. In addition, multiple users may sign a form. Automatic Actions The UFDL supports automatic timed behavior activated by the form. Forms can automatically cancel themselves, submit themselves to a server for processing, open new forms, and upload information to a server. The ability to perform automatic actions provides a mechanism that form designers can use to create stated connections with other applications. An application typically requiring a stated connection is a database\management system. Logical Operations and Arithmetic Computations The UFDL uses a set of options to describe a form object's appearance and behavior. For example, the option bgcolor describes an object's background color. The UFDL permits form designers to use literal values or logically computed values (called computations) to determine the value of an option. These computations are resolved when the form appears. You can nest computations, employ complex mathematical operations, populate and use arrays, and make decisions. Computations provide designers with a very powerful and sophisticated tool for customizing forms to the needs of individual users and applications. It takes very little code (one line per logical computation) and it allows decisions regarding a form's appearance and behavior to occur at run-time. Stand Alone Definitions All aspects of a form's appearance, behavior, and content are integral to the form definition. Therefore, unless you specify otherwise, the entire form definition and the user data travel with the form when a user submits it for processing. Consequently, you can transmit any UFDL form to any site with a UFDL-compliant form Universal Forms Description Language [page 12] viewer application and the viewer will display the form correctly. The only exception to this rule occurs when the form design specifies partial submission of forms. The UFDL permits form designers to specify partial submissions in one of two ways: - by specifying which parts to transmit - by specifying HTML format Partial submissions help reduce network traffic and transmission time. Context Sensitive Help The UFDL provides a mechanism whereby form designers can define help messages for individual items in the form. Help messages appear in a window overlaying the form. Enclosures Users can enclose external files in UFDL forms. They can organize the files into folders, and they can display, copy, or remove the files. Enclosed files are encoded using the base64 encoding technique. The UFDL includes a MIME type with an enclosed file's description. This allows form viewer applications to choose an appropriate viewer (for example, World Wide Web browser, word processor, etc.) when displaying enclosures. ------ 2.3 Description of a UFDL Form A UFDL form is a collection of items (for example, buttons, labels, amd fields) organized into pages. There are items to display fixed values, items to collect user input, items to initiate actions, and items to assist with form navigation. The decision about which items to place on a page and how many pages to include in the form is application dependent. The UFDL provides a set of options for assigning characteristics to the form and to its pages and items. These include such things as the behavior, appearance, and location of an item. The UFDL defines default settings for many of these options, or you can define your own settings in the form. The following example describes a simple two-page form: For information on the syntax rules of a form description, see 'Syntax of the UFDL' on 2.4b. ------ 2.3a What is a Page? A form page is similar to a page in a paper form. Each page consists of its own set of items. You can place any number and type of items on a page. The number of items, their sizes, and their Universal Forms Description Language [page 13] locations determine the size of the page. In some senses, pages act like independent forms. They have their own size, appearance, toolbars, and characteristics. As well, relational positioning of the page's items is based solely on other items on the same page. The following example shows a page containing a label and a button: For more information on the syntax rules of a page description, see 'Syntax of the UFDL' on 2.4b. Relational and Absolute Positioning The UFDL supports two positioning schemes for creating a page image: relational and absolute positioning. In the relational positioning scheme, each item's location depends on the location and size of one or more other items on the page. For example, a field might be below and slightly to the right of a label. A series of buttons might be placed to appear one after the other. In the absolute positioning scheme, each visible item is anchored to a particular coordinate on the page drawn on the computer screen. Each coordinate represents a distance in pixels from the top left corner of the page. In addition, a form designer using absolute positioning can offset items from other items. Absolute positioning is useful for graphic form design programs because it allows users to drag and drop items on a form. It is not a good cross-platform positioning scheme, although when used carefully in conjunction with relational positioning, it can be successful. Relational positioning provides cross-platform compatibility in UFDL form designs, because all visible items are placed relative to each other. Therefore, if any item's size changes because of a change in font size or a dynamically generated value, other items on the form will shift to accommodate it, while maintaining their positions relative to each other. For more information, see 'Item Placement' on 2.4f, and the item location option description, on . Toolbars The toolbar is a separate and fixed area at the top of a page. It functions much like a toolbar in a word processing application. Typically, you place items in the toolbar that you want users to see no matter what portion of the page they are viewing. Toolbars are optional and each page has its own toolbar. The toolbar and the remainder (or body) of the page operate independently of one another. Both are scrollable, and scrolling one does not scroll the other. The toolbar can also have different characteristics than the page body, and relational positioning of Universal Forms Description Language [page 14] toolbar items is based solely on other items on the same toolbar. ------ 2.3b What is an Item? Items are the basic elements of a page. Just as paper forms consist of items like lines, boxes, and instructions, UFDL forms consist of items like lines, boxes, text fields, labels, buttons, and so on. There are two categories of items: - external - internal or hidden A page can include both categories of items. External items occupy space on the page. They can be either visible or invisible. Visible items are things users see like labels and buttons. Invisible items are things like spacers that create white space on the form. Internal items are invisible and occupy no space; instead they trigger form actions or store data used by other items. Action and data items are examples of internal items. An action item initiates a transmission, while a data item contains data stored in the form. Each type of item has default characteristics. For example, all fields will be a certain length and color unless the form developer specifies otherwise. A form developer can modify an item's default characteristics by adding options to its definition. For example, the field described below on the left would have a default appearance of 60 characters long and one row high (as well as having other default characteristics). On the right, the size option added to its description overrides that default size. date_field = new field { } date_field = new field { size = ["20", "1"]; } Field using default characteristics only Modified size overriding the default size There are defaults for most item characteristics. If the defaults meet your requirements, an item definition may include only the instance identifier, a unique item tag. Instance identifiers are mandatory. They are critical to the relational positioning scheme. For that reason, the UFDL incorporates the identifier into the syntax of an item definition. An item's definition includes: - An instance identifier (an item tag that uniquely identifies it). - An open brace following the item declaration. - A close brace at the end of the definition (after the options, Universal Forms Description Language [page 15] if there are any). - Optional information giving the item characteristics, including its position on the page, graphical characteristics and size, initial value and edit state, and instructions for handling the item when the form is submitted. Because these characteristics are optional, the lines that specify them are called options. Here is a sample of an item description: For more information on the syntax rules of an item's description, see 2.4b 'Syntax of the UFDL'. ------ 2.3c What is an Option? An option defines one characteristic of a form, a page, or an item. There are options to specify each aspect of the appearance and behavior of your form. Some options apply to the entire form, others apply only to items, and still others apply to pages or items. The example below shows options giving characteristics to an entire form, to a page, and to a particular item. version = "3.2.0"; bgcolor = ["ivory"]; page_1 = new page { ... page_1 = new page { bgcolor = ["seashell"]; bar_box = new box { ... bar_box = new box { bgcolor = ["black"]; size = ["60", "5"]; } ... Options that appear at the top of the form, like the example on the far left, are called global settings. They apply to the whole form. Options that appear at the top of a page, like the example in the center, are called page settings. They apply to the entire page. Page settings override any similar global settings-but only for the page on which they occur. Options within items, like the example on the far right, apply only to the item whose description they are in. ------ 2.3d Including External Files The UFDL #include statement allows you to include external files in your form definition much as you would include header files in a C Universal Forms Description Language [page 16] language source file. The form viewer application replaces the #include statement with the contents of the file you specify. The included file must reside in a secure include directory accessible to the form viewer application. 2.3e Unrecognized Items and Options User-Defined Items and Options and Newer UFDL Items and Options As a UFDL form viewer parses a form, it ignores items and options it does not recognize. This feature has a number of advantages. - It allows a form designer to include items and options for new form viewer applications without affecting the form's behavior in other viewers. - Form processing applications can use the custom items and options when processing the form. One example of a custom item might be an SQL query item the application uses to populate a response form. Unrecognized items and options include: - User defined (or custom) items and options - Items and options from releases of the UFDL that are newer than the user's form viewer application understands ------ 2.4 Syntax of the UFDL 2.4a Basic Syntax Rules The basic syntax rules of the UFDL are: - It is case sensitive. - It ignores white space around and within statements. - It permits multiple line statements. - It permits multiple statements per line. ------ 2.4b Form Definition The syntax of a UFDL form definition is as follows: *