Universal Forms Description Language Specification From: http://info.internet.isi.edu/in-drafts/files/draft-gordon-ufdl-spec-02.txt Date: 1998-10-07 INTERNET DRAFT David Manning, Richard Bennett, John Boyer, Sonja McLellan, Michael Mansell August 1998 Expires: February 04, 1999 Universal Forms Description Language Specification Version 4.0.1 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), ftp.ietf.org (US East Coast), or ftp.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 1. INTRODUCTION 1.1 Introduction to the UFDL 1.2 UFDL Documentation 1.2a How This Document is Organized 1.2b Other UFDL Documentation 1.3 Requirement Levels for UFDL Elements 1.4 Implied Semantics for UFDL Viewers 1.5 Security Considerations 1.6 Responding to Errors in the Form Description Universal Forms Description Language [page 1] 2. INTRODUCTION TO THE UNIVERSAL FORMS DESCRIPTION LANGUAGE 2.1 What is UFDL? 2.2 Features of UFDL Forms 2.3 Description of a UFDL Form 2.3a What is a Page? 2.3b What is an Item? 2.3c What is an Option? 2.3d Including External Files 2.3e Unrecognized Items and Options 2.4 Syntax of UFDL 2.4a Basic Syntax Rules 2.4b Form Definition 2.4c Page Definition 2.4d Item Definition 2.4e Item Size 2.4f Item Placement 2.4g Toolbar Definition 2.4h Option Definition 2.4i Literals 2.4j References to Other Options 2.4k Relative Page Tags and Item Tags 2.4l Operations 2.4m User Events and Changes of State 2.4n Arrays 2.4o Defining Tabbing and Paging 2.4p Including External Files 2.5 UFDL Language Elements 2.5a Identifiers 2.5b Custom Item Types and Custom Option Names 2.5c Reserved Words 2.5d Quoted Strings 2.5e Binary Data 2.5f Comments 2.6 Security 2.7 Filters 2.8 Processing Forms 2.8a Include Statements 2.8b Expressions 3. UFDL GLOBAL AND PAGE SETTINGS 3.1 Global Settings 3.2 Page Settings 4. UFDL FORM ITEMS 4.1 action 4.2 box 4.3 button 4.4 cell 4.5 check 4.6 combobox 4.7 data 4.8 field 4.9 help 4.10 label 4.11 line Universal Forms Description Language [page 2] 4.12 list 4.13 popup 4.14 radio 4.15 signature 4.16 spacer 4.17 tablet 4.18 toolbar 4.19 5. UFDL FORM OPTIONS 5.1 activated 5.2 active 5.3 bgcolor 5.4 bordercolor 5.5 borderwidth 5.6 coordinates 5.7 data 5.8 datagroup 5.9 delay 5.10 editstate 5.11 filename 5.12 focused 5.13 fontcolor 5.14 fontinfo 5.15 format 5.16 group 5.17 help 5.18 image 5.19 itemlocation 5.20 justify 5.21 label 5.22 labelbgcolor 5.23 labelbordercolor 5.24 labelborderwidth 5.25 labelfontcolor 5.26 labelfontinfo 5.27 mimedata 5.28 mimetype 5.29 mouseover 5.30 next 5.31 previous 5.32 printsettings 5.33 saveformat 5.34 scrollhoriz 5.35 scrollvert 5.36 signature 5.37 signdatagroups 5.38 signer 5.39 signformat 5.40 signgroups 5.41 signitemrefs 5.42 signitems 5.43 signoptionrefs 5.44 signoptions 5.45 size Universal Forms Description Language [page 3] 5.46 thickness 5.47 transmitdatagroups 5.48 transmitformat 5.49 transmitgroups 5.50 transmititemrefs 5.51 transmititems 5.52 transmitoptionrefs 5.53 transmitoptions 5.54 triggeritem 5.55 type 5.56 url 5.57 value 5.58 version 5.59 6. UFDL FORM VIEWER DIRECTIVE 6.1 #include 6.2 #optinclude 7. UFDL FUNCTIONS 7.1 String Functions 7.1a countLines 7.1b replace 7.1c strlen 7.1d strmatch 7.1e strpbrk 7.1f strrstr 7.1g strstr 7.1h substr 7.1i tolower 7.1j toupper 7.1k trim 7.1l URLDecode 7.1m URLEncode 7.2 Math Functions 7.2a abs 7.2b acos 7.2c annuity 7.2d asin 7.2e atan 7.2f ceiling 7.2g compound 7.2h cos 7.2i deg2rad 7.2j exp 7.2k fact 7.2l floor 7.2m ln 7.2n log 7.2o mod 7.2p pi 7.2q power 7.2r rad2deg 7.2s rand 7.2t round Universal Forms Description Language [page 4] 7.2u sin 7.2v sqrt 7.2w tan 7.3 Utility Functions 7.3a applicationName 7.3b applicationVersion 7.3c applicationVersionNum 7.3d decimal 7.3e formatString 7.3f isValidFormat 7.3g set 7.3h toggle 7.4 Time and Date Functions 7.4a date 7.4b dateToSeconds 7.4c day 7.4d dayOfWeek 7.4e endOfMonth 7.4f hour 7.4g minute 7.4h month 7.4i now 7.4j second 7.4k time 7.4l year APPENDIX A: QUICK REFERENCE TABLES A.1 Table of Items and Form and Page Characteristics A.2 Table of Options APPENDIX B: DEFAULT SIZES APPENDIX C: UFDL FOR C AND C++ PROGRAMMERS C.1 Procedural vs. State Language C.2 Globals and Functions (Pages) C.3 References and Dynamic Option Reference C.4 Arrays C.5 Assignment APPENDIX D: GLOSSARY AUTHOR CONTACT INFORMATION 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, Universal Forms Description Language [page 5] 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. 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 Universal Forms Description Language [page 6] 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 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 C: UFDL for C and C++ Programmers'. 1.2b Other UFDL Documentation 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 Universal Forms Description Language [page 7] - labelbgcolor option - labelfontcolor option - next option - previous option - printsettings option OPTIONAL Elements (Elements that implementors MAY include) - help item - bordercolor option - 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 Universal Forms Description Language [page 8] 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 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 Universal Forms Description Language [page 9] 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 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 UFDL? Summary The Universal Forms Description Language (UFDL) is a language that describes complex Internet 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 UFDL is a platform-independent, high-level language that describes Internet 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 Universal Forms Description Language [page 10] 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, functions, and other behavioral changes based on user events. - 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. UFDL incorporates the following design concepts: Familiar Syntax UFDL is easy to pick up, because it is syntactically similar to two industry standard programming languages: C++ and Java. Here is the description of a very simple UFDL form: version = "3.2.0"; bgcolor = ["ivory"]; 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 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 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 UFDL was designed to be easily extensible for both form developers and the creators of UFDL. Universal Forms Description Language [page 11] - 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 UFDL can add new features to each new version of UFDL. Open Protocol 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 D: UFDL for C and C++ Programmers. This appendix outlines UFDL's 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 other applications, 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 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 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. Universal Forms Description Language [page 12] 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 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 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 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 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 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. 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 Universal Forms Description Language [page 13] 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. Functions UFDL functions allow forms to perform procedural logicas well as complex operations that would normally require complicated conditional statements. For details, see 7: UFDL Functions". 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 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. 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 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. 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 Universal Forms Description Language [page 14] 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. 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. 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: version = "4.0.0"; bgcolor = ["ivory"]; page_1 = new page { bgcolor = ["seashell"]; next_page_button = new button { value = "Next Page"; url = ["#page_2.global"]; } } page_2 = new page { fontinfo = ["Helvetica", "14", "plain"]; hello_label = new label { value = "Hello, world."; } } For information on the syntax rules of a form description, see "2.4-Syntax of UFDL" ------ 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 locations determine the size of the page. See the discussions of 'Relational and Absolute Positioning' and 'Item Placement' for more information on this topic. 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. Universal Forms Description Language [page 15] The following example shows a page containing a label and a button: page_1 = new page { bgcolor = ["seashell"]; hello_label = new label { value = "Hello, world."; fontcolor = ["blue"]; } next_page_button = new button { value = "Next Page"; url = ["#page_2.global"]; } } For more information on the syntax rules of a page description, see '2.4-Syntax of UFDL' Relational and Absolute Positioning 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 '2.4f-Item Placement' 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. Universal Forms Description Language [page 16] 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 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. See the section 'UFDL Form Items' in section 4.0 for a description of each item. 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. An instance is a particular occurrence of an item type. For example, a form may have two labels. Each label is an instance of the item type 'label'. 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 { } Universal Forms Description Language [page 17] 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, 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, 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: date_field = new field { size = ["20", "1"]; label = "Today's Date"; format = ["date", "long"]; value = "*"; itemlocation = [["after", "name_field"]]; } For more information on the syntax rules of an item's description, see '2.4-Syntax of UFDL' ------ 2.3c What is an Option? See the section 'UFDL Form Options' in section 4.0 for a description of each 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"]; Universal Forms Description Language [page 18] 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 See the '#include' section in section 2.8a for a description of the '#include' statement. The UFDL #include statement allows you to include external files in your form definition much as you would include header files in a C 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 Universal Forms Description Language [page 19] response form. Unrecognized items and options include: * User defined (or custom) items and options. * Items and options from releases of UFDL that are newer than the user's form viewer application understands. ----- 2.4 Syntax of UFDL 2.4a Basic Syntax Rules The basic syntax rules of 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: *